Provided by: systemtap_5.0-2ubuntu1_amd64 bug

NAME

       stap-profile-annotate - Annotate source files of running programs.

SYNOPSIS

       strace-profile-annotate [ OPTIONS ] -d BINARY ...
       strace-profile-annotate [ OPTIONS ] -x PID
       strace-profile-annotate [ OPTIONS ] -c CMD

DESCRIPTION

       The  stap-profile-annotate  command  profiles  selected user-space processes, based on selected profiling
       events over a selected period of time, then produces an annotated source code listings from all the  hits
       on  their executables & shared libraries.  The annotation identifes number of profiling event hits on the
       source files' individual lines.

       The selection of user-space processes and shared libraries may be system-wide (in which case use  the  -d
       option  to  enumerate  all  potentially  interesting  binaries), or may be focused on single pre-existing
       process (-x) or a newly run process  hierarchy  (-c).   SystemTap  automatically  adds  dependent  shared
       libraries for any binary explicitly given by the user.

       The  selection  of  profiling  event may be the default kernel profiling timer (a few hundred Hz), or any
       desired set of systemtap probe points (-e).

       The selected time for the profiling session can be the lifetime of the targeted process, or  a  specified
       timeout (-T), or may be interrupted by the user at any time.

       The  stap-profile-annotate  program  uses  debuginfod  to fetch debuginfo and source files, and therefore
       requires a configured debuginfod-find  program.   If  profiling  locally  built  programs  that  are  not
       available  in  central  debuginfod servers, consider running a local private server temporarily, possibly
       federated to upstream debuginfod servers.

          % export DEBUGINFOD_URLS=https://UPSTREAM.SERVER/
          % debuginfod -p 8002 -d :memory: -F /BUILD/TREE1 /BUILD/TREE2 &

          # export DEBUGINFOD_URLS=http://localhost:8002/
          # stap-profile-annotate [...]

       The resulting annotated source files may be written into subdirectories based on the buildid of the bina‐
       ries, or printed to standard output (-p).

       A profiling session can end before the process it's targeting finishes. In this case, sending  SIGINT  to
       stap-profile-annotate  will yield the script's desired output if sent after "Stopped stap data collector"
       is in stdout. You must still manually kill the targeted process after sending stap-profile-annotate  SIG‐
       INT.

       When  stap is run it adds user-space libraries into the kernel module by default. However, when profiling
       a module which is not a user-space shared library the -d option must be used to add that module's  infor‐
       mation into the SystemTap kernel module.

       stap-profile-annotate  relies heavily on the use of debuginfod. Debuginfod allows the script to fetch de‐
       buginfo and translate virtual memory offsets into source line numbers. It is also used to fetch the actu‐
       al source files to annotate. For these reasons, ensure your debuginfod client is properly configured  for
       use.

OPTIONS

       -h     Show help message.

       -x, --pid PID
              Pre-existing process PID for SystemTap to target.  Its symbol information is automatically includ‐
              ed.

       -c, --cmd CMD
              Command for SystemTap to run and then target.  Its symbol information is automatically included.

       -d BINARY
              Add  symbol  information  for another binary (executable or shared library) and its referenced li‐
              braries.  This option may be repeated.

       -e EVENTS, --events EVENTS
              Use the given SystemTap probe points (comma-separated), instead of the  default  timer.profile  to
              catch profiling hits.  Consider perf.hw.branch_misses.

       -T, --timeout TIMEOUT
              stap-profile-annotate  will exit after TIMEOUT seconds.  Note: if -x or -c, any targeted processes
              will not be killed after this timeout.  Targeted processes either need their own  timeouts  speci‐
              fied or to be killed manually.

       -p, --print
              Print annotated source files to standard output instead of to individual files named like profile-
              BUILDID/source/PATH/FOO.c.

       -w, --context-width WIDTH
              This  option limits the number of lines of context before and after each hit source line.  Without
              this option, the default is to use unlimited context, i.e., print all lines.

       -s, --stap PATH
              Override the path to the systemtap program.

       -v, --verbose
              Increase verbosity.  May be repeated for more verbosity.

EXAMPLES

   Command
       export DEBUGINFOD_URLS=https://debuginfod.elfutils.org/ # if needed
       stap-profile-annotate -w 1 -c '/usr/bin/stress -t 5 --cpu 2'

   Output
       Starting stap data collector.
       stress: info: [88582] dispatching hogs: 4 cpu, 0 io, 0 vm, 0 hdd
       stress: info: [88582] successful run completed in 5s
       Counted 19798 known userspace hits.
       Ignored 12342 kernel hits.
       Stopped stap data collector.
       Consumed 321 profile records of 19798 hits across 3 buildids.
       0001228 (6.20%) hits in profile-10da92de76b289c2e9cfb145ca1edc4e850ec4da/source/usr/src/debug/
            glibc-2.32-10.fc33.x86_64/stdlib/rand.c over 3 lines.
       0004241 (21.42%) hits in profile-10da92de76b289c2e9cfb145ca1edc4e850ec4da/source/usr/src/debug/
            glibc-2.32-10.fc33.x86_64/stdlib/random_r.c over 18 lines.
       0000094 (0.47%) hits in profile-10da92de76b289c2e9cfb145ca1edc4e850ec4da/source/usr/src/debug/
            glibc-2.32-10.fc33.x86_64/stdlib/../sysdeps/unix/sysv/linux/x86/lowlevellock.h over 1 lines.
       0004769 (24.09%) hits in profile-10da92de76b289c2e9cfb145ca1edc4e850ec4da/source/usr/src/debug/
            glibc-2.32-10.fc33.x86_64/stdlib/random.c over 6 lines.
       0001401 (7.08%) hits in profile-520e2b0352d6ac72cb3b58df4f44137e29a94250/source/usr/src/debug/
            stress-1.0.4-26.fc33.x86_64/src/stress.c over 1 lines.
       00001038 (5.24%) hits in buildid 520e2b0352d6ac72cb3b58df4f44137e29a94250 with unknown source
       0003109 (15.70%) hits in profile-07ae52cfc7f4eda1d13383c04564e3236e059993/source/usr/src/debug/
            glibc-2.32-10.fc33.x86_64/math/../sysdeps/ieee754/dbl-64/e_sqrt.c over 3 lines.
       0003918 (19.79%) hits in profile-07ae52cfc7f4eda1d13383c04564e3236e059993/source/usr/src/debug/
            glibc-2.32-10.fc33.x86_64/math/w_sqrt_compat.c over 3 lines.

   Example Annotated Source File
       Found          in:          profile-07ae52cfc7f4eda1d13383c04564e3236e059993/source/          usr/src/de‐
       bug/glibc-2.32-10.fc33.x86_64/math/w_sqrt_compat.c

               {
       0000730   if (__builtin_expect (isless (x, 0.0), 0) && _LIB_VERSION != _IEEE_)
       0000353     return __kernel_standard (x, x, 26); /* sqrt(negative) */

       0002799   return __ieee754_sqrt (x);
               }
               libm_alias_double (__sqrt, sqrt)

SEE ALSO

       stap(1),
       stapprobes(3stap),
       debuginfod-find(1)

                                                                                        STAP-PROFILE-ANNOTATE(1)