Controlling QNX helpers logging
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 thedefault
key also change. If you usedefault
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 toQH_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 thestdout
destination.
- Set the slog2 verbosity to
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 toQH_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 toQH_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.
- Add slog2 as an active destination to the context
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.
- 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
is03aB[-t
, the environment variable associated with it isQH_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
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.
The high
, low
, and default
keys
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 thehigh
buffer, eight forlow
, and one fordefault
).
- For the
high
buffer section:minsev=severity
— The severity value represents the severity level at which messages start being logged to thehigh
severity buffer. Messages below this severity go to thelow
severity buffer. Valid values are:all
,none
,shutdown
,critical
,error
,warning
,notice
,info
,debug1
, ordebug2
. Whennone
is used, a single buffer logs all messages and there is nolow
andhigh
buffer. To usenone
, thepages
configuration option for thehigh
buffer must be set to 0. Whenall
ordebug2
is used, it also means use a single buffer, butpages
must not be 0 for thehigh
buffer. Ifminsev
is not specified, the severity level at which messages start being logged to thehigh
severity buffer iswarning
.
- For the
high
andlow
buffer sections:isdefault
— When theisdefault
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 theisdefault
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
iswarning
. - 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 withnotice
severity and above. - The
low
buffer gets the default number of pages (eight) and is also used as the default buffer for non-QNX helpersslog2
calls. TheSLOG2_ALLOC_TYPE_SHMEM
andSLOG2_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 witherror
severity and above. - The
low
buffer gets the default number of pages (eight) and the default buffer gets five pages.