perf/Documentation/perf-script-python.txt

1 perf-script-python(1)
6 perf-script-python - Process trace data with a Python script
11 'perf script' [-s [Python]:script[.py] ]
16 This perf script option is used to process perf script data using perf's
26 raw perf script stream.  You can avoid reading the rest of this
32 'syscall-counts' script you see when you list the available perf script
33 scripts via 'perf script -l'.  As such, this script also shows how to
34 integrate your script into the list of general-purpose 'perf script'
81   allowable by perf.  These individual syscall events will however be
92 don't care how it exited, so we'll use 'perf record' to record only
96 # perf record -a -e raw_syscalls:sys_enter
98 ^C[ perf record: Woken up 1 times to write data ]
99 [ perf record: Captured and wrote 56.545 MB perf.data (~2470503 samples) ]
105 called perf.data.
107 Once we have a perf.data file containing our data, we can use the -g
108 'perf script' option to generate a Python script that will contain a
109 callback handler for each event type found in the perf.data trace
113 # perf script -g python
114 generated Python script: perf-script.py
117 perf-script.py.  Here's the file in its entirety:
119 # perf script event handlers, generated by perf script -g python
126 # See the perf-script-python Documentation for the list of available functions.
132 	'/scripts/python/Perf-Trace-Util/lib/Perf/Trace')
161 path append which every perf script script should include.
169 every event in the 'perf record' output.  The handler functions take
177 every time the script finds an event in the perf.data file that
190 # mv perf-script.py syscall-counts.py
191 # perf script -s syscall-counts.py
193 raw_syscalls__sys_enter     1 00840.847582083     7506 perf                  id=1, args=
194 raw_syscalls__sys_enter     1 00840.847595764     7506 perf                  id=1, args=
195 raw_syscalls__sys_enter     1 00840.847620860     7506 perf                  id=1, args=
217 	'/scripts/python/Perf-Trace-Util/lib/Perf/Trace')
280 	'/scripts/python/Perf-Trace-Util/lib/Perf/Trace')
316   # perf script -s syscall-counts.py
322 'perf list' and/or look in /sys/kernel/tracing/events/ for
324 using 'perf record', passing it the list of interesting events,
325 generate a skeleton script using 'perf script -g python' and modify the
332 scripts listed by the 'perf script -l' command e.g.:
335 # perf script -l
343 probably lengthy 'perf record' command needed to record the events for
351 into the perf/scripts/python/bin directory in the kernel source tree.
352 In that script, you write the 'perf record' command-line needed for
356 # cat kernel-source/tools/perf/scripts/python/bin/syscall-counts-record
359 perf record -a -e raw_syscalls:sys_enter
364 the perf/scripts/python/bin directory.  In that script, you write the
365 'perf script -s' command-line needed for running your script:
368 # cat kernel-source/tools/perf/scripts/python/bin/syscall-counts-report
372 perf script -s ~/libexec/perf-core/scripts/python/syscall-counts.py
376 is in the libexec/perf-core/scripts/python directory - this is where
377 the script will be copied by 'make install' when you install perf.
379 to be located in the perf/scripts/python directory in the kernel
383 # ls -al kernel-source/tools/perf/scripts/python
388 -rw-r--r-- 1 trz trz 2548 2010-01-26 22:29 check-perf-script.py
389 drwxr-xr-x 3 trz trz 4096 2010-01-26 22:49 Perf-Trace-Util
394 otherwise your script won't show up at run-time), 'perf script -l'
398 # perf script -l
406 You can now perform the record step via 'perf script record':
408   # perf script record syscall-counts
410 and display the output using 'perf script report':
412   # perf script report syscall-counts
418 trace data by generating a skeleton script using 'perf script -g
419 python' in the same directory as an existing perf.data trace file.
425 ~/libexec/perf-core/scripts/python for typical examples showing how to
427 the check-perf-script.py script, while not interesting for its results,
433 When perf script is invoked using a trace script, a user-defined
441 available as calls back into the perf executable (see below).
443 As an example, the following perf record command can be used to record
446  # perf record -a -e sched:sched_wakeup
488  context		    an opaque 'cookie' used in calls back into perf
506 Every perf script Python script should start by setting up a Python
515 	      '/scripts/python/Perf-Trace-Util/lib/Perf/Trace')
575 built-in perf script Python modules and their associated functions.
581 via the various perf script Python modules.  To use the functions and
583 import' line to your perf script script.
632 Various utility functions for use with perf script:
679 linkperf:perf-script[1]