1 perf-script-perl(1)
2 ===================
3
4 NAME
5 ----
6 perf-script-perl - Process trace data with a P
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 per
17 built-in Perl interpreter. It reads and proce
18 displays the results of the trace analysis imp
19 Perl script, if any.
20
21 STARTER SCRIPTS
22 ---------------
23
24 You can avoid reading the rest of this documen
25 -g perl' in the same directory as an existing
26 That will generate a starter script containing
27 the event types in the trace file; it simply p
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 e
32 do basic things like aggregate event data, pri
33 the check-perf-script.pl script, while not int
34 attempts to exercise all of the main scripting
35
36 EVENT HANDLERS
37 --------------
38
39 When perf script is invoked using a trace scri
40 'handler function' is called for each event in
41 no handler function defined for a given event
42 ignored (or passed to a 'trace_unhandled' func
43 next event is processed.
44
45 Most of the event's field values are passed as
46 handler function; some of the less common ones
47 available as calls back into the perf executab
48
49 As an example, the following perf record comma
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 sh
55 the above option: -a to enable system-wide col
56
57 The format file for the sched_wakeup event def
58 (see /sys/kernel/tracing/events/sched/sched_wa
59
60 ----
61 format:
62 field:unsigned short common_type;
63 field:unsigned char common_flags;
64 field:unsigned char common_preempt_cou
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 d
75
76 ----
77 sub sched::sched_wakeup
78 {
79 my ($event_name, $context, $common_cpu, $co
80 $common_nsecs, $common_pid, $common_com
81 $comm, $pid, $prio, $success, $target_c
82 }
83 ----
84
85 The handler function takes the form subsystem:
86
87 The $common_* arguments in the handler's argum
88 arguments passed to all event handlers; some o
89 to the common_* fields in the format file, but
90 and some of the common_* fields aren't common
91 to every event as arguments but are available
92
93 Here's a brief description of each of the inva
94
95 $event_name the name of the ev
96 $context an opaque 'cookie'
97 $common_cpu the cpu the event
98 $common_secs the secs portion o
99 $common_nsecs the nsecs portion
100 $common_pid the pid of the cur
101 $common_comm the name of the cu
102
103 All of the remaining fields in the event's for
104 counterparts as handler function arguments of
105 seen in the example above.
106
107 The above provides the basics needed to direct
108 every event in a trace, which covers 90% of wh
109 write a useful trace script. The sections bel
110
111 SCRIPT LAYOUT
112 -------------
113
114 Every perf script Perl script should start by
115 search path and 'use'ing a few support modules
116 descriptions below):
117
118 ----
119 use lib "$ENV{'PERF_EXEC_PATH'}/scripts/perl/
120 use lib "./Perf-Trace-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 fun
127 functions in any order.
128
129 Aside from the event handler functions discuss
130 can implement a set of optional functions:
131
132 *trace_begin*, if defined, is called before an
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 e
142 processed and gives scripts a chance to do en
143 as display results:
144
145 ----
146 sub trace_end
147 {
148 }
149 ----
150
151 *trace_unhandled*, if defined, is called after
152 doesn't have a handler explicitly defined for
153 of common arguments are passed into it:
154
155 ----
156 sub trace_unhandled
157 {
158 my ($event_name, $context, $common_cpu, $c
159 $common_nsecs, $common_pid, $common_co
160 }
161 ----
162
163 The remaining sections provide descriptions of
164 built-in perf script Perl modules and their as
165
166 AVAILABLE MODULES AND FUNCTIONS
167 -------------------------------
168
169 The following sections describe the functions
170 via the various Perf::Trace::* Perl modules.
171 variables from the given module, add the corre
172 Perf::Trace::XXX' line to your perf script scr
173
174 Perf::Trace::Core Module
175 ~~~~~~~~~~~~~~~~~~~~~~~~
176
177 These functions provide some essential functio
178
179 The *flag_str* and *symbol_str* functions prov
180 strings for flag and symbolic fields. These c
181 and values parsed from the 'print fmt' fields
182 files:
183
184 flag_str($event_name, $field_name, $field_va
185 symbol_str($event_name, $field_name, $field_
186
187 Perf::Trace::Context Module
188 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
189
190 Some of the 'common' fields in the event forma
191 common, but need to be made accessible to user
192
193 Perf::Trace::Context defines a set of function
194 access this data in the context of the current
195 functions expects a $context variable, which i
196 $context variable passed into every event hand
197 argument.
198
199 common_pc($context) - returns common_preempt
200 common_flags($context) - returns common_flags
201 common_lock_depth($context) - returns common_
202
203 Perf::Trace::Util Module
204 ~~~~~~~~~~~~~~~~~~~~~~~~
205
206 Various utility functions for use with perf sc
207
208 nsecs($secs, $nsecs) - returns total nsecs g
209 nsecs_secs($nsecs) - returns whole secs port
210 nsecs_nsecs($nsecs) - returns nsecs remainde
211 nsecs_str($nsecs) - returns printable string
212 avg($total, $n) - returns average given a su
213
214 SEE ALSO
215 --------
216 linkperf:perf-script[1]
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.