This version of this document is no longer maintained. For the latest documentation, see http://www.qnx.com/developers/docs.

`tracelogger`

Log tracing information into an event file

You must be root to run this utility.
In order to log trace events, your system must be running an instrumented version of procnto.

Syntax:

tracelogger [-cEPRrw] [-A attribute] [-b num] [-d mode]
            [-F num] [-f file] [-k num] [-M -S size] [-n num]
            [-s num] [-v[v...]]

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.

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 -A PERIOD=1s

-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.

-d mode

Currently, the mode is:

1 (“One”): Launch in daemon mode. Unless you also specify the -E option, tracelogger ignores all its other options, leaving your application to configure, start, and stop the tracing.

-E

Extend the daemon (-d1) mode by honoring the other options to tracelogger. Your application still needs to call TraceEvent() to start capturing trace events.

-f file

The name of the file to store logged events in. The default is /dev/shmem/tracebuffer.kev.

-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.

-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

The number of iterations to log 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.

-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

Set the kernel buffer to ring mode. The default is linear mode.

-s num

The number of seconds to log in continuous mode (as specified by the -c option). 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.

Description:

The tracelogger daemon receives events from the instrumented kernel (procnto*-instr) and saves them in a file or on a device for later analysis. It logs the requested number of iterations, and then terminates. You can start tracelogger using:

Full tracelogger support (limited control): Instrumentation with full tracelogger support is the simplest way to obtain the tracing information. In this case, the 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.
Partial tracelogger support (daemon mode, full control): Instrumentation with partial tracelogger support is the most flexible way of controlling the instrumentation process. However, it requires the largest amount of user support during initialization. Except for specifying the number of buffers, the 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.

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 -n 12 -w

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

#tracelogger -r -b 5

Run tracelogger in continous mode for 20 seconds:

tracelogger -c -s20

Exit status:

-1: An error occurred.

Errors:

Severe errors cause tracelogger to terminate.

Caveats:

Run only one instance of tracelogger at a time.