slogger2

Runs on:

QNX OS

Options:

-C dev_console_buffer_size

Specify the buffer size to use for /dev/console, which provides a general-purpose console logging node. The size is in bytes, but you can specify a (case-sensitive) suffix of k to specify a size in kilobytes. By default, this feature is enabled with a buffer size of 16 KB. To disable it, set the size to 0.

-c out_buffer_size,error_buffer_size

Create a buffer set containing two logging buffers (out and error) with the given sizes, in bytes. You can write to these buffers by opening the following paths for writing:

Path	Buffer
/dev/slog2/critical	error
/dev/slog2/error	error
/dev/slog2/warning	out
/dev/slog2/info	out
/dev/slog2/debug	out

This option creates one log file that's shared by all processes that use slogger2 APIs. Each log line is prefixed with the process ID of the client, in square brackets.

-D slogger2_asinfo_name[:dump_file]

-d slogger2_asinfo_name[:dump_file]

Allow slogger2 buffer sets to be backed against a known range of physical memory, for possible recovery after a warm reset.

The slogger2_asinfo_name argument is the name of the address space memory region in the system page (syspage) that's been set aside for this purpose.

If the pre-reset state of the logs is determined to be intact, it's saved in /dev/shmem/dump_file. The default value of dump_file is slog2phys.

The -d option tries to use physical memory backing only if you pass the SLOG2_ALLOC_TYPE_PHYSICAL flag to slog2_register().

The -D option tries to use physical memory backing for every buffer set. To override this behavior, pass the SLOG2_ALLOC_TYPE_SHMEM flag to slog2_register().

If physical memory is depleted and can't be reclaimed from previous dead processes, then the buffer set is created as a regular shared memory object.

-G verbosity_level

Numeric verbosity override value.

Forces a system-wide verbosity_level override to control logging behaviour. The valid values are:

• -1 — Disable logging, effectively disabling all logging in the system.
• 0 to 7 — The severity or verbosity levels as defined in <sys/slog2.h>.

This affects the behaviour of slog2_set_verbosity() such that the verbosity value will be clipped to the buffer's set verbosity_level when the new verbosity value is bigger.

-g gid1,gid2,...

Add each group in the list to every buffer set as a read-only ACL entry.

-l log_save_path

When a client process stops or terminates, move its associated buffer set(s) under /dev/shmem/slogger2/ to log_save_path.

This is mainly intended as a debugging feature.

The default behavior of slogger2 once a client disconnects is to postpone the immediate cleanup of resources associated with the respective buffer set(s) until a later time. The present implementation relies on a queue of disconnected clients.

-m

Use CLOCK_MONOTONIC as the timestamp reference.

The default system clock is CLOCK_REALTIME.

-S

Force slogger2 to look up an environment variable called SLOG_BUFFER_SIZE in each client to possibly override the buffer size associated with the -s option for that client only. The value of SLOG_BUFFER_SIZE is the desired buffer size in bytes.

This option is intended for debug use only; if you use it, slogger2 must retain all root process abilities.

-s size

Allocate each client using the legacy logger APIs (i.e., slogb(), slogf(), slogi(), and vslogf()) a private logging buffer that's managed by slogger2 on its behalf. This option lets you override the default per-client buffer size of 64 KB. The size is in bytes, but you can specify a (case-sensitive) suffix of k to specify a size in kilobytes. The size is rounded up to the nearest multiple of the page size (4 KB). To disable the legacy logging feature, set the size to 0.

-U uid:gid

Once running, run as the specified user, so that the program doesn't need to run as root. The option argument must be the user ID (uid) followed by a colon and then the group ID (gid).

-V

Globally set the SLOG2_DYNAMIC_VERBOSITY flag for each buffer set. This has the same effect as if each client had set the SLOG2_DYNAMIC_VERBOSITY flag in slog2_register().

Description:

The slogger2 daemon is the central manager of a system-logging framework. Its primary goals are to:

• provide high performance
• work in situations where interrupts aren't enabled
• provide component-specific log buffers and verbosity control

The components of the system logger include:

libslog2, <sys/slog2.h>

The library and header file for the API.

slogger2

The daemon process that's responsible for:

• allocating buffers for each process
• maintaining buffers (cleaning up buffers when processes die, etc.)
• controlling verbosity
• gathering logs
• providing a means for other components to consume the logs

libslog2parse, <slog2_parse.h>

A library that supports log parsing by other tools (e.g., slog2info). For more information, see slog2_parse_all(), slog2_parse_dynamic_buffer(), slog2_parse_static_buffer(), and their related functions in the C Library Reference.

slog2info

