Controlling QNX helpers logging

Updated: April 19, 2023

Logging using QNX helpers is controlled by a configuration string that specifies a combination of the destination flags, the verbosity of a context, and the message-specific flags.

The destination flags are the base, and the message-specific flags are applied on top. For logging to occur, at least one destination needs to be active and the message severity level needs to satisfy the verbosity requirements of the destinations configured for the specified context.

There are currently four logging destinations: slog, slog2, stdout, and stderr.

Logging configuration syntax

The configuration string uses the following format:

context_name_1:destination[=severity_level,...];
context_name_2:destination[=severity_level,...];
context_nameN:destination[=severity_level,...]

It is made up of a series of key-value pairs separated by a semi-colon (;), without any newlines, spaces, tabs, or separating characters. The key and value are separated by a colon (:). The key is a context name and the value is the configuration to apply to the context. For information about context names, see Setting up QNX helpers logging. You can also specify one of the following reserved context names:

The value part of the key-value pair is itself made up of a series of key-value pairs separated by a comma (,) and the key and value are separated by an equal sign (=). The key specifies a logging destination and the value specifies the severity levels used for the verbosity. Valid destination keys are all, default, slog, slog2, stdout, and stderr. Valid severity level values are all, none, shutdown, critical, error, warning, notice, info, debug1, and debug2.

When the key specifies a logging destination, it is used as an active destination (using its assigned verbosity, if you provide one) for the specified context. However, if the key is prefixed with a tilde (~), it is an inactive destination. Logging can still occur for destinations with this prefix if a log call specifically requests this destination and it meets the verbosity requirements.

The order of contexts and destinations can affect the logging behavior because the configuration is applied from left to right and contexts and destinations can be specified multiple times. The logging configuration that exists prior to making this call is not cleared before configuration updates are applied.

The configuration also applies to contexts that haven't been created yet. When a context is created, the configuration information is looked up and applied to it; otherwise, the context reverts to the default context's configuration.

There cannot be any white space in the configuration.

If there is a parsing error, the function returns an error and does not modify the logging configuration.

Example logging configurations

Preventing applications from making changes to the logging configuration

If the environment variables contain QH_LOG_CONFIG_CTX, a program-specific configuration string (which uses the format QH_LOG_CONFIG_CTX__progname), or both, the library automatically uses them one after the other, starting with QH_LOG_CONFIG_CTX (if it is set and valid) to update the destination flags at startup, before the process enters its main function. The library then prevents that application from making any further changes. This behavior allows system integrators to set up the logging configuration the way they want without the possibility of the application changing it.

For development environments, where the implied locking can cause problems, you can disable the locking behavior by setting QH_LOG_CONFIG_LOCKED to 0.

QH_LOG_CONFIG_CTX__progname

The program-specific environment variable allows system integrators to have system-wide settings in QH_LOG_CONFIG_CTX and program-specific settings in QH_LOG_CONFIG_CTX__progname.

The QH_LOG_CONFIG_CTX__progname environment variable is made up of:
  1. QH_LOG_CONFIG_CTX__ (suffix is two underscores).
  2. The program name as reported by __progname. If the first character or any other characters are non-alphanumeric, they are converted to an underscore. The name is truncated to 63 characters. The case of the characters is preserved. For example, if __progname is 03aB[-t, the environment variable associated with it is QH_LOG_CONFIG_CTX___3_aB__t.

Configuring slog2

System integrators can use the environment variable QH_LOG_CONFIG_SLOG2 or QH_LOG_CONFIG_SLOG2__progname (which uses the same naming convention as QH_LOG_CONFIG_CTX__progname) to configure the set of slog2 buffers that QNX helpers uses. If these environment variables are used, QNX helpers uses only one of them, because having a combined or successive application of multiple slog2 configurations doesn't make sense. It first tries to use QH_LOG_CONFIG_SLOG2__progname, and if it is absent or invalid, it uses the system-wide one if it is present and valid. If neither environment variable is present and valid, it creates three slog2 buffers to use by default:

  • high - For logs with severity levels QH_LOG_SEVERITY_WARNING and above. Its size is four slog2 pages.
  • low - For logs with severity levels below QH_LOG_SEVERITY_WARNING. Its size is eight slog2 pages.
  • default - For slog2 calls made directly through the slog2 API. Not for use with QNX helpers. It sets the specified buffer to NULL, which means use the default buffer. This buffer has a single page.

The configuration string noslog2 completely disables slog2 for QNX helpers logging (i.e., no buffer sets are created and no logging to slog2 happens through QNX helpers).

Registration of the slog2 buffers is delayed until the first QNX helpers log call that logs to slog2 is made, with the following exceptions:

In cases where QNX helpers should configure slog2, the configuration string is a series of key-value pairs separated by a semi-colon (;). Each key-value pair is separated by a colon (:). The key is one of high, low, default, or flags and the value is the configuration:

key1:value1;...;keyN:valueN

Although the order in which sections appear is not important and they are all optional, at least one key-value pair is required. When one isn't specified, QNX helpers uses the default values described above.

The flags key

The flags key specifies a set of slog2 flags to use when registering the slog2 buffer set. By default, QNX helpers doesn't use any flags when it registers the slog2 buffer set. The value for flags is a comma-separated list of flag names. Possible values are:
  • alloc_phys — Equivalent to SLOG2_ALLOC_TYPE_PHYSICAL.
  • alloc_shmem — Equivalent to SLOG2_ALLOC_TYPE_SHMEM.
  • discard_newline — Equivalent to SLOG2_DISCARD_NEWLINE.
For more information on these flags, see slog2_register() in the C Library Reference.

The high, low, and default keys

The high, low, and default keys each represent a slog2 buffer configuration. Their value is a comma-separated list of options. As mentioned above, the high buffer gets the logs with higher severity, low gets those that don't make it to the high buffer, and default gets the logs from slog2 calls that were made directly through the slog2 API (buffer value is NULL). The following buffer configuration options are available:
  • For all sections:
    • pages=XX represents the number of 4 KB pages to allocate for the specified buffer. If this option isn't specified, the default number of pages is used (four for the high buffer, eight for low, and one for default).
  • For the high buffer section:
    • minsev=severity — The severity value represents the severity level at which messages start being logged to the high severity buffer. Messages below this severity go to the low severity buffer. Valid values are: all, none, shutdown, critical, error, warning, notice, info, debug1, or debug2. When none is used, a single buffer logs all messages and there is no low and high buffer. To use none, the pages configuration option for the high buffer must be set to 0. When all or debug2 is used, it also means use a single buffer, but pages must not be 0 for the high buffer. If minsev is not specified, the severity level at which messages start being logged to the high severity buffer is warning.
  • For the high and low buffer sections:
    • isdefault — When the isdefault option is specified, it means that there is no default slog2 buffer for messages logged through slog2 directly. Instead, those messages go to the buffer that has the isdefault option.

White spaces

Do not put any white spaces in the slog2 configuration.

Parsing errors

If there is an error when the slog2 configuration is parsed from QH_LOG_CONFIG_SLOG2, a corresponding message is logged and QNX helpers uses the following default configuration for the slog2 buffers:

  • A high buffer with four pages, minsev is warning.
  • A low buffer with eight pages, a one-page default buffer, and no flags.

Example slog2 configurations

high:pages=5,minsev=notice;low:isdefault;flags:alloc_shmem,discard_newline 
high:minsev=error;default:pages=5 
  • The high buffer gets the default number of pages (four) and is sent all messages with error severity and above.
  • The low buffer gets the default number of pages (eight) and the default buffer gets five pages.