tools/perf/Documentation/perf-script-perl.txt

Source file repositories/reference/linux-study-clean/tools/perf/Documentation/perf-script-perl.txt

File Facts

System
Linux kernel
Corpus path
tools/perf/Documentation/perf-script-perl.txt
Extension
.txt
Size
7368 bytes
Lines
217
Domain
Support Tooling And Documentation
Bucket
tools
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

perf-script-perl(1)
===================

NAME
----
perf-script-perl - Process trace data with a Perl script

SYNOPSIS
--------
[verse]
'perf script' [-s [Perl]:script[.pl] ]

DESCRIPTION
-----------

This perf script option is used to process perf script data using perf's
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.

STARTER SCRIPTS
---------------

You can avoid reading the rest of this document by running 'perf script
-g perl' 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.

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.

EVENT HANDLERS
--------------

When perf script is invoked using a trace script, a user-defined
'handler function' is called for each event in the trace.  If there's
no handler function defined for a given event type, the event is
ignored (or passed to a 'trace_unhandled' function, see below) and the
next event is processed.

Most of the event's field values are passed as arguments to the
handler function; some of the less common ones aren't - those are
available as calls back into the perf executable (see below).

As an example, the following perf record command can be used to record
all sched_wakeup events in the system:

 # perf record -a -e sched:sched_wakeup

Traces meant to be processed using a script should be recorded with
the above option: -a to enable system-wide collection.

The format file for the sched_wakeup event defines the following fields
(see /sys/kernel/tracing/events/sched/sched_wakeup/format):

----
 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;

Annotation

Implementation Notes