TPROF(8) System Manager's Manual TPROF(8)

tprof
record tprof profiling samples

tprof op [arguments]

The tprof tool can be used to monitor hardware events (PMCs) during the execution of certain commands.

The tprof utility makes the kernel driver start profiling, executes the specified command, keeps recording samples from the kernel driver until the command finishes, and reports statistics to the standard error.

The tprof(4) pseudo driver and a suitable backend should be loaded beforehand.

The tprof utility accepts the following options. The first argument, op, specifies the action to take. Valid actions are:

Display the following information:
  • a list of performance counter events available on the system
  • the maximum number of counters that can be used simultaneously
  • the default counter for monitor and top commands
[-e name[:option][,scale]] [-e ...] [-o outfile] command
Monitor the execution of command. The name specifies the event to count; it must be taken from the list of available events. option specifies the source of the event; it must be a combination of u (userland) and k (kernel). If omitted, it is assumed that both are specified. Multiple -e arguments can be specified. If none of the -e arguments are specified, the CPU's default counter is used.

scale specifies the ratio of the speed to the cycle counter, or the counter until overflow. The counter reset value on overflow used for profiling is calculated from the speed of the cycle counter by default, but for some events this value may be too large (counter increasing too slowly) to be sufficient for profiling. For example, to specify an event that increases about 1000 times slower than the cycle counter, specify ‘-e event,1000’. Also, if ‘-e event,=200’ is specified, profiling is performed every time the counter is increased by 200.

The collected samples are written into the file outfile if specified. The default is tprof.out.

-e name[:option] [-e ...] [-i interval] command
Same as monitor, but does not do any profiling, only outputs counters every interval second.
[-CkLPs] [-p pid] file
Analyze the samples produced by a previous run of tprof, stored in file, and generate a plain text representation of them.
Don't distinguish CPUs. All samples are treated as its CPU number is 0.
Kernel only. Ignore samples for userland code.
Don't distinguish LWPs. All samples are treated as its LWP ID is 0.
Don't distinguish processes. All samples are treated as its PID is 0.
pid
Process only samples for the process with PID pid and ignore the rest.
Per symbol.
[-acu] [-e name[,scale]] [-e ...] [-i interval]
Displays profiling results in real-time. name specifies the name of the event to count.
Starts in accumulation mode. The display is updated every interval second, but the values are accumulative.
Show the delta of the event counters.
interval
Set the update interval in seconds. The default value is 1.
Userland processes are also included in the profiling.

While tprof top is running, it accepts commands from the terminal. These commands are currently recognized:

a
toggle accumurative mode.
c
shows/hides the event counters.
q
quit tprof.
z
clear accumulated data.

The following command profiles the system during 20 seconds and writes the samples into the file myfile.out.

# tprof monitor -e llc-misses:k -o myfile.out sleep 20

The following command displays the results of the sampling.

# tprof analyze myfile.out

The following CPU models are supported:

The tprof utility reports the following statistics about the activities of the tprof(4) pseudo driver.
sample
The number of samples collected and prepared for userland consumption.
overflow
The number of samples dropped because the per-CPU buffer was full.
buf
The number of buffers successfully prepared for userland consumption.
emptybuf
The number of buffers which have been dropped because they were empty.
dropbuf
The number of buffers dropped because the number of buffers kept in the kernel exceeds the limit.
dropbuf_samples
The number of samples dropped because the buffers containing the samples were dropped.

tprof(4)

The tprof utility was written by YAMAMOTO Takashi. It was revamped by Maxime Villard in 2018, and by Ryo Shimizu in 2022.

The contents and representation of recorded samples are undocumented and will likely be changed for future releases of NetBSD in an incompatible way.
April 17, 2023 NetBSD 10.0