usr/src/man/man3tnf/tracing.3tnf

   1 '\" te
   2 .\"  Copyright (c) 1997, Sun Microsystems, Inc.
   3 .\"  All Rights Reserved
   4 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   5 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   6 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   7 .TH TRACING 3TNF "Mar 4, 1997"
   8 .SH NAME
   9 tracing \- overview of tnf tracing system
  10 .SH DESCRIPTION
  11 .sp
  12 .LP
  13 \fBtnf tracing\fR is a set of programs and  \fBAPI's\fR that can be used to
  14 present a high-level view of the performance of an executable, a library, or
  15 part of the kernel.  \fBtracing\fR is used to analyze a program's performance
  16 and identify the conditions that produced a bug.
  17 .sp
  18 .LP
  19 The core elements of  \fBtracing\fR are:
  20 .sp
  21 .ne 2
  22 .na
  23 \fB\fBTNF_PROBE_*(\|)\fR\fR
  24 .ad
  25 .RS 25n
  26 The  \fBTNF_PROBE_*(\|)\fR macros define "probes" to be placed in code which,
  27 when enabled and executed, cause information to be added to a trace file. See
  28 \fBTNF_PROBE\fR(3TNF). If there are insufficient  \fBTNF_PROBE_*\fR macros to
  29 store all the data of interest for a probe, data may be grouped into records.
  30 See  \fBTNF_DECLARE_RECORD\fR(3TNF).
  31 .RE
  32
  33 .sp
  34 .ne 2
  35 .na
  36 \fB\fBprex\fR\fR
  37 .ad
  38 .RS 25n
  39 Displays and controls probes in running software. See prex(1).
  40 .RE
  41
  42 .sp
  43 .ne 2
  44 .na
  45 \fB\fBkernel\fR \fBprobes\fR\fR
  46 .ad
  47 .RS 25n
  48 A set of probes built into the Solaris kernel which capture information about
  49 system calls, multithreading, page faults, swapping, memory management, and
  50 I/O. You can use these probes to obtain detailed traces of kernel activity
  51 under your application workloads. See  \fBtnf_kernel_probes\fR(4).
  52 .RE
  53
  54 .sp
  55 .ne 2
  56 .na
  57 \fB\fBtnfxtract\fR\fR
  58 .ad
  59 .RS 25n
  60 A program that extracts the trace data from the kernel's in-memory buffer into
  61 a file. See  \fBtnfxtract\fR(1).
  62 .RE
  63
  64 .sp
  65 .ne 2
  66 .na
  67 \fB\fBtnfdump\fR\fR
  68 .ad
  69 .RS 25n
  70 A program that displays the information from a trace file. See
  71 \fBtnfdump\fR(1).
  72 .RE
  73
  74 .sp
  75 .ne 2
  76 .na
  77 \fB\fBlibtnfctl\fR\fR
  78 .ad
  79 .RS 25n
  80 A library of interfaces that controls probes in a process.  See
  81 \fBlibtnfctl\fR(3TNF). \fBprex\fR(1) also utilizes this library.  Other tools
  82 and processes use the \fBlibtnfctl\fR interfaces to exercise fine control over
  83 their own probes.
  84 .RE
  85
  86 .sp
  87 .ne 2
  88 .na
  89 \fB\fBtnf_process_enable()\fR\fR
  90 .ad
  91 .RS 25n
  92 A routine called by a process to turn on tracing and probe functions for the
  93 current process.  See \fBtnf_process_enable\fR(3TNF).
  94 .RE
  95
  96 .sp
  97 .ne 2
  98 .na
  99 \fB\fBtnf_process_disable()\fR\fR
 100 .ad
 101 .RS 25n
 102 A routine called by a process to turn off tracing and probe  functions for the
 103 current process.  See \fBtnf_process_disable\fR(3TNF).
 104 .RE
 105
 106 .sp
 107 .ne 2
 108 .na
 109 \fB\fBtnf_thread_enable()\fR\fR
 110 .ad
 111 .RS 25n
 112 A routine called by a process to turn on tracing and probe functions for the
 113 currently running thread. See \fBtnf_thread_enable\fR(3TNF).
 114 .RE
 115
 116 .sp
 117 .ne 2
 118 .na
 119 \fB\fBtnf_thread_disable()\fR\fR
 120 .ad
 121 .RS 25n
 122 A routine called by a process to turn off tracing and probe functions for the
 123 currently running thread. See \fBtnf_thread_disable\fR(3TNF).
 124 .RE
 125
 126 .SH EXAMPLES
 127 .LP
 128 \fBExample 1 \fRTracing a Process
 129 .sp
 130 .LP
 131 The following function in some daemon process accepts job requests of various
 132 types, queueing them for later execution. There are two "debug probes" and one
 133 "production probe."  Note that probes which are intended for debugging will not
 134 be compiled into the final version of the code; however, production probes are
 135 compiled into the final product.
 136
 137 .sp
 138 .in +2
 139 .nf
 140  /*
 141   * To compile in all probes (for development):
 142   *     cc -DTNF_DEBUG ...
 143   *
 144   * To compile in only production probes (for release):
 145   *     cc ...
 146   *
 147   * To compile in no probes at all:
 148   *     cc -DNPROBE ...
 149   */
 150 #include <tnf/probe.h>
 151 void work(long, char *);
 152 enum work_request_type { READ, WRITE, ERASE, UPDATE };
 153 static char *work_request_name[] = {"read", "write", "erase", "update"};
 154 main(\|)
 155 {
 156   long i;
 157   for (i = READ;  i <= UPDATE; i++)
 158         work(i, work_request_name[i]);
 159 }
 160 void work(long request_type, char *request_name)
 161 {
 162     static long q_length;
 163     TNF_PROBE_2_DEBUG(work_start, "work",
 164                 "XYZ%debug 'in function work'",
 165                 tnf_long, request_type_arg, request_type,
 166                 tnf_string, request_name_arg, request_name);
 167     /* assume work request is queued for later processing */
 168     q_length++;
 169     TNF_PROBE_1(work_queue, "work queue",
 170                 "XYZ%work_load heavy",
 171                 tnf_long, queue_length, q_length);
 172     TNF_PROBE_0_DEBUG(work_end, "work", "");
 173 }
 174 .fi
 175 .in -2
 176
 177 .sp
 178 .LP
 179 The production probe "work_queue," which remains compiled in the code, will,
 180 when enabled, log the length of the work queue each time a request is received.
 181
 182 .sp
 183 .LP
 184 The debug probes "work_start" and "work_end, " which are compiled only during
 185 the development phase, track entry to and exit from the  \fBwork()\fR function
 186 and measure how much time is spent executing it. Additionally, the debug probe
 187 "work_start" logs the value of the  two incoming arguments  \fBrequest_type\fR
 188 and  \fBrequest_name\fR. The runtime overhead for disabled probes is low enough
 189 that one can liberally embed them in the code with little impact on
 190 performance.
 191
 192 .sp
 193 .LP
 194 For debugging, the developer would compile with  \fB-DTNF_DEBUG\fR, run the
 195 program under control of  \fBprex\fR(1), enable the probes of interest (in this
 196 case, all probes),  continue the program until exit, and dump the trace file:
 197
 198 .sp
 199 .in +2
 200 .nf
 201 % cc
 202 -DTNF_DEBUG -o daemon daemon.c  # compile in all probes
 203 % prex daemon                   # run program under prex control
 204 Target process stopped
 205 Type "continue" to resume the target, "help" for help ...
 206 prex> list probes $all          # list all probes in program
 207 <probe list output here>
 208 prex> enable $all               # enable all probes
 209 prex> continue                  # let target process execute
 210 <program output here>
 211 prex: target process finished
 212 % ls /tmp/trace-*               # trace output is in trace-<pid>
 213 /tmp/trace-4194
 214 % tnfdump /tmp/trace-4194       # get ascii output of trace file
 215 <trace records output here>
 216 .fi
 217 .in -2
 218
 219 .sp
 220 .LP
 221 For the production version of the system, the developer simply compiles without
 222 \fB-DTNF_DEBUG\fR\&.
 223
 224 .LP
 225 \fBExample 2 \fRTracing the Kernel
 226 .sp
 227 .LP
 228 Kernel tracing is similar to tracing a process;  however, there are some
 229 differences. For instance, to trace the kernel, you need superuser privileges.
 230 The following example uses prex(1) and traces the probes in the kernel that
 231 capture system call information.
 232
 233 .sp
 234 .in +2
 235 .nf
 236 Allocate kernel
 237 trace buffer and capture trace data:
 238 root# prex -k
 239 Type "help" for help ...
 240 prex> buffer alloc 2m           # allocate kernel trace buffer
 241 Buffer of size 2097152 bytes allocated
 242 prex> list probes $all          # list all kernel probes
 243 <probe list output here>
 244 prex> list probes syscall       # list syscall probes
 245                                 # (keys=syscall)
 246 <syscall probes list output here>
 247 prex> enable syscall            # enable only syscall probes
 248 prex> ktrace on                 # turn on kernel tracing
 249 <Run your application in another window at this point>
 250 prex> ktrace off                # turn off kernel tracing
 251 prex> quit                      # exit prex
 252 Extract the kernel's trace buffer into a file:
 253 root# tnfxtract /tmp/ktrace     # extract kernel trace buffer
 254 Reset kernel tracing:
 255 root# prex -k
 256 prex> disable $all              # disable all probes
 257 prex> untrace $all              # untrace all probes
 258 prex> buffer dealloc            # deallocate kernel trace buffer
 259 prex> quit
 260 .fi
 261 .in -2
 262
 263 .sp
 264 .LP
 265 CAUTION: Do not deallocate the trace buffer  until you  have extracted it into
 266 a trace file. Otherwise, you will lose the trace data that you collected from
 267 your experiment!
 268
 269 .sp
 270 .LP
 271 Examine the kernel trace file:
 272
 273 .sp
 274 .in +2
 275 .nf
 276 root# tnfdump /tmp/ktrace       # get ascii dump of trace file
 277 <trace records output here>
 278 .fi
 279 .in -2
 280
 281 .sp
 282 .LP
 283 \fBprex\fR can also attach to a running process, list probes, and perform a
 284 variety of other tasks.
 285
 286 .SH ATTRIBUTES
 287 .sp
 288 .LP
 289 See \fBattributes\fR(5) for descriptions of the following attributes:
 290 .sp
 291
 292 .sp
 293 .TS
 294 box;
 295 c | c
 296 l | l .
 297 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 298 _
 299 MT Level        MT-Safe
 300 .TE
 301
 302 .SH SEE ALSO
 303 .sp
 304 .LP
 305 \fBprex\fR(1), \fBtnfdump\fR(1), \fBtnfxtract\fR(1),
 306 \fBTNF_DECLARE_RECORD\fR(3TNF), \fBTNF_PROBE\fR(3TNF), \fBlibtnfctl\fR(3TNF),
 307 \fBtnf_process_disable\fR(3TNF), \fBtnf_kernel_probes\fR(4),
 308 \fBattributes\fR(5)