The realtime viewer. It can consume the live stream from slogger2, as well as parse (using libslog2parse) and display saved slog2 files.

The slogger2 daemon replaces the legacy slogger and older Unix system logger daemon, syslogd. The Unix library routines for syslog() output their messages to /dev/slog, which is caught and logged by slogger2.

Buffer Management

The central slogger2 process manages a region of shared RAM where all slog2 buffers are located. This gives slog2 the performance benefit of writing to RAM (instead of to flash or disk) without losing logs in the case of process crashes. When a process ends, its logs remain in RAM, but slogger2 removes them when it needs to reuse that memory. However, if the power source is disconnected, any log contents in RAM will be lost.

Individual slog2 instances are allocated from this memory region by slogger2 and are provided to the client process, via slog2_register(), in the form of a shared memory file in /dev/shmem/slogger2/. The libslog2 library uses shm_open() to access each instance.

Within each slog2 instance there may be up to four buffers defined by the client process. These buffers can be any combination of 4 KB pages. The primary intent for these buffers is to enable high-rate logging into one buffer, while preserving a longer history of low-rate logging in another.

The central slogger2 process is responsible for cleaning up the slog2 instances, including calling the shmem_unlink() function to remove the shared memory file.

Severity, verbosity, and filtering

Each log line is assigned one of the following severity levels (listed here in decreasing order):

SLOG2_SHUTDOWN

Shut down the system now (e.g., for OEM use).

SLOG2_CRITICAL

Unexpected unrecoverable error (e.g., hard disk error).

SLOG2_ERROR

Unexpected recoverable error (e.g., you need to reset a hardware controller).

SLOG2_WARNING

Expected error (e.g., parity error on a serial port).

SLOG2_NOTICE

Warning (e.g., out of paper).

SLOG2_INFO

Information (e.g., printing page 3).

SLOG2_DEBUG1

Debug messages (e.g., normal detail).

SLOG2_DEBUG2

Debug messages (e.g., fine detail).

The verbosity level controls which log lines are written in the slog2 buffer; if the severity level is greater than the verbosity level, the line is written in the buffer.

Filtering controls which log items are displayed to the user; the log contents aren't affected. You could filter the log by using (for example) grep, slog2info, or a custom log viewer.

Redirecting a program's stdout and stderr to slog2 buffers

You can redirect a program's standard output (stdout) and standard error (stderr) streams to slog2 buffers. The slogger2 service manages two device paths, /dev/slog2/stdout and /dev/slog2/stderr, and when a process writes to them, the service stores the bytes written, along with other information such as the process ID, in slog2 buffers.

The advantage of using this redirection feature over the -c option is that a given program's logging information can be viewed separately from that of other programs. With -c, the same buffer set contains output from all processes using slogger2.

my_program >/dev/slog2/stdout[/[buffer_set_name],stdout_page_count] 
 2>/dev/slog2/stderr[/[buffer_set_name],stdout_page_count[,stderr_page_count]] 

my_program >/dev/slog2/stdout 2>/dev/slog2/stderr

my_program >/dev/slog2/stdout/alt_name,1,32 2>/dev/slog2/stderr/alt_name,1,32

The default behavior (if no options are provided) is equivalent to writing to /dev/slog2/stdout/7 and /dev/slog2/stderr/7,1. This is to make /dev/slog2/stdout/7 become /dev/slog2/stdout/7,1 to align with the need for the same syntax in both. In this example, 7 pages are used for stdout and 1 page for stderr.

/dev/slog2/stderr/7,1

/dev/slog2/stderr/0,0

/dev/slog2/stderr/,0

Redirecting slogger output to slogger2

LD_PRELOAD=libslog2shim.so my_program

buffer_set_name: my_program
num_buffers: 1
verbosity level: SLOG2_DEBUG
num_pages: 8
buffer_name: SLOGGER_LEGACY

_SLOG_SETCODE(major, minor)

If you don't load the shim library, any slogger messages issued by your programs are still handled by slogger2. This is because slogger2 exposes the /dev/slog device path that the legacy slogger APIs write their messages to. The slogger2 process understands the format of messages received this way, but just like when the shim library is used, it also drops the major value from the opcode and keeps only the minor value.

The advantage of using the shim library is that each log written to the logging buffer is handled locally within the process, without any message passing overhead. With the /dev/slog method, the logging buffer is maintained by slogger2 and each log written by a process is passed as a message to slogger2, which in turn appends the log to a buffer that it maintains on behalf of the client process. Almost all advantages related to logging with slogger2 are lost with the /dev/slog approach. The only advantage to this other approach is simplicity; it minimizes the effort required to get a legacy code base working, while retaining the same efficiency as slogger.