TNF Library Functions tracing(3TNF)
NAME
tracing - overview of tnf tracing system
DESCRIPTION
tnf tracing is a set of programs and API's that can be used
to present a high-level view of the performance of an exe-
cutable, a library, or part of the kernel. tracing is used
to analyze a program's performance and identify the condi-
tions that produced a bug.
The core elements of tracing are:
TNFPROBE*() The TNFPROBE*() macros define
"probes" to be placed in code
which, when enabled and executed,
cause information to be added to a
trace file. See TNFPROBE(3TNF).
If there are insufficient
TNFPROBE* macros to store all the
data of interest for a probe, data
may be grouped into records. See
TNFDECLARERECORD(3TNF).
prex Displays and controls probes in
running software. See prex(1).
kernel probes A set of probes built into the
Solaris kernel which capture infor-
mation about system calls, mul-
tithreading, page faults, swapping,
memory management, and I/O. You can
use these probes to obtain detailed
traces of kernel activity under
your application workloads. See
tnfkernelprobes(4).
tnfxtract A program that extracts the trace
data from the kernel's in-memory
buffer into a file. See
tnfxtract(1).
tnfdump A program that displays the infor-
mation from a trace file. See
tnfdump(1).
SunOS 5.11 Last change: 4 Mar 1997 1
TNF Library Functions tracing(3TNF)
libtnfctl A library of interfaces that con-
trols probes in a process. See
libtnfctl(3TNF). prex(1) also util-
izes this library. Other tools and
processes use the libtnfctl inter-
faces to exercise fine control over
their own probes.
tnfprocessenable() A routine called by a process to
turn on tracing and probe functions
for the current process. See
tnfprocessenable(3TNF).
tnfprocessdisable() A routine called by a process to
turn off tracing and probe func-
tions for the current process. See
tnfprocessdisable(3TNF).
tnfthreadenable() A routine called by a process to
turn on tracing and probe functions
for the currently running thread.
See tnfthreadenable(3TNF).
tnfthreaddisable() A routine called by a process to
turn off tracing and probe func-
tions for the currently running
thread. See
tnfthreaddisable(3TNF).
EXAMPLES
Example 1 Tracing a Process
The following function in some daemon process accepts job
requests of various types, queueing them for later execu-
tion. There are two "debug probes" and one "production
probe." Note that probes which are intended for debugging
will not be compiled into the final version of the code;
however, production probes are compiled into the final pro-
duct.
/*
* To compile in all probes (for development):
* cc -DTNFDEBUG ...
*
* To compile in only production probes (for release):
SunOS 5.11 Last change: 4 Mar 1997 2
TNF Library Functions tracing(3TNF)
* cc ...
*
* To compile in no probes at all:
* cc -DNPROBE ...
*/
#include
void work(long, char *);
enum workrequesttype { READ, WRITE, ERASE, UPDATE };
static char *workrequestname[] = {"read", "write", "erase", "update"};
main()
{
long i;
for (i = READ; i <= UPDATE; i])
work(i, workrequestname[i]);
}
void work(long requesttype, char *requestname)
{
static long qlength;
TNFPROBE2DEBUG(workstart, "work",
"XYZ%debug 'in function work'",
tnflong, requesttypearg, requesttype,
tnfstring, requestnamearg, requestname);
/* assume work request is queued for later processing */
qlength];
TNFPROBE1(workqueue, "work queue",
"XYZ%workload heavy",
tnflong, queuelength, qlength);
TNFPROBE0DEBUG(workend, "work", "");
}
The production probe "workqueue," which remains compiled in
the code, will, when enabled, log the length of the work
queue each time a request is received.
The debug probes "workstart" and "workend, " which are
compiled only during the development phase, track entry to
and exit from the work() function and measure how much time
is spent executing it. Additionally, the debug probe
"workstart" logs the value of the two incoming arguments
requesttype and requestname. The runtime overhead for
disabled probes is low enough that one can liberally embed
them in the code with little impact on performance.
For debugging, the developer would compile with -
DTNFDEBUG, run the program under control of prex(1),
enable the probes of interest (in this case, all probes),
SunOS 5.11 Last change: 4 Mar 1997 3
TNF Library Functions tracing(3TNF)
continue the program until exit, and dump the trace file:
% cc
-DTNFDEBUG -o daemon daemon.c # compile in all probes
% prex daemon # run program under prex control
Target process stopped
Type "continue" to resume the target, "help" for help ...
prex> list probes $all # list all probes in program
prex> enable $all # enable all probes
prex> continue # let target process execute
prex: target process finished
% ls /tmp/trace-* # trace output is in trace-
/tmp/trace-4194
% tnfdump /tmp/trace-4194 # get ascii output of trace file
For the production version of the system, the developer sim-
ply compiles without -DTNFDEBUG.
Example 2 Tracing the Kernel
Kernel tracing is similar to tracing a process; however,
there are some differences. For instance, to trace the ker-
nel, you need superuser privileges. The following example
uses prex(1) and traces the probes in the kernel that cap-
ture system call information.
Allocate kernel
trace buffer and capture trace data:
root# prex -k
Type "help" for help ...
prex> buffer alloc 2m # allocate kernel trace buffer
Buffer of size 2097152 bytes allocated
prex> list probes $all # list all kernel probes
prex> list probes syscall # list syscall probes
# (keys=syscall)
prex> enable syscall # enable only syscall probes
prex> ktrace on # turn on kernel tracing
prex> ktrace off # turn off kernel tracing
prex> quit # exit prex
Extract the kernel's trace buffer into a file:
SunOS 5.11 Last change: 4 Mar 1997 4
TNF Library Functions tracing(3TNF)
root# tnfxtract /tmp/ktrace # extract kernel trace buffer
Reset kernel tracing:
root# prex -k
prex> disable $all # disable all probes
prex> untrace $all # untrace all probes
prex> buffer dealloc # deallocate kernel trace buffer
prex> quit
CAUTION: Do not deallocate the trace buffer until you have
extracted it into a trace file. Otherwise, you will lose the
trace data that you collected from your experiment!
Examine the kernel trace file:
root# tnfdump /tmp/ktrace # get ascii dump of trace file
prex can also attach to a running process, list probes, and
perform a variety of other tasks.
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Availability SUNWtnfd
MT Level MT-Safe
SEE ALSO
prex(1), tnfdump(1), tnfxtract(1), TNFDECLARERECORD(3TNF),
TNFPROBE(3TNF), libtnfctl(3TNF), tnfprocessdisable(3TNF),
tnfkernelprobes(4), attributes(5)
SunOS 5.11 Last change: 4 Mar 1997 5
|
