tracelogger

Updated: April 19, 2023

Log tracing information into an event file

Note:
  • You must be root to run this utility.
  • In order to log trace events, your system must be running an instrumented version of procnto (i.e., procnto*-instr). In QNX Neutrino 7.0 or later, we ship only the instrumented versions.

Syntax:

tracelogger [-acEPRrw] [-A attribute] [-b num] [-D seconds]
            [-d mode] [-F num] [-f file] [-k num]
            [-M -S size] [-n num] [-p addr] [-s num] [-v[v...]]

Runs on:

QNX Neutrino

Options:

-A attribute
Specify an attribute to add to the log. The attribute is in the form name=value, where the name and value are arbitrary strings.
Note: You can't use the following in the name or value:
  • ::
  • TRACE_
  • =

If you do, tracelogger prints a message and ignores the attribute.

You can use one or more occurrences of this option to add information to identify the scenario that you're logging. For example:

tracelogger -s1 -A MACHINE_NAME=tx86_64 -A PERIOD=1s
-a
(QNX Neutrino 7.0 or later) Enable Security class events.
-b num
The maximum number of dynamic buffers to allocate in tracelogger; the default is 64. Each buffer has a size of approximately 11 KB.
-c
Operate in continuous mode; the default is to run in iterations mode. This option is equivalent to -n0.
-D seconds
Enable a periodic flush of kernel events (the default is off).
-d1

(“One”) Launch in so-called daemon mode. This option makes tracelogger run passively, leaving the control of tracing to your application; it doesn't actually make tracelogger run as a daemon.

Note:

The -d1 option doesn't configure events or logging duration. To enable events, use the -E option. Alternatively, use TraceEvent() calls to enable specific events. To configure the logging duration, use -c, -s, or -n. The default is -n32.

-E
Enable events, even if you're running tracelogger in daemon mode.
-f file
The name of the file to store logged events in. The default is /dev/shmem/tracebuffer.kev. If file is a hyphen (-), then the logged events are streamed to stdout. If file names an existing FIFO special file created with mkfifo() or the mkfifo utility, the logged events are streamed to the FIFO.
-F num
Filtering for different num values, as follows:
0
Don't set any filtering.
1
Disable Kernel calls class.
2
Disable Interrupt class.
3
Disable Process class.
4
Disable Thread class.
5
Disable VThread class.
6
Disable Communication class.
7
Disable System class.

You can specify more than one filter by using multiple -F options. For example, to disable both the Interrupt and VThread classes, specify -F2 -F5. For more information about these classes, see the Events and the Kernel chapter of the System Analysis Toolkit User's Guide.

-k num
The number of buffers to allocate in the kernel; the default is 32. Each buffer has a size of approximately 16 KB.
-M
Map the log file directly instead of writing. If you use this option, the log file must be in shared memory, and you must use the -S option to specify the maximum file size.
-n num_buffers
The number of buffers to fill in iterations mode. The default is 32; specify 0 for unlimited iterations.
-P
Preserve the kernel instrumentation buffers in a shared memory block in /dev/shmem. If you specify this option, then when tracelogger exits, it doesn't deallocate the in-kernel buffer memory; you can then specify the -R option on subsequent runs to make tracelogger reuse the same buffers without reallocating memory.
-p addr
Specify the address of the physical memory to use for kernel buffers.
-R
Reuse the kernel instrumentation buffers that were previously created when you used the -P option. If there are no buffers to reuse, tracelogger allocates the kernel buffers as usual.
-r
Log the events in ring mode (i.e., without flushing them). The default is linear mode (filled buffers are flushed immediately).
-s num
The number of seconds to log for. The default is 0, specifying an unlimited duration.
-S size
The maximum size of the log file. Use M for megabytes or K for kilobytes. If you don't use M or K, the units are assumed to be bytes. You must specify this option if you use the -M option.
-v[v...]
Be verbose; more v characters cause more verbosity.
-w
Log wide events; the default is to log fast events. For more information, see Fast and wide modes in the “Events and the Kernel” chapter of the System Analysis Toolkit User's Guide.

