Root/
1 | perf-script-perl(1) |
2 | ================== |
3 | |
4 | NAME |
5 | ---- |
6 | perf-script-perl - Process trace data with a Perl script |
7 | |
8 | SYNOPSIS |
9 | -------- |
10 | [verse] |
11 | 'perf script' [-s [Perl]:script[.pl] ] |
12 | |
13 | DESCRIPTION |
14 | ----------- |
15 | |
16 | This perf script option is used to process perf script data using perf's |
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 | |
24 | You can avoid reading the rest of this document by running 'perf script |
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, |
33 | the check-perf-script.pl script, while not interesting for its results, |
34 | attempts to exercise all of the main scripting features. |
35 | |
36 | EVENT HANDLERS |
37 | -------------- |
38 | |
39 | When perf script is invoked using a trace script, a user-defined |
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 | |
52 | # perf record -a -e sched:sched_wakeup |
53 | |
54 | Traces meant to be processed using a script should be recorded with |
55 | the above option: -a to enable system-wide collection. |
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; |
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 | |
114 | Every perf script Perl script should start by setting up a Perl module |
115 | search path and 'use'ing a few support modules (see module |
116 | descriptions below): |
117 | |
118 | ---- |
119 | use lib "$ENV{'PERF_EXEC_PATH'}/scripts/perl/perf-script-Util/lib"; |
120 | use lib "./perf-script-Util/lib"; |
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 |
164 | built-in perf script Perl modules and their associated functions. |
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 |
172 | Perf::Trace::XXX' line to your perf script script. |
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 | |
206 | Various utility functions for use with perf script: |
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 | -------- |
216 | linkperf:perf-script[1] |
217 |
Branches:
ben-wpan
ben-wpan-stefan
javiroman/ks7010
jz-2.6.34
jz-2.6.34-rc5
jz-2.6.34-rc6
jz-2.6.34-rc7
jz-2.6.35
jz-2.6.36
jz-2.6.37
jz-2.6.38
jz-2.6.39
jz-3.0
jz-3.1
jz-3.11
jz-3.12
jz-3.13
jz-3.15
jz-3.16
jz-3.18-dt
jz-3.2
jz-3.3
jz-3.4
jz-3.5
jz-3.6
jz-3.6-rc2-pwm
jz-3.9
jz-3.9-clk
jz-3.9-rc8
jz47xx
jz47xx-2.6.38
master
Tags:
od-2011-09-04
od-2011-09-18
v2.6.34-rc5
v2.6.34-rc6
v2.6.34-rc7
v3.9