Commit | Line | Data |
---|---|---|
133dc4c3 | 1 | perf-script-perl(1) |
89fbf0b8 TZ |
2 | ================== |
3 | ||
4 | NAME | |
5 | ---- | |
133dc4c3 | 6 | perf-script-perl - Process trace data with a Perl script |
89fbf0b8 TZ |
7 | |
8 | SYNOPSIS | |
9 | -------- | |
10 | [verse] | |
133dc4c3 | 11 | 'perf script' [-s [Perl]:script[.pl] ] |
89fbf0b8 TZ |
12 | |
13 | DESCRIPTION | |
14 | ----------- | |
15 | ||
133dc4c3 | 16 | This perf script option is used to process perf script data using perf's |
89fbf0b8 TZ |
17 | built-in Perl interpreter. It reads and processes the input file and |
18 | displays the results of the trace analysis implemented in the given | |
19 | Perl script, if any. | |
20 | ||
21 | STARTER SCRIPTS | |
22 | --------------- | |
23 | ||
133dc4c3 | 24 | You can avoid reading the rest of this document by running 'perf script |
89fbf0b8 TZ |
25 | -g perl' in the same directory as an existing perf.data trace file. |
26 | That will generate a starter script containing a handler for each of | |
27 | the event types in the trace file; it simply prints every available | |
28 | field for each event in the trace file. | |
29 | ||
30 | You can also look at the existing scripts in | |
31 | ~/libexec/perf-core/scripts/perl for typical examples showing how to | |
32 | do basic things like aggregate event data, print results, etc. Also, | |
133dc4c3 | 33 | the check-perf-script.pl script, while not interesting for its results, |
89fbf0b8 TZ |
34 | attempts to exercise all of the main scripting features. |
35 | ||
36 | EVENT HANDLERS | |
37 | -------------- | |
38 | ||
133dc4c3 | 39 | When perf script is invoked using a trace script, a user-defined |
89fbf0b8 TZ |
40 | 'handler function' is called for each event in the trace. If there's |
41 | no handler function defined for a given event type, the event is | |
42 | ignored (or passed to a 'trace_handled' function, see below) and the | |
43 | next event is processed. | |
44 | ||
45 | Most of the event's field values are passed as arguments to the | |
46 | handler function; some of the less common ones aren't - those are | |
47 | available as calls back into the perf executable (see below). | |
48 | ||
49 | As an example, the following perf record command can be used to record | |
50 | all sched_wakeup events in the system: | |
51 | ||
e5a5f1f0 | 52 | # perf record -a -e sched:sched_wakeup |
89fbf0b8 TZ |
53 | |
54 | Traces meant to be processed using a script should be recorded with | |
e5a5f1f0 | 55 | the above option: -a to enable system-wide collection. |
89fbf0b8 TZ |
56 | |
57 | The format file for the sched_wakep event defines the following fields | |
58 | (see /sys/kernel/debug/tracing/events/sched/sched_wakeup/format): | |
59 | ||
60 | ---- | |
61 | format: | |
62 | field:unsigned short common_type; | |
63 | field:unsigned char common_flags; | |
64 | field:unsigned char common_preempt_count; | |
65 | field:int common_pid; | |
89fbf0b8 TZ |
66 | |
67 | field:char comm[TASK_COMM_LEN]; | |
68 | field:pid_t pid; | |
69 | field:int prio; | |
70 | field:int success; | |
71 | field:int target_cpu; | |
72 | ---- | |
73 | ||
74 | The handler function for this event would be defined as: | |
75 | ||
76 | ---- | |
77 | sub sched::sched_wakeup | |
78 | { | |
79 | my ($event_name, $context, $common_cpu, $common_secs, | |
80 | $common_nsecs, $common_pid, $common_comm, | |
81 | $comm, $pid, $prio, $success, $target_cpu) = @_; | |
82 | } | |
83 | ---- | |
84 | ||
85 | The handler function takes the form subsystem::event_name. | |
86 | ||
87 | The $common_* arguments in the handler's argument list are the set of | |
88 | arguments passed to all event handlers; some of the fields correspond | |
89 | to the common_* fields in the format file, but some are synthesized, | |
90 | and some of the common_* fields aren't common enough to to be passed | |
91 | to every event as arguments but are available as library functions. | |
92 | ||
93 | Here's a brief description of each of the invariant event args: | |
94 | ||
95 | $event_name the name of the event as text | |
96 | $context an opaque 'cookie' used in calls back into perf | |
97 | $common_cpu the cpu the event occurred on | |
98 | $common_secs the secs portion of the event timestamp | |
99 | $common_nsecs the nsecs portion of the event timestamp | |
100 | $common_pid the pid of the current task | |
101 | $common_comm the name of the current process | |
102 | ||
103 | All of the remaining fields in the event's format file have | |
104 | counterparts as handler function arguments of the same name, as can be | |
105 | seen in the example above. | |
106 | ||
107 | The above provides the basics needed to directly access every field of | |
108 | every event in a trace, which covers 90% of what you need to know to | |
109 | write a useful trace script. The sections below cover the rest. | |
110 | ||
111 | SCRIPT LAYOUT | |
112 | ------------- | |
113 | ||
133dc4c3 | 114 | Every perf script Perl script should start by setting up a Perl module |
89fbf0b8 TZ |
115 | search path and 'use'ing a few support modules (see module |
116 | descriptions below): | |
117 | ||
118 | ---- | |
133dc4c3 IM |
119 | use lib "$ENV{'PERF_EXEC_PATH'}/scripts/perl/perf-script-Util/lib"; |
120 | use lib "./perf-script-Util/lib"; | |
89fbf0b8 TZ |
121 | use Perf::Trace::Core; |
122 | use Perf::Trace::Context; | |
123 | use Perf::Trace::Util; | |
124 | ---- | |
125 | ||
126 | The rest of the script can contain handler functions and support | |
127 | functions in any order. | |
128 | ||
129 | Aside from the event handler functions discussed above, every script | |
130 | can implement a set of optional functions: | |
131 | ||
132 | *trace_begin*, if defined, is called before any event is processed and | |
133 | gives scripts a chance to do setup tasks: | |
134 | ||
135 | ---- | |
136 | sub trace_begin | |
137 | { | |
138 | } | |
139 | ---- | |
140 | ||
141 | *trace_end*, if defined, is called after all events have been | |
142 | processed and gives scripts a chance to do end-of-script tasks, such | |
143 | as display results: | |
144 | ||
145 | ---- | |
146 | sub trace_end | |
147 | { | |
148 | } | |
149 | ---- | |
150 | ||
151 | *trace_unhandled*, if defined, is called after for any event that | |
152 | doesn't have a handler explicitly defined for it. The standard set | |
153 | of common arguments are passed into it: | |
154 | ||
155 | ---- | |
156 | sub trace_unhandled | |
157 | { | |
158 | my ($event_name, $context, $common_cpu, $common_secs, | |
159 | $common_nsecs, $common_pid, $common_comm) = @_; | |
160 | } | |
161 | ---- | |
162 | ||
163 | The remaining sections provide descriptions of each of the available | |
133dc4c3 | 164 | built-in perf script Perl modules and their associated functions. |
89fbf0b8 TZ |
165 | |
166 | AVAILABLE MODULES AND FUNCTIONS | |
167 | ------------------------------- | |
168 | ||
169 | The following sections describe the functions and variables available | |
170 | via the various Perf::Trace::* Perl modules. To use the functions and | |
171 | variables from the given module, add the corresponding 'use | |
133dc4c3 | 172 | Perf::Trace::XXX' line to your perf script script. |
89fbf0b8 TZ |
173 | |
174 | Perf::Trace::Core Module | |
175 | ~~~~~~~~~~~~~~~~~~~~~~~~ | |
176 | ||
177 | These functions provide some essential functions to user scripts. | |
178 | ||
179 | The *flag_str* and *symbol_str* functions provide human-readable | |
180 | strings for flag and symbolic fields. These correspond to the strings | |
181 | and values parsed from the 'print fmt' fields of the event format | |
182 | files: | |
183 | ||
184 | 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 | |
185 | 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 | |
186 | ||
187 | Perf::Trace::Context Module | |
188 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
189 | ||
190 | Some of the 'common' fields in the event format file aren't all that | |
191 | common, but need to be made accessible to user scripts nonetheless. | |
192 | ||
193 | Perf::Trace::Context defines a set of functions that can be used to | |
194 | access this data in the context of the current event. Each of these | |
195 | functions expects a $context variable, which is the same as the | |
196 | $context variable passed into every event handler as the second | |
197 | argument. | |
198 | ||
199 | common_pc($context) - returns common_preempt count for the current event | |
200 | common_flags($context) - returns common_flags for the current event | |
201 | common_lock_depth($context) - returns common_lock_depth for the current event | |
202 | ||
203 | Perf::Trace::Util Module | |
204 | ~~~~~~~~~~~~~~~~~~~~~~~~ | |
205 | ||
133dc4c3 | 206 | Various utility functions for use with perf script: |
89fbf0b8 TZ |
207 | |
208 | nsecs($secs, $nsecs) - returns total nsecs given secs/nsecs pair | |
209 | nsecs_secs($nsecs) - returns whole secs portion given nsecs | |
210 | nsecs_nsecs($nsecs) - returns nsecs remainder given nsecs | |
211 | nsecs_str($nsecs) - returns printable string in the form secs.nsecs | |
212 | avg($total, $n) - returns average given a sum and a total number of values | |
213 | ||
214 | SEE ALSO | |
215 | -------- | |
133dc4c3 | 216 | linkperf:perf-script[1] |