0001 perf-script-perl(1)
0002 ===================
0003
0004 NAME
0005 ----
0006 perf-script-perl - Process trace data with a Perl script
0007
0008 SYNOPSIS
0009 --------
0010 [verse]
0011 'perf script' [-s [Perl]:script[.pl] ]
0012
0013 DESCRIPTION
0014 -----------
0015
0016 This perf script option is used to process perf script data using perf's
0017 built-in Perl interpreter. It reads and processes the input file and
0018 displays the results of the trace analysis implemented in the given
0019 Perl script, if any.
0020
0021 STARTER SCRIPTS
0022 ---------------
0023
0024 You can avoid reading the rest of this document by running 'perf script
0025 -g perl' in the same directory as an existing perf.data trace file.
0026 That will generate a starter script containing a handler for each of
0027 the event types in the trace file; it simply prints every available
0028 field for each event in the trace file.
0029
0030 You can also look at the existing scripts in
0031 ~/libexec/perf-core/scripts/perl for typical examples showing how to
0032 do basic things like aggregate event data, print results, etc. Also,
0033 the check-perf-script.pl script, while not interesting for its results,
0034 attempts to exercise all of the main scripting features.
0035
0036 EVENT HANDLERS
0037 --------------
0038
0039 When perf script is invoked using a trace script, a user-defined
0040 'handler function' is called for each event in the trace. If there's
0041 no handler function defined for a given event type, the event is
0042 ignored (or passed to a 'trace_unhandled' function, see below) and the
0043 next event is processed.
0044
0045 Most of the event's field values are passed as arguments to the
0046 handler function; some of the less common ones aren't - those are
0047 available as calls back into the perf executable (see below).
0048
0049 As an example, the following perf record command can be used to record
0050 all sched_wakeup events in the system:
0051
0052 # perf record -a -e sched:sched_wakeup
0053
0054 Traces meant to be processed using a script should be recorded with
0055 the above option: -a to enable system-wide collection.
0056
0057 The format file for the sched_wakeup event defines the following fields
0058 (see /sys/kernel/debug/tracing/events/sched/sched_wakeup/format):
0059
0060 ----
0061 format:
0062 field:unsigned short common_type;
0063 field:unsigned char common_flags;
0064 field:unsigned char common_preempt_count;
0065 field:int common_pid;
0066
0067 field:char comm[TASK_COMM_LEN];
0068 field:pid_t pid;
0069 field:int prio;
0070 field:int success;
0071 field:int target_cpu;
0072 ----
0073
0074 The handler function for this event would be defined as:
0075
0076 ----
0077 sub sched::sched_wakeup
0078 {
0079 my ($event_name, $context, $common_cpu, $common_secs,
0080 $common_nsecs, $common_pid, $common_comm,
0081 $comm, $pid, $prio, $success, $target_cpu) = @_;
0082 }
0083 ----
0084
0085 The handler function takes the form subsystem::event_name.
0086
0087 The $common_* arguments in the handler's argument list are the set of
0088 arguments passed to all event handlers; some of the fields correspond
0089 to the common_* fields in the format file, but some are synthesized,
0090 and some of the common_* fields aren't common enough to to be passed
0091 to every event as arguments but are available as library functions.
0092
0093 Here's a brief description of each of the invariant event args:
0094
0095 $event_name the name of the event as text
0096 $context an opaque 'cookie' used in calls back into perf
0097 $common_cpu the cpu the event occurred on
0098 $common_secs the secs portion of the event timestamp
0099 $common_nsecs the nsecs portion of the event timestamp
0100 $common_pid the pid of the current task
0101 $common_comm the name of the current process
0102
0103 All of the remaining fields in the event's format file have
0104 counterparts as handler function arguments of the same name, as can be
0105 seen in the example above.
0106
0107 The above provides the basics needed to directly access every field of
0108 every event in a trace, which covers 90% of what you need to know to
0109 write a useful trace script. The sections below cover the rest.
0110
0111 SCRIPT LAYOUT
0112 -------------
0113
0114 Every perf script Perl script should start by setting up a Perl module
0115 search path and 'use'ing a few support modules (see module
0116 descriptions below):
0117
0118 ----
0119 use lib "$ENV{'PERF_EXEC_PATH'}/scripts/perl/Perf-Trace-Util/lib";
0120 use lib "./Perf-Trace-Util/lib";
0121 use Perf::Trace::Core;
0122 use Perf::Trace::Context;
0123 use Perf::Trace::Util;
0124 ----
0125
0126 The rest of the script can contain handler functions and support
0127 functions in any order.
0128
0129 Aside from the event handler functions discussed above, every script
0130 can implement a set of optional functions:
0131
0132 *trace_begin*, if defined, is called before any event is processed and
0133 gives scripts a chance to do setup tasks:
0134
0135 ----
0136 sub trace_begin
0137 {
0138 }
0139 ----
0140
0141 *trace_end*, if defined, is called after all events have been
0142 processed and gives scripts a chance to do end-of-script tasks, such
0143 as display results:
0144
0145 ----
0146 sub trace_end
0147 {
0148 }
0149 ----
0150
0151 *trace_unhandled*, if defined, is called after for any event that
0152 doesn't have a handler explicitly defined for it. The standard set
0153 of common arguments are passed into it:
0154
0155 ----
0156 sub trace_unhandled
0157 {
0158 my ($event_name, $context, $common_cpu, $common_secs,
0159 $common_nsecs, $common_pid, $common_comm) = @_;
0160 }
0161 ----
0162
0163 The remaining sections provide descriptions of each of the available
0164 built-in perf script Perl modules and their associated functions.
0165
0166 AVAILABLE MODULES AND FUNCTIONS
0167 -------------------------------
0168
0169 The following sections describe the functions and variables available
0170 via the various Perf::Trace::* Perl modules. To use the functions and
0171 variables from the given module, add the corresponding 'use
0172 Perf::Trace::XXX' line to your perf script script.
0173
0174 Perf::Trace::Core Module
0175 ~~~~~~~~~~~~~~~~~~~~~~~~
0176
0177 These functions provide some essential functions to user scripts.
0178
0179 The *flag_str* and *symbol_str* functions provide human-readable
0180 strings for flag and symbolic fields. These correspond to the strings
0181 and values parsed from the 'print fmt' fields of the event format
0182 files:
0183
0184 flag_str($event_name, $field_name, $field_value) - returns the string representation corresponding to $field_value for the flag field $field_name of event $event_name
0185 symbol_str($event_name, $field_name, $field_value) - returns the string representation corresponding to $field_value for the symbolic field $field_name of event $event_name
0186
0187 Perf::Trace::Context Module
0188 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
0189
0190 Some of the 'common' fields in the event format file aren't all that
0191 common, but need to be made accessible to user scripts nonetheless.
0192
0193 Perf::Trace::Context defines a set of functions that can be used to
0194 access this data in the context of the current event. Each of these
0195 functions expects a $context variable, which is the same as the
0196 $context variable passed into every event handler as the second
0197 argument.
0198
0199 common_pc($context) - returns common_preempt count for the current event
0200 common_flags($context) - returns common_flags for the current event
0201 common_lock_depth($context) - returns common_lock_depth for the current event
0202
0203 Perf::Trace::Util Module
0204 ~~~~~~~~~~~~~~~~~~~~~~~~
0205
0206 Various utility functions for use with perf script:
0207
0208 nsecs($secs, $nsecs) - returns total nsecs given secs/nsecs pair
0209 nsecs_secs($nsecs) - returns whole secs portion given nsecs
0210 nsecs_nsecs($nsecs) - returns nsecs remainder given nsecs
0211 nsecs_str($nsecs) - returns printable string in the form secs.nsecs
0212 avg($total, $n) - returns average given a sum and a total number of values
0213
0214 SEE ALSO
0215 --------
0216 linkperf:perf-script[1]
