Updated: 2022/Sep/29

Please read Privacy Policy. It's for your privacy.


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

     list        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

     monitor [-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.

     count -e name[:option] [-e ...] [-i interval] command
                 Same as monitor, but does not do any profiling, only outputs
                 counters every interval second.

     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.

     top [-acu] [-e name[,scale]] [-e ...] [-i interval]
                 Displays profiling results in real-time.  name specifies the
                 name of the event to count.

                 -a          Starts in accumulation mode.  The display is
                             updated every interval second, but the values are
                             accumulative.

                 -c          Show the delta of the event counters.

                 -i interval
                             Set the update interval in seconds.  The default
                             value is 1.

                 -u          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.

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 AMD Family 19h
           -   x86 Intel Generic (all Intel CPUs)
           -   x86 Intel Skylake, Kabylake and Cometlake
           -   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(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.

SEE ALSO
     tprof(4)

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

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

NetBSD 10.99                    April 17, 2023                    NetBSD 10.99