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

# NAME

`tprof` —
record tprof profiling samples

# SYNOPSIS

`tprof` | op [arguments]

# DESCRIPTION

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` 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:

list
  Display a list of performance counter events available on the system.
monitor `-e` name:option [`-o` outfile] command
  Monitor the execution of command command. name specifies the name of 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). The collected samples are written into the file outfile if specified. The default is “tprof.out”.
analyze [`-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.
  `-C`
    Don't distinguish CPUs. All samples are treated as its CPU number is 0.
  `-k`
    Kernel only. Ignore samples for userland code.
  `-L`
    Don't distinguish LWPs. All samples are treated as its LWP ID is 0.
  `-P`
    Don't distinguish processes. All samples are treated as its PID is 0.
  `-p` pid
    Process only samples for the process with PID pid and ignore the rest.
  `-s`
    Per symbol.

# EXAMPLES

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`

# SUPPORT

The following CPU models are supported:

- ARMv7
- ARMv8
- x86 AMD Family 10h
- x86 AMD Family 15h
- x86 AMD Family 17h
- x86 Intel Generic (all Intel CPUs)
- x86 Intel Skylake/Kabylake
- x86 Intel Silvermont/Airmont
- x86 Intel Goldmont
- x86 Intel Goldmont Plus

# DIAGNOSTICS

The `tprof` utility reports the following statistics about the activities of the `tprof` 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.

# SEE ALSO

tprof(4)

# AUTHORS

The `tprof` utility was written by YAMAMOTO Takashi. It was revamped by Maxime Villard in 2018.

# CAVEATS

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

October 11, 2019 | NetBSD 9.2