'\" te .\" Copyright (c) 1997, Sun Microsystems, Inc. .\" All Rights Reserved .\" 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. .\" 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. .\" 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] .TH TRACING 3TNF "Mar 4, 1997" .SH NAME tracing \- overview of tnf tracing system .SH DESCRIPTION .sp .LP \fBtnf tracing\fR is a set of programs and \fBAPI's\fR that can be used to present a high-level view of the performance of an executable, a library, or part of the kernel. \fBtracing\fR is used to analyze a program's performance and identify the conditions that produced a bug. .sp .LP The core elements of \fBtracing\fR are: .sp .ne 2 .na \fB\fBTNF_PROBE_*(\|)\fR\fR .ad .RS 25n The \fBTNF_PROBE_*(\|)\fR macros define "probes" to be placed in code which, when enabled and executed, cause information to be added to a trace file. See \fBTNF_PROBE\fR(3TNF). If there are insufficient \fBTNF_PROBE_*\fR macros to store all the data of interest for a probe, data may be grouped into records. See \fBTNF_DECLARE_RECORD\fR(3TNF). .RE .sp .ne 2 .na \fB\fBprex\fR\fR .ad .RS 25n Displays and controls probes in running software. See prex(1). .RE .sp .ne 2 .na \fB\fBkernel\fR \fBprobes\fR\fR .ad .RS 25n A set of probes built into the Solaris kernel which capture information about system calls, multithreading, 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 \fBtnf_kernel_probes\fR(4). .RE .sp .ne 2 .na \fB\fBtnfxtract\fR\fR .ad .RS 25n A program that extracts the trace data from the kernel's in-memory buffer into a file. See \fBtnfxtract\fR(1). .RE .sp .ne 2 .na \fB\fBtnfdump\fR\fR .ad .RS 25n A program that displays the information from a trace file. See \fBtnfdump\fR(1). .RE .sp .ne 2 .na \fB\fBlibtnfctl\fR\fR .ad .RS 25n A library of interfaces that controls probes in a process. See \fBlibtnfctl\fR(3TNF). \fBprex\fR(1) also utilizes this library. Other tools and processes use the \fBlibtnfctl\fR interfaces to exercise fine control over their own probes. .RE .sp .ne 2 .na \fB\fBtnf_process_enable()\fR\fR .ad .RS 25n A routine called by a process to turn on tracing and probe functions for the current process. See \fBtnf_process_enable\fR(3TNF). .RE .sp .ne 2 .na \fB\fBtnf_process_disable()\fR\fR .ad .RS 25n A routine called by a process to turn off tracing and probe functions for the current process. See \fBtnf_process_disable\fR(3TNF). .RE .sp .ne 2 .na \fB\fBtnf_thread_enable()\fR\fR .ad .RS 25n A routine called by a process to turn on tracing and probe functions for the currently running thread. See \fBtnf_thread_enable\fR(3TNF). .RE .sp .ne 2 .na \fB\fBtnf_thread_disable()\fR\fR .ad .RS 25n A routine called by a process to turn off tracing and probe functions for the currently running thread. See \fBtnf_thread_disable\fR(3TNF). .RE .SH EXAMPLES .LP \fBExample 1 \fRTracing a Process .sp .LP The following function in some daemon process accepts job requests of various types, queueing them for later execution. 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 product. .sp .in +2 .nf /* * To compile in all probes (for development): * cc -DTNF_DEBUG ... * * To compile in only production probes (for release): * cc ... * * To compile in no probes at all: * cc -DNPROBE ... */ #include void work(long, char *); enum work_request_type { READ, WRITE, ERASE, UPDATE }; static char *work_request_name[] = {"read", "write", "erase", "update"}; main(\|) { long i; for (i = READ; i <= UPDATE; i++) work(i, work_request_name[i]); } void work(long request_type, char *request_name) { static long q_length; TNF_PROBE_2_DEBUG(work_start, "work", "XYZ%debug 'in function work'", tnf_long, request_type_arg, request_type, tnf_string, request_name_arg, request_name); /* assume work request is queued for later processing */ q_length++; TNF_PROBE_1(work_queue, "work queue", "XYZ%work_load heavy", tnf_long, queue_length, q_length); TNF_PROBE_0_DEBUG(work_end, "work", ""); } .fi .in -2 .sp .LP The production probe "work_queue," which remains compiled in the code, will, when enabled, log the length of the work queue each time a request is received. .sp .LP The debug probes "work_start" and "work_end, " which are compiled only during the development phase, track entry to and exit from the \fBwork()\fR function and measure how much time is spent executing it. Additionally, the debug probe "work_start" logs the value of the two incoming arguments \fBrequest_type\fR and \fBrequest_name\fR. The runtime overhead for disabled probes is low enough that one can liberally embed them in the code with little impact on performance. .sp .LP For debugging, the developer would compile with \fB-DTNF_DEBUG\fR, run the program under control of \fBprex\fR(1), enable the probes of interest (in this case, all probes), continue the program until exit, and dump the trace file: .sp .in +2 .nf % cc -DTNF_DEBUG -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 .fi .in -2 .sp .LP For the production version of the system, the developer simply compiles without \fB-DTNF_DEBUG\fR\&. .LP \fBExample 2 \fRTracing the Kernel .sp .LP Kernel tracing is similar to tracing a process; however, there are some differences. For instance, to trace the kernel, you need superuser privileges. The following example uses prex(1) and traces the probes in the kernel that capture system call information. .sp .in +2 .nf 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: 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 .fi .in -2 .sp .LP 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! .sp .LP Examine the kernel trace file: .sp .in +2 .nf root# tnfdump /tmp/ktrace # get ascii dump of trace file .fi .in -2 .sp .LP \fBprex\fR can also attach to a running process, list probes, and perform a variety of other tasks. .SH ATTRIBUTES .sp .LP See \fBattributes\fR(5) for descriptions of the following attributes: .sp .sp .TS box; c | c l | l . ATTRIBUTE TYPE ATTRIBUTE VALUE _ MT Level MT-Safe .TE .SH SEE ALSO .sp .LP \fBprex\fR(1), \fBtnfdump\fR(1), \fBtnfxtract\fR(1), \fBTNF_DECLARE_RECORD\fR(3TNF), \fBTNF_PROBE\fR(3TNF), \fBlibtnfctl\fR(3TNF), \fBtnf_process_disable\fR(3TNF), \fBtnf_kernel_probes\fR(4), \fBattributes\fR(5)