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:
- all — the specified configuration applies to all contexts except the
default one.
- default — update the default context with the specified
configuration.
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.
- all — all logging destinations are assigned the value.
- default — the context uses the values from the default context and a
value cannot be specified. When the default context configuration changes, the values
assigned by the default key also change. If you use
default with the default context, the default context reverts back to
the original defaults, as if it was never configured.
- For all other destination keys, the value is optional (omit the equal sign). If no value
is specified, the verbosity for the specified destination does not change.
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
default:slog2=info;all:~stdout=none;qh:stdout=default
- Set the slog2 verbosity to QH_LOG_SEVERITY_INFO for the default context.
- Specify that all other contexts should not use stdout as an active destination
and set its verbosity to QH_LOG_SEVERITY_NONE.
stdout is used only when a log call specifically requests it.
- Specify that the qh context should use the settings from the default context for the stdout destination.
default:slog2=notice,~stderr=error
- Applies to the default context only.
- Add slog2 as an active destination (with verbosity level
QH_LOG_SEVERITY_NOTICE).
- Make stderr an inactive destination and set its verbosity level to
QH_LOG_SEVERITY_ERROR.
- Leave the rest of the destinations and their associated verbosity unchanged.
all:~all=none,slog2=notice,~stderr=error
- Applies to all contexts except the default.
- Make all destinations inactive and set their verbosity to none (i.e., don't log anything).
- Add slog2 as an active destination with verbosity level QH_LOG_SEVERITY_NOTICE.
- Keep stderr inactive but set its verbosity level to QH_LOG_SEVERITY_ERROR.
my_ctx:slog2
- Add slog2 as an active destination to the context my_ctx
without changing its verbosity.
- Leave the rest of the destinations and their associated verbosity unchanged.
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:
- QH_LOG_CONFIG_CTX__ (suffix is two underscores).
- 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:
- Only the default buffer has any buffer pages. In this case, if registration isn't
done early, it never occurs because no QNX helper logs ever go to slog2
(the normal trigger for slog2 registration).
- The configuration string contains early_init, which indicates that the
slog2 registration should not be delayed.
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=X — X 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
- The high buffer gets five pages and is sent all messages with notice severity and above.
- The low buffer gets the default number of pages (eight) and is also used as the
default buffer for non-QNX helpers slog2 calls. The
SLOG2_ALLOC_TYPE_SHMEM and SLOG2_DISCARD_NEWLINE flags
are used.
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.