Description:

The tracelogger service receives events from the instrumented kernel (procnto*-instr) and saves them in a file or on a device for later analysis. By default, tracelogger saves the events in /dev/shmem/tracebuffer.kev. The .kev extension is short for “kernel events”; the Integrated Development Environment opens files with this extension in the System Profiler.

Note:
  • Run only one instance of tracelogger at a time. Similarly, don't run tracelogger and use qconn (under control of the IDE) to trace events at the same time.
  • In QNX Neutrino 7.0 or later, we require that the hardware underlying ClockCycles() be synchronized across all processors on an SMP system. If the clocks aren't synchronized, then tracelogger produces data with inconsistent timestamps, and the IDE won't be able to load the trace file. The IDE attempts to properly order the events in the trace file, and this can go awry if the timestamp data is incorrect.

    The traceprinter utility doesn't have any issues with such traces because it doesn't attempt to reorder the data and interpret it; it simply dumps the contents of each event.

You can run tracelogger in the following modes:

Mode Option The kernel: tracelogger:
Continuous -c Logs events Captures the events, and continues to do so until terminated
Daemon -d1 Doesn't log eventsa Waits passivelya
Iterations (the default) -n Logs events Captures num_buffers of data and then terminates
Ring -r Logs events Doesn't capture events until it gets a SIGINT signal, or an application calls TraceEvent(_NTO_TRACE_STOP)b
Time-based -s Logs events Captures events for the specified number of seconds

a In daemon mode, logging starts when an application calls TraceEvent(_NTO_TRACE_START) and continues until an application calls TraceEvent(_NTO_TRACE_STOP), logging duration expires (-c, -s, or -n), or until you terminate tracelogger.

b When you terminate tracing in ring mode, tracelogger stops logging events, and then briefly restarts and stops it again so it can capture the state information that's emitted by the _NTO_TRACE_START command. This information includes the thread IDs and names of processes.

If you aren't using daemon mode, or you're using daemon mode with the -E option, then tracelogger:

This is the simplest way to configure the tracing. In this case, tracelogger performs all initialization and runtime control of the instrumentation module in addition to its normal task of saving the trace buffers to the filesystem. If you use daemon mode, your application needs to call TraceEvent() to start capturing trace events.

For finer (and more flexible) control of the instrumentation, run tracelogger in daemon mode without the -E option, and call TraceEvent() from your application to specify what to trace, and when to start and stop tracing. Except for specifying the number of buffers, tracelogger doesn't perform any initialization of the instrumentation module, and its almost exclusive task is to log the “received” trace events to the filesystem.

Note: If an application has called TraceEvent(_NTO_TRACE_START), and you then try to start tracelogger, tracelogger might fail with a “resource busy” message. To help avoid this:
  • Start tracelogger before your application issues a _NTO_TRACE_START or _NTO_TRACE_STARTNOSTATE command.
  • Don't leave tracing on indefinitely; be sure to issue a _NTO_TRACE_STOP after each _NTO_TRACE_START or _NTO_TRACE_STARTNOSTATE command.

Examples:

Start tracelogger in wide mode and display operational information on the console screen; store the logged data in the named file and stop logging when 12 trace buffers are full:

tracelogger -f /dev/shmem/my_tracebuffer.kev -n 12 -w

Start tracelogger in ring mode using 5 internal buffers and wait for an asynchronous signal (e.g., CtrlC) to stop it:

tracelogger -r -b 5

Run tracelogger in daemon mode until _NTO_TRACE_STOP is issued. Enable all events, log wide events, and filter out events that are in the Interrupt class:

tracelogger -d1 -c -E -w -F2

Exit status:

-1
An error occurred.

Errors:

Severe errors cause tracelogger to terminate.