ktracer.1m (2010 09)

ManualsBrandsHP ManualsSoftwareHP-UX Manpages

ktracer(1M) ktracer(1M)

NAME

ktracer - kernel tracer

SYNOPSIS

Getting Started

ktracer [-R][-L

][-b][-B][-h][-w workload ][

-g numsec]

Changing the Function List

[

-a func]... [-e

[mod:]pattern]... [-l lib ]... [-m mod]... [

-r func]... [-S func ]... [-z]

Installing the Function List

[

-I][-U]

Managing Memory for Traces

[

-A numtraces ][-f

][-Z]

General Interest

[

-?][-t][

-D ktracedump-options][

-p pid]

Remarks

See

http://hp.com/go/ktracer

DESCRIPTION

HP-UX kernel tracing is a powerful, indispensable facility for debugging kernel problems and for under-

standing kernel behavior. It gives insight into kernel events and activity by capturing data across all

CPUs about kernel function call sequence, parameters, and timing.

Kernel tracing on HP-UX is comprised of kernel and userspace components.

The

ktracer component in the kernel collects and stores trace records in trace buffers in kernel

memory. The ktracer program is a userspace component that gives its user control over how much

memory to allocate for trace buffers, which functions to trace, and when to start and stop tracing on a live

system.

The

ktracedump program is another userspace component that retrieves the trace records and traced

function list either from the live kernel or from a kernel dump. ktracedump then formats the output in

accordance with user speciﬁcations.

NOTE: The word ktracer is used for both the individual

ktracer program and for the whole kernel

tracing facility (which includes the kernel component, the ktracer program, and the ktracedump pro-

gram). See ktracedump (1M) for more information about ktracedump.

Kernel tracing is particularly useful in understanding what the kernel is doing, for the purpose of educa-

tion, as well as analysis. Kernel tracing is useful to debug panics and hangs, and useful in making

software design choices.

HP-UX is capable of tracing kernel calls along the boot path.

With the September 2008 release of HP-UX 11i Version 3 Update 3, ktracer is newly supported for cus-

tomer use on Integrity systems only.

Kernel support for

ktracer is sensitive to the underlying HP-UX release version and processor architec-

ture on which it runs.

ktracer runs on HP Integrity Virtual Machines (HPVM) running HP-UX 11i v3 Update 3 or later.

Information about Virtual Machines is at http://www.docs.hp.com/en/vse.html

Functions

ktracer can trace thousands of kernel functions. ktracer is capable of tracing almost all nonleaf

functions written in C, most leaf functions on Integrity platforms, and also some functions written in

assembly. The set of traced functions can be any subset of the traceable functions. To produce a list of all

traceable functions in a given system, run the following command:

# ktracer -R -h; ktracedump -DNF > traceable_functions

Processes

ktracer can trace all processes or a selected process. See the -p option.

HP-UX 11i Version 3: September 2010 − 1 − Hewlett-Packard Company 1

Summary of content (12 pages)

PAGE 1
ktracer(1M) ktracer(1M) NAME ktracer - kernel tracer SYNOPSIS Getting Started ktracer [-R] [-L] [-b] [-B] [-h] [-w workload ] [-g numsec ] Changing the Function List [-a func ]... [-e [mod:]pattern]... [-l lib ]... [-m mod]... [-r func ]... [-S func ]... [-z] Installing the Function List [-I] [-U] Managing Memory for Traces [-A numtraces ] [-f] [-Z] General Interest [-?] [-t] [-D ktracedump-options] [-p pid ] Remarks See http://hp.com/go/ktracer.
PAGE 2
ktracer(1M) ktracer(1M) When Are Trace Records Captured? The kernel captures one trace record each and every time that it encounters a trace point, as long as the following situations occur: • • • Tracing status is on. The process executing the trace point is selected for tracing. The CPU executing the trace point has memory allocated for its trace buffer.
PAGE 3
ktracer(1M) ktracer(1M) Option Status Description Getting Started -R on Reasonable. Start tracing all functions (heavyweight) -L on Lightweight. Start tracing key functions (lightweight) -b on Begin tracing. Start intercepting and tracing functions -B on Begin tracing. Same as -b -h off Halt.
PAGE 4
ktracer(1M) • ktracer(1M) Begin tracing (-b). The -R option is the simplest way to get started. This option tells ktracer to trace everything possible, and to begin immediately. It does not matter what state ktracer was in before using this option. ktracer -R achieves a known state of allocated, installed and active. To get the full list of traced functions, run ktracedump -FND.
PAGE 5
ktracer(1M) ktracer(1M) Halt is normally used before running ktracedump to see the trace output. When functions are intercepted, system performance degrades in proportion to how often intercepted functions are called. When ktracer stops intercepting functions, then path flow and system performance are restored to normal. To start ktracer after a halt, use the -b option. -g #seconds An all-in-one way to gather trace data for the specified number of seconds.
PAGE 6
ktracer(1M) ktracer(1M) To obtain the hexadecimal addresses for each kernel function name, use the following command: # /bin/nm -p -v -x /stand/vmunix To obtain the decimal addresses for each kernel function name, use the following command: # /bin/nm -p -v /stand/vmunix If several local or static functions have the same name, specifying them by address provides a way to distinguish them. The following example shows how to trace both of the functions named "rand".
PAGE 7
ktracer(1M) ktracer(1M) client or server code or otherwise. # ktracer -m iexgbe -m nfs* -B Functions from statically linked modules and functions from dynamically loadable kernel modules (DLKMs) are traceable. In the event that a DLKM is unloaded while functions within it are being traced, ktracer will stop tracing those functions that get unloaded, while continuing to trace the rest.
PAGE 8
ktracer(1M) ktracer(1M) many conditions that can lead to an early return from it without collecting a trace record. These conditions include but are not limited to the following: 1. 2. 3. 4. Tracing is OFF, because it was halted or not begun, or a stop function was encountered. The executing process does not match selected process to trace (see the -p option). No trace buffer is allocated on current CPU (see the -A option). The trace buffer is full AND linear buffers (not circular) were chosen.
PAGE 9
ktracer(1M) -f ktracer(1M) Free the memory allocated by ktracer, namely the per-CPU trace buffers and the function list. After completing a session of kernel tracing and CR ktracedump report generation, invoking -f is recommended, particularly if not much physical memory is available on the system. General Interest -? Print the ktracer usage message. Describe the options of the ktracer command briefly. -t Print current status of ktracer.
PAGE 10
ktracer(1M) ktracer(1M) The above command actually prints a brief ktracedump usage message to /dev/null. This command is convenient to defer the overhead of ktracedump processing until later (for example, when the system has less of a load). LIMITATIONS Traces are only collected at function entry, not at function exit or elsewhere. Therefore, the "Elapsed Times" are from function entry to function entry. You will not see when a function exited or what value it returned.
PAGE 11
ktracer(1M) ktracer(1M) Certain functions known to ktracer are excluded because tracing their execution is potentially problematic. These ktracer add failures are based on the function characteristics, and do not vary based on which add option is used: -a, -e, -l, -m, or -S. When a request is made to add an untraceable function to list, the outcome is that an error message will be reported, and the requested function will not be added and will not be traced when it executes.
PAGE 12
ktracer(1M) ktracer(1M) AUTHOR ktracer was developed by HP. FILES Trace buffers are stored in kernel memory and not in any files. SEE ALSO egrep(1), sh(1), ktracedump(1M), privileges(5), regexp(5). For information on how to obtain ktracer, go to: http://hp.com/go/ktracer or http://hp.com/go/caliper Click on the documentation link and then click on HP Caliper Ktrace Features Guide . The Caliper 5.