1tracing(3TNF) TNF Library Functions tracing(3TNF)
2
6 tracing - overview of tnf tracing system
7
9 tnf tracing is a set of programs and API's that can be used to present
10 a high-level view of the performance of an executable, a library, or
11 part of the kernel. tracing is used to analyze a program's performance
12 and identify the conditions that produced a bug.
13 The core elements of tracing are:
16 TNF_PROBE_*() The TNF_PROBE_*() macros define "probes" to
18 be placed in code which, when enabled and exe‐
19 cuted, cause information to be added to a
20 trace file. See TNF_PROBE(3TNF). If there are
21 insufficient TNF_PROBE_* macros to store all
22 the data of interest for a probe, data may be
23 grouped into records. See
24 TNF_DECLARE_RECORD(3TNF).
25 prex Displays and controls probes in running soft‐
28 ware. See prex(1).
29 kernel probes A set of probes built into the Solaris kernel
32 which capture information about system calls,
33 multithreading, page faults, swapping, memory
34 management, and I/O. You can use these probes
35 to obtain detailed traces of kernel activity
36 under your application workloads. See
37 tnf_kernel_probes(4).
38 tnfxtract A program that extracts the trace data from
41 the kernel's in-memory buffer into a file. See
42 tnfxtract(1).
43 tnfdump A program that displays the information from a
46 trace file. See tnfdump(1).
47 libtnfctl A library of interfaces that controls probes
50 in a process. See libtnfctl(3TNF). prex(1)
51 also utilizes this library. Other tools and
52 processes use the libtnfctl interfaces to
53 exercise fine control over their own probes.
54 tnf_process_enable() A routine called by a process to turn on trac‐
57 ing and probe functions for the current
58 process. See tnf_process_enable(3TNF).
59 tnf_process_disable() A routine called by a process to turn off
62 tracing and probe functions for the current
63 process. See tnf_process_disable(3TNF).
64 tnf_thread_enable() A routine called by a process to turn on trac‐
67 ing and probe functions for the currently run‐
68 ning thread. See tnf_thread_enable(3TNF).
69 tnf_thread_disable() A routine called by a process to turn off
72 tracing and probe functions for the currently
73 running thread. See tnf_thread_disable(3TNF).
74
77 Example 1 Tracing a Process
78 The following function in some daemon process accepts job requests of
81 various types, queueing them for later execution. There are two "debug
82 probes" and one "production probe." Note that probes which are
83 intended for debugging will not be compiled into the final version of
84 the code; however, production probes are compiled into the final prod‐
85 uct.
86 /*
89 * To compile in all probes (for development):
90 * cc -DTNF_DEBUG ...
91 *
92 * To compile in only production probes (for release):
93 * cc ...
94 *
95 * To compile in no probes at all:
96 * cc -DNPROBE ...
97 */
98 #include <tnf/probe.h>
99 void work(long, char *);
100 enum work_request_type { READ, WRITE, ERASE, UPDATE };
101 static char *work_request_name[] = {"read", "write", "erase", "update"};
102 main()
103 {
104 long i;
105 for (i = READ; i <= UPDATE; i++)
106 work(i, work_request_name[i]);
107 }
108 void work(long request_type, char *request_name)
109 {
110 static long q_length;
111 TNF_PROBE_2_DEBUG(work_start, "work",
112 "XYZ%debug 'in function work'",
113 tnf_long, request_type_arg, request_type,
114 tnf_string, request_name_arg, request_name);
115 /* assume work request is queued for later processing */
116 q_length++;
117 TNF_PROBE_1(work_queue, "work queue",
118 "XYZ%work_load heavy",
119 tnf_long, queue_length, q_length);
120 TNF_PROBE_0_DEBUG(work_end, "work", "");
121 }
122 The production probe "work_queue," which remains compiled in the code,
126 will, when enabled, log the length of the work queue each time a
127 request is received.
128 The debug probes "work_start" and "work_end, " which are compiled only
132 during the development phase, track entry to and exit from the work()
133 function and measure how much time is spent executing it. Additionally,
134 the debug probe "work_start" logs the value of the two incoming argu‐
135 ments request_type and request_name. The runtime overhead for dis‐
136 abled probes is low enough that one can liberally embed them in the
137 code with little impact on performance.
138 For debugging, the developer would compile with -DTNF_DEBUG, run the
142 program under control of prex(1), enable the probes of interest (in
143 this case, all probes), continue the program until exit, and dump the
144 trace file:
145 % cc
148 -DTNF_DEBUG -o daemon daemon.c # compile in all probes
149 % prex daemon # run program under prex control
150 Target process stopped
151 Type "continue" to resume the target, "help" for help ...
152 prex> list probes $all # list all probes in program
153 <probe list output here>
154 prex> enable $all # enable all probes
155 prex> continue # let target process execute
156 <program output here>
157 prex: target process finished
158 % ls /tmp/trace-* # trace output is in trace-<pid>
159 /tmp/trace-4194
160 % tnfdump /tmp/trace-4194 # get ascii output of trace file
161 <trace records output here>
162 For the production version of the system, the developer simply compiles
166 without -DTNF_DEBUG.
167 Example 2 Tracing the Kernel
170 Kernel tracing is similar to tracing a process; however, there are
173 some differences. For instance, to trace the kernel, you need superuser
174 privileges. The following example uses prex(1) and traces the probes in
175 the kernel that capture system call information.
176 Allocate kernel
179 trace buffer and capture trace data:
180 root# prex -k
181 Type "help" for help ...
182 prex> buffer alloc 2m # allocate kernel trace buffer
183 Buffer of size 2097152 bytes allocated
184 prex> list probes $all # list all kernel probes
185 <probe list output here>
186 prex> list probes syscall # list syscall probes
187 # (keys=syscall)
188 <syscall probes list output here>
189 prex> enable syscall # enable only syscall probes
190 prex> ktrace on # turn on kernel tracing
191 <Run your application in another window at this point>
192 prex> ktrace off # turn off kernel tracing
193 prex> quit # exit prex
194 Extract the kernel's trace buffer into a file:
195 root# tnfxtract /tmp/ktrace # extract kernel trace buffer
196 Reset kernel tracing:
197 root# prex -k
198 prex> disable $all # disable all probes
199 prex> untrace $all # untrace all probes
200 prex> buffer dealloc # deallocate kernel trace buffer
201 prex> quit
202 CAUTION: Do not deallocate the trace buffer until you have extracted
206 it into a trace file. Otherwise, you will lose the trace data that you
207 collected from your experiment!
208 Examine the kernel trace file:
212 root# tnfdump /tmp/ktrace # get ascii dump of trace file
215 <trace records output here>
216 prex can also attach to a running process, list probes, and perform a
220 variety of other tasks.
221
224 See attributes(5) for descriptions of the following attributes:
225 ┌─────────────────────────────┬─────────────────────────────┐
230 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
231 ├─────────────────────────────┼─────────────────────────────┤
232 │Availability │SUNWtnfd │
233 ├─────────────────────────────┼─────────────────────────────┤
234 │MT Level │MT-Safe │
235 └─────────────────────────────┴─────────────────────────────┘
236
238 prex(1), tnfdump(1), tnfxtract(1), TNF_DECLARE_RECORD(3TNF),
239 TNF_PROBE(3TNF), libtnfctl(3TNF), tnf_process_disable(3TNF), tnf_ker‐
240 nel_probes(4), attributes(5)
241SunOS 5.11 4 Mar 1997 tracing(3TNF)