perf/Documentation/perf-script-python.txt

1 perf-script-python(1)
5 ----
6 perf-script-python - Process trace data with a Python script
9 --------
11 'perf script' [-s [Python]:script[.py] ]
14 -----------
17 built-in Python interpreter.  It reads and processes the input file and
22 ---------------
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'
37 The syscall-counts script is a simple script, but demonstrates all the
42 ----
46 ----------------------------------------  -----------
71 ----
73 Basically our task is to keep a per-syscall tally that gets updated
74 every time a system call occurs in the system.  Our script will do
79 - we could enable every event under the tracing/events/syscalls
83   general-purpose scripts to drill down and get more detail about
86 - we can enable the sys_enter and/or sys_exit syscalls found under
95 ----
96 # perf record -a -e raw_syscalls:sys_enter
100 ----
103 system-wide and multiplex the per-cpu output into a single stream.
107 Once we have a perf.data file containing our data, we can use the -g
112 ----
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')
156 	print "%-20s %5u %05u.%09u %8u %-20s " % \
158 ----
183 The script generated by -g option simply prints a line for each
189 ----
190 # mv perf-script.py syscall-counts.py
191 # perf script -s syscall-counts.py
204 ----
212 ----
217 	'/scripts/python/Perf-Trace-Util/lib/Perf/Trace')
228 ----
238 ----
245 ----
259 effectively end up with a single-level dictionary keyed on syscall id
275 ----
280 	'/scripts/python/Perf-Trace-Util/lib/Perf/Trace')
305     print "%-40s  %10s\n" % ("event", "count"),
306     print "%-40s  %10s\n" % ("----------------------------------------", \
307                                  "-----------"),
311 	    print "%-40s  %10d\n" % (syscall_name(id), val),
312 ----
316   # perf script -s syscall-counts.py
320 you're interested in - basically find the tracepoint(s) you're
325 generate a skeleton script using 'perf script -g python' and modify the
328 After you've done that you may end up with a general-purpose script
332 scripts listed by the 'perf script -l' command e.g.:
334 ----
335 # perf script -l
337   wakeup-latency                       system-wide min/max/avg wakeup latency
338   rw-by-file <comm>                    r/w activity for a program, by file
339   rw-by-pid                            system-wide r/w activity
340 ----
346 To have the script appear as a 'built-in' script, you write two simple
350 script, but with -record appended.  The shell script should be put
352 In that script, you write the 'perf record' command-line needed for
355 ----
356 # cat kernel-source/tools/perf/scripts/python/bin/syscall-counts-record
359 perf record -a -e raw_syscalls:sys_enter
360 ----
363 your script, but with -report appended.  It should also be located in
365 'perf script -s' command-line needed for running your script:
367 ----
368 # cat kernel-source/tools/perf/scripts/python/bin/syscall-counts-report
371 # description: system-wide syscall counts
372 perf script -s ~/libexec/perf-core/scripts/python/syscall-counts.py
373 ----
376 is in the libexec/perf-core/scripts/python directory - this is where
382 ----
383 # ls -al kernel-source/tools/perf/scripts/python
385 drwxr-xr-x 4 trz trz 4096 2010-01-26 22:30 .
386 drwxr-xr-x 4 trz trz 4096 2010-01-26 22:29 ..
387 drwxr-xr-x 2 trz trz 4096 2010-01-26 22:29 bin
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
390 -rw-r--r-- 1 trz trz 1462 2010-01-26 22:30 syscall-counts.py
391 ----
394 otherwise your script won't show up at run-time), 'perf script -l'
397 ----
398 # perf script -l
400   wakeup-latency                       system-wide min/max/avg wakeup latency
401   rw-by-file <comm>                    r/w activity for a program, by file
402   rw-by-pid                            system-wide r/w activity
403   syscall-counts                       system-wide syscall counts
404 ----
408   # perf script record syscall-counts
412   # perf script report syscall-counts
415 ---------------
418 trace data by generating a skeleton script using 'perf script -g
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,
431 --------------
433 When perf script is invoked using a trace script, a user-defined
440 handler function; some of the less common ones aren't - those are
444 all sched_wakeup events in the system:
446  # perf record -a -e sched:sched_wakeup
449 the above option: -a to enable system-wide collection.
454 ----
466 ----
470 ----
475 ----
504 -------------
510 ----
515 	      '/scripts/python/Perf-Trace-Util/lib/Perf/Trace')
519 ----
530 ----
533 ----
536  processed and gives scripts a chance to do end-of-script tasks, such
539 ----
542 ----
548 ----
551 ----
553 *process_event*, if defined, is called for any non-tracepoint event
555 ----
558 ----
562 ----
565 ----
569 ----
572 ----
575 built-in perf script Python modules and their associated functions.
578 -------------------------------
590 The *flag_str* and *symbol_str* functions provide human-readable
595 …flag_str(event_name, field_name, field_value) - returns the string representation corresponding to…
596 …symbol_str(event_name, field_name, field_value) - returns the string representation corresponding …
604   autodict() - returns an autovivifying dictionary instance
617 argument. For non-tracepoint events, the context variable is also present
620  common_pc(context) - returns common_preempt count for the current event
621  common_flags(context) - returns common_flags for the current event
622  common_lock_depth(context) - returns common_lock_depth for the current event
623  perf_sample_insn(context) - returns the machine code instruction
624 …perf_set_itrace_options(context, itrace_options) - set --itrace options if they have not been set …
625  perf_sample_srcline(context) - returns source_file_name, line_number
626  perf_sample_srccode(context) - returns source_file_name, line_number, source_line
634   nsecs(secs, nsecs) - returns total nsecs given secs/nsecs pair
635   nsecs_secs(nsecs) - returns whole secs portion given nsecs
636   nsecs_nsecs(nsecs) - returns nsecs remainder given nsecs
637   nsecs_str(nsecs) - returns printable string in the form secs.nsecs
638   avg(total, n) - returns average given a sum and a total number of values
641 ----------------
652  flags - sample flags
653  flags_disp - sample flags display
654  insn_cnt - instruction count for determining instructions-per-cycle (IPC)
655  cyc_cnt - cycle count for determining IPC
656  addr_correlates_sym - addr can correlate to a symbol
657  addr_dso - addr dso
658  addr_symbol - addr symbol
659  addr_symoff - addr symbol offset
678 --------
679 linkperf:perf-script[1]