tprof(8) - NetBSD Manual Pages

Command:
Section:
Arch:
Collection:
>>>
TPROF(8)                NetBSD 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 before-
     hand.

     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 user-
                      land 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 con-
                      taining 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.

NetBSD 9.2                     October 11, 2019                     NetBSD 9.2