Lines Matching +full:in +full:- +full:functions
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
18 displays the results of the trace analysis implemented in the given
22 ---------------
28 provides more details on each step and lists the library functions
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.
104 That single stream will be recorded in a file in the current directory
107 Once we have a perf.data file containing our data, we can use the -g
109 callback handler for each event type found in the perf.data trace
112 ----
113 # perf script -g python
114 generated Python script: perf-script.py
116 The output file created also in the current directory is named
117 perf-script.py. Here's the file in its entirety:
119 # perf script event handlers, generated by perf script -g python
124 # in the format files. Those fields not available as handler params can
125 # be retrieved using Python functions of the form common_*(context).
126 # See the perf-script-python Documentation for the list of available functions.
132 '/scripts/python/Perf-Trace-Util/lib/Perf/Trace')
138 print "in trace_begin"
141 print "in trace_end"
153 print ' '.join(['%s=%s'%(k,str(v))for k,v in sorted(event_fields_dict.items())])
156 print "%-20s %5u %05u.%09u %8u %-20s " % \
158 ----
163 Following that are a couple generated functions, trace_begin() and
168 Following those are the 'event handler' functions generated one for
169 every event in the 'perf record' output. The handler functions take
171 each field in the event; in this case, there's only one event,
175 The final couple of functions are, like the begin and end functions,
177 every time the script finds an event in the perf.data file that
178 doesn't correspond to any event handler in the script. This could
180 really interested in, or the script was run against a trace file that
183 The script generated by -g option simply prints a line for each
184 event found in the trace stream i.e. it basically just dumps the event
189 ----
190 # mv perf-script.py syscall-counts.py
191 # perf script -s syscall-counts.py
204 ----
206 Of course, for this script, we're not interested in printing every
207 trace event, but rather aggregating it in a useful way. So we'll get
209 trace_unhandled() functions, which we won't be using. That leaves us
212 ----
217 '/scripts/python/Perf-Trace-Util/lib/Perf/Trace')
223 print "in trace_end"
228 ----
230 In trace_end(), we'll simply print the results, but first we need to
238 ----
245 ----
248 (implemented in Core.py) that implements Perl's 'autovivifying' hashes
249 in Python i.e. with autovivifying hashes, you can assign nested hash
254 object itself, the initial value is assigned in the TypeError
255 exception. Well, there may be a better way to do this in Python but
259 effectively end up with a single-level dictionary keyed on syscall id
262 The print_syscall_totals() function iterates over the entries in the
267 displayed after all the events in the trace have been processed, by
271 The final script producing the output shown above is shown in its
275 ----
280 '/scripts/python/Perf-Trace-Util/lib/Perf/Trace')
305 print "%-40s %10s\n" % ("event", "count"),
306 print "%-40s %10s\n" % ("----------------------------------------", \
307 "-----------"),
309 for id, val in sorted(syscalls.iteritems(), key = lambda(k, v): (v, k), \
311 print "%-40s %10d\n" % (syscall_name(id), val),
312 ----
316 # perf script -s syscall-counts.py
318 So those are the essential steps in writing and running a script. The
320 you're interested in - basically find the tracepoint(s) you're
321 interested in by looking at the list of available events shown by
322 'perf list' and/or look in /sys/kernel/tracing/events/ for
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
330 writing a couple of very simple shell scripts and putting them in the
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
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
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
364 the perf/scripts/python/bin directory. In that script, you write the
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 ----
375 Note that the location of the Python script given in the shell script
376 is in the libexec/perf-core/scripts/python directory - this is where
379 to be located in the perf/scripts/python directory in the kernel
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
419 python' in the same directory as an existing perf.data trace file.
421 the event types in the trace file; it simply prints every available
422 field for each event in the trace file.
424 You can also look at the existing scripts in
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
434 'handler function' is called for each event in the trace. If there's
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 ----
479 The common_* arguments in the handler's argument list are the set of
481 to the common_* fields in the format file, but some are synthesized,
483 to every event as arguments but are available as library functions.
488 context an opaque 'cookie' used in calls back into perf
495 All of the remaining fields in the event's format file have
497 seen in the example above.
500 every event in a trace, which covers 90% of what you need to know to
504 -------------
510 ----
515 '/scripts/python/Perf-Trace-Util/lib/Perf/Trace')
519 ----
521 The rest of the script can contain handler functions and support
522 functions in any order.
524 Aside from the event handler functions discussed above, every script
525 can implement a set of optional functions:
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.
577 AVAILABLE MODULES AND FUNCTIONS
578 -------------------------------
580 The following sections describe the functions and variables available
581 via the various perf script Python modules. To use the functions and
588 These functions provide some essential functions to user scripts.
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 …
599 dictionary that implements Perl's 'autovivifying' hashes in Python
604 autodict() - returns an autovivifying dictionary instance
610 Some of the 'common' fields in the event format file aren't all that
613 perf_trace_context defines a set of functions that can be used to
614 access this data in the context of the current event. Each of these
615 functions expects a context variable, which is the same as the
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
632 Various utility functions for use with perf script:
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
673 if 'brstack' in dict:
674 for entry in dict['brstack']:
678 --------
679 linkperf:perf-script[1]