All of the remaining fields in the event's format file havecounterparts as handler function arguments of the same name, as can beseen in the example above. The above provides the basics needed to directly access every field ofevery event in a trace, which covers 90% of what you need to know towrite a useful trace script. The sections below cover the rest. SCRIPT LAYOUT------------- Every perf script Python script should start by setting up a Pythonmodule search path and 'import'ing a few support modules (see moduledescriptions below): ---- import os import sys sys.path.append(os.environ['PERF_EXEC_PATH'] + \ '/scripts/python/perf-script-Util/lib/Perf/Trace') from perf_trace_context import * from Core import *---- The rest of the script can contain handler functions and supportfunctions in any order. Aside from the event handler functions discussed above, every scriptcan implement a set of optional functions: *trace_begin*, if defined, is called before any event is processed andgives scripts a chance to do setup tasks: ----def trace_begin: pass---- *trace_end*, if defined, is called after all events have been processed and gives scripts a chance to do end-of-script tasks, such as display results: ----def trace_end: pass---- *trace_unhandled*, if defined, is called after for any event that doesn't have a handler explicitly defined for it. The standard set of common arguments are passed into it: ----def trace_unhandled(event_name, context, common_cpu, common_secs, common_nsecs, common_pid, common_comm): pass---- The remaining sections provide descriptions of each of the availablebuilt-in perf script Python modules and their associated functions. AVAILABLE MODULES AND FUNCTIONS------------------------------- The following sections describe the functions and variables availablevia the various perf script Python modules. To use the functions andvariables from the given module, add the corresponding 'from XXXXimport' line to your perf script script. Core.py Module~~~~~~~~~~~~~~ These functions provide some essential functions to user scripts. The *flag_str* and *symbol_str* functions provide human-readablestrings for flag and symbolic fields. These correspond to the stringsand values parsed from the 'print fmt' fields of the event formatfiles: flag_str(event_name, field_name, field_value) - returns the string represention corresponding to field_value for the flag field field_name of event event_name symbol_str(event_name, field_name, field_value) - returns the string represention corresponding to field_value for the symbolic field field_name of event event_name The *autodict* function returns a special kind of Pythondictionary that implements Perl's 'autovivifying' hashes in Pythoni.e. with autovivifying hashes, you can assign nested hash valueswithout having to go to the trouble of creating intermediate levels ifthey don't exist. autodict() - returns an autovivifying dictionary instance perf_trace_context Module~~~~~~~~~~~~~~~~~~~~~~~~~ Some of the 'common' fields in the event format file aren't all thatcommon, but need to be made accessible to user scripts nonetheless. perf_trace_context defines a set of functions that can be used toaccess this data in the context of the current event. Each of thesefunctions expects a context variable, which is the same as thecontext variable passed into every event handler as the secondargument. common_pc(context) - returns common_preempt count for the current event common_flags(context) - returns common_flags for the current event common_lock_depth(context) - returns common_lock_depth for the current event Util.py Module~~~~~~~~~~~~~~ Various utility functions for use with perf script: nsecs(secs, nsecs) - returns total nsecs given secs/nsecs pair nsecs_secs(nsecs) - returns whole secs portion given nsecs nsecs_nsecs(nsecs) - returns nsecs remainder given nsecs nsecs_str(nsecs) - returns printable string in the form secs.nsecs avg(total, n) - returns average given a sum and a total number of values SEE ALSO--------linkperf:perf-script[1]Lines 501–622 of 622. Previous lines
All of the remaining fields in the event's format file have counterparts as handler function arguments of the same name, as can be seen in the example above. The above provides the basics needed to directly access every field of every event in a trace, which covers 90% of what you need to know to write a useful trace script. The sections below cover the rest. SCRIPT LAYOUT ------------- Every perf script Python script should start by setting up a Python module search path and 'import'ing a few support modules (see module descriptions below): ---- import os import sys sys.path.append(os.environ['PERF_EXEC_PATH'] + \ '/scripts/python/perf-script-Util/lib/Perf/Trace') from perf_trace_context import * from Core import * ---- The rest of the script can contain handler functions and support functions in any order. Aside from the event handler functions discussed above, every script can implement a set of optional functions: *trace_begin*, if defined, is called before any event is processed and gives scripts a chance to do setup tasks: ---- def trace_begin: pass ---- *trace_end*, if defined, is called after all events have been processed and gives scripts a chance to do end-of-script tasks, such as display results: ---- def trace_end: pass ---- *trace_unhandled*, if defined, is called after for any event that doesn't have a handler explicitly defined for it. The standard set of common arguments are passed into it: ---- def trace_unhandled(event_name, context, common_cpu, common_secs, common_nsecs, common_pid, common_comm): pass ---- The remaining sections provide descriptions of each of the available built-in perf script Python modules and their associated functions. AVAILABLE MODULES AND FUNCTIONS ------------------------------- The following sections describe the functions and variables available via the various perf script Python modules. To use the functions and variables from the given module, add the corresponding 'from XXXX import' line to your perf script script. Core.py Module ~~~~~~~~~~~~~~ These functions provide some essential functions to user scripts. The *flag_str* and *symbol_str* functions provide human-readable strings for flag and symbolic fields. These correspond to the strings and values parsed from the 'print fmt' fields of the event format files: flag_str(event_name, field_name, field_value) - returns the string represention corresponding to field_value for the flag field field_name of event event_name symbol_str(event_name, field_name, field_value) - returns the string represention corresponding to field_value for the symbolic field field_name of event event_name The *autodict* function returns a special kind of Python dictionary that implements Perl's 'autovivifying' hashes in Python i.e. with autovivifying hashes, you can assign nested hash values without having to go to the trouble of creating intermediate levels if they don't exist. autodict() - returns an autovivifying dictionary instance perf_trace_context Module ~~~~~~~~~~~~~~~~~~~~~~~~~ Some of the 'common' fields in the event format file aren't all that common, but need to be made accessible to user scripts nonetheless. perf_trace_context defines a set of functions that can be used to access this data in the context of the current event. Each of these functions expects a context variable, which is the same as the context variable passed into every event handler as the second argument. common_pc(context) - returns common_preempt count for the current event common_flags(context) - returns common_flags for the current event common_lock_depth(context) - returns common_lock_depth for the current event Util.py Module ~~~~~~~~~~~~~~ Various utility functions for use with perf script: nsecs(secs, nsecs) - returns total nsecs given secs/nsecs pair nsecs_secs(nsecs) - returns whole secs portion given nsecs nsecs_nsecs(nsecs) - returns nsecs remainder given nsecs nsecs_str(nsecs) - returns printable string in the form secs.nsecs avg(total, n) - returns average given a sum and a total number of values SEE ALSO -------- linkperf:perf-script[1]