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).
Syntax:
tracelogger [-cEPRrw] [-A attribute] [-b num] [-d mode]
[-F num] [-f file] [-k num] [-M -S size]
[-n num] [-p addr] [-s num] [-v[v...]]
Targets:
x86, PPC, SH-4, ARM, and MIPS
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:
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 through calls to
TraceEvent().
- -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.
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
- 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.
- -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
- Set the kernel buffer to ring mode.
The default is linear mode.
- -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.
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.
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.
You can run tracelogger in the following modes:
- -n iterations
- The kernel logs events; tracelogger captures
iterations buffers worth of data, and then terminates.
This is the default, and iterations defaults to 32.
- -r
- Ring mode: the kernel logs events, but tracelogger doesn't
capture them
until it gets a SIGINT signal, or an application calls
TraceEvent()
with a command of _NTO_TRACE_STOP.
- -d1
- Daemon mode: the kernel doesn't log events, and tracelogger
doesn't capture them, until an application calls
TraceEvent()
with a command of _NTO_TRACE_START.
Logging continues until an application calls TraceEvent()
with a command of _NTO_TRACE_STOP, or you terminate
tracelogger.
- -s seconds
- The kernel logs events; tracelogger captures them over
the specified time.
- -c
- The kernel logs events; tracelogger captures them, and
continues to do so until terminated.
The simplest way to configure the tracing is to start tracelogger
in normal or extended daemon (-d1 -E) mode, using the command-line
options to specify what to trace.
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 extended 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 (-d1) mode, 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.
CAUTION:
On a multicore system, if the clocks on all processors aren't synchronized,
then
tracelogger will produce
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.
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 (background)
using 5 internal buffers and wait for an asynchronous
signal (e.g. CtrlC) 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.
Similarly, don't run tracelogger and use
qconn
(under control of the IDE) to trace events at the same time.