'\" t
.\"     Title: perf-script-perl
.\"    Author: [FIXME: author] [see http://docbook.sf.net/el/author]
.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
.\"      Date: 2018-01-14
.\"    Manual: perf Manual
.\"    Source: perf
.\"  Language: English
.\"
.TH "PERF_4.14\-SCRIPT\-PERL" "1" "2018\-01\-14" "perf" "perf Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
perf-script-perl \- Process trace data with a Perl script
.SH "SYNOPSIS"
.sp
.nf
\fIperf script\fR [\-s [Perl]:script[\&.pl] ]
.fi
.SH "DESCRIPTION"
.sp
This perf script option is used to process perf script data using perf\(cqs built\-in Perl interpreter\&. It reads and processes the input file and displays the results of the trace analysis implemented in the given Perl script, if any\&.
.SH "STARTER SCRIPTS"
.sp
You can avoid reading the rest of this document by running \fIperf script \-g perl\fR in the same directory as an existing perf\&.data trace file\&. That will generate a starter script containing a handler for each of the event types in the trace file; it simply prints every available field for each event in the trace file\&.
.sp
You can also look at the existing scripts in ~/libexec/perf\-core/scripts/perl for typical examples showing how to do basic things like aggregate event data, print results, etc\&. Also, the check\-perf\-script\&.pl script, while not interesting for its results, attempts to exercise all of the main scripting features\&.
.SH "EVENT HANDLERS"
.sp
When perf script is invoked using a trace script, a user\-defined \fIhandler function\fR is called for each event in the trace\&. If there\(cqs no handler function defined for a given event type, the event is ignored (or passed to a \fItrace_unhandled\fR function, see below) and the next event is processed\&.
.sp
Most of the event\(cqs field values are passed as arguments to the handler function; some of the less common ones aren\(cqt \- those are available as calls back into the perf executable (see below)\&.
.sp
As an example, the following perf record command can be used to record all sched_wakeup events in the system:
.sp
.if n \{\
.RS 4
.\}
.nf
# perf record \-a \-e sched:sched_wakeup
.fi
.if n \{\
.RE
.\}
.sp
Traces meant to be processed using a script should be recorded with the above option: \-a to enable system\-wide collection\&.
.sp
The format file for the sched_wakep event defines the following fields (see /sys/kernel/debug/tracing/events/sched/sched_wakeup/format):
.sp
.if n \{\
.RS 4
.\}
.nf

\&.ft C
 format:
        field:unsigned short common_type;
        field:unsigned char common_flags;
        field:unsigned char common_preempt_count;
        field:int common_pid;

        field:char comm[TASK_COMM_LEN];
        field:pid_t pid;
        field:int prio;
        field:int success;
        field:int target_cpu;
\&.ft

.fi
.if n \{\
.RE
.\}
.sp
The handler function for this event would be defined as:
.sp
.if n \{\
.RS 4
.\}
.nf

\&.ft C
sub sched::sched_wakeup
{
   my ($event_name, $context, $common_cpu, $common_secs,
       $common_nsecs, $common_pid, $common_comm,
       $comm, $pid, $prio, $success, $target_cpu) = @_;
}
\&.ft

.fi
.if n \{\
.RE
.\}
.sp
The handler function takes the form subsystem::event_name\&.
.sp
The $common_* arguments in the handler\(cqs argument list are the set of arguments passed to all event handlers; some of the fields correspond to the common_* fields in the format file, but some are synthesized, and some of the common_* fields aren\(cqt common enough to to be passed to every event as arguments but are available as library functions\&.
.sp
Here\(cqs a brief description of each of the invariant event args:
.sp
.if n \{\
.RS 4
.\}
.nf
$event_name                the name of the event as text
$context                   an opaque \*(Aqcookie\*(Aq used in calls back into perf
$common_cpu                the cpu the event occurred on
$common_secs               the secs portion of the event timestamp
$common_nsecs              the nsecs portion of the event timestamp
$common_pid                the pid of the current task
$common_comm               the name of the current process
.fi
.if n \{\
.RE
.\}
.sp
All of the remaining fields in the event\(cqs format file have counterparts as handler function arguments of the same name, as can be seen in the example above\&.
.sp
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\&.
.SH "SCRIPT LAYOUT"
.sp
Every perf script Perl script should start by setting up a Perl module search path and \*(Aquse\(cqing a few support modules (see module descriptions below):
.sp
.if n \{\
.RS 4
.\}
.nf

\&.ft C
 use lib "$ENV{\*(AqPERF_EXEC_PATH\*(Aq}/scripts/perl/Perf\-Trace\-Util/lib";
 use lib "\&./Perf\-Trace\-Util/lib";
 use Perf::Trace::Core;
 use Perf::Trace::Context;
 use Perf::Trace::Util;
\&.ft

.fi
.if n \{\
.RE
.\}
.sp
The rest of the script can contain handler functions and support functions in any order\&.
.sp
Aside from the event handler functions discussed above, every script can implement a set of optional functions:
.sp
\fBtrace_begin\fR, if defined, is called before any event is processed and gives scripts a chance to do setup tasks:
.sp
.if n \{\
.RS 4
.\}
.nf

\&.ft C
 sub trace_begin
 {
 }
\&.ft

.fi
.if n \{\
.RE
.\}
.sp
\fBtrace_end\fR, 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:
.sp
.if n \{\
.RS 4
.\}
.nf

\&.ft C
sub trace_end
{
}
\&.ft

.fi
.if n \{\
.RE
.\}
.sp
\fBtrace_unhandled\fR, if defined, is called after for any event that doesn\(cqt have a handler explicitly defined for it\&. The standard set of common arguments are passed into it:
.sp
.if n \{\
.RS 4
.\}
.nf

\&.ft C
sub trace_unhandled
{
    my ($event_name, $context, $common_cpu, $common_secs,
        $common_nsecs, $common_pid, $common_comm) = @_;
}
\&.ft

.fi
.if n \{\
.RE
.\}
.sp
The remaining sections provide descriptions of each of the available built\-in perf script Perl modules and their associated functions\&.
.SH "AVAILABLE MODULES AND FUNCTIONS"
.sp
The following sections describe the functions and variables available via the various Perf::Trace::* Perl modules\&. To use the functions and variables from the given module, add the corresponding \fIuse Perf::Trace::XXX\fR line to your perf script script\&.
.SS "Perf::Trace::Core Module"
.sp
These functions provide some essential functions to user scripts\&.
.sp
The \fBflag_str\fR and \fBsymbol_str\fR functions provide human\-readable strings for flag and symbolic fields\&. These correspond to the strings and values parsed from the \fIprint fmt\fR fields of the event format files:
.sp
.if n \{\
.RS 4
.\}
.nf
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
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
.fi
.if n \{\
.RE
.\}
.SS "Perf::Trace::Context Module"
.sp
Some of the \fIcommon\fR fields in the event format file aren\(cqt all that common, but need to be made accessible to user scripts nonetheless\&.
.sp
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\&.
.sp
.if n \{\
.RS 4
.\}
.nf
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
.fi
.if n \{\
.RE
.\}
.SS "Perf::Trace::Util Module"
.sp
Various utility functions for use with perf script:
.sp
.if n \{\
.RS 4
.\}
.nf
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
.fi
.if n \{\
.RE
.\}
.SH "SEE ALSO"
.sp
\fBperf_4.14-script\fR(1)