'\" t
.\"     Title: perf-inject
.\"    Author: [FIXME: author] [see http://docbook.sf.net/el/author]
.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
.\"      Date: 2018-01-15
.\"    Manual: perf Manual
.\"    Source: perf
.\"  Language: English
.\"
.TH "PERF_4.15\-INJECT" "1" "2018\-01\-15" "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-inject \- Filter to augment the events stream with additional information
.SH "SYNOPSIS"
.sp
.nf
\fIperf inject <options>\fR
.fi
.SH "DESCRIPTION"
.sp
perf\-inject reads a perf\-record event stream and repipes it to stdout\&. At any point the processing code can inject other events into the event stream \- in this case build\-ids (\-b option) are read and injected as needed into the event stream\&.
.sp
Build\-ids are just the first user of perf\-inject \- potentially anything that needs userspace processing to augment the events stream with additional information could make use of this facility\&.
.SH "OPTIONS"
.PP
\-b, \-\-build\-ids=
.RS 4
Inject build\-ids into the output stream
.RE
.PP
\-v, \-\-verbose
.RS 4
Be more verbose\&.
.RE
.PP
\-i, \-\-input=
.RS 4
Input file name\&. (default: stdin)
.RE
.PP
\-o, \-\-output=
.RS 4
Output file name\&. (default: stdout)
.RE
.PP
\-s, \-\-sched\-stat
.RS 4
Merge sched_stat and sched_switch for getting events where and how long tasks slept\&. sched_switch contains a callchain where a task slept and sched_stat contains a timeslice how long a task slept\&.
.RE
.PP
\-\-kallsyms=<file>
.RS 4
kallsyms pathname
.RE
.PP
\-\-itrace
.RS 4
Decode Instruction Tracing data, replacing it with synthesized events\&. Options are:
.sp
.if n \{\
.RS 4
.\}
.nf
i       synthesize instructions events
b       synthesize branches events
c       synthesize branches events (calls only)
r       synthesize branches events (returns only)
x       synthesize transactions events
w       synthesize ptwrite events
p       synthesize power events
e       synthesize error events
d       create a debug log
g       synthesize a call chain (use with i or x)
l       synthesize last branch entries (use with i or x)
s       skip initial number of events
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
The default is all events i\&.e\&. the same as \-\-itrace=ibxwpe
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
In addition, the period (default 100000) for instructions events
can be specified in units of:
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
i       instructions
t       ticks
ms      milliseconds
us      microseconds
ns      nanoseconds (default)
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
Also the call chain size (default 16, max\&. 1024) for instructions or
transactions events can be specified\&.
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
Also the number of last branch entries (default 64, max\&. 1024) for
instructions or transactions events can be specified\&.
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
It is also possible to skip events generated (instructions, branches, transactions,
ptwrite, power) at the beginning\&. This is useful to ignore initialization code\&.
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
\-\-itrace=i0nss1000000
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
skips the first million instructions\&.
.fi
.if n \{\
.RE
.\}
.RE
.PP
\-\-strip
.RS 4
Use with \-\-itrace to strip out non\-synthesized events\&.
.RE
.PP
\-j, \-\-jit
.RS 4
Process jitdump files by injecting the mmap records corresponding to jitted functions\&. This option also generates the ELF images for each jitted function found in the jitdumps files captured in the input perf\&.data file\&. Use this option if you are monitoring environment using JIT runtimes, such as Java, DART or V8\&.
.RE
.SH "SEE ALSO"
.sp
\fBperf_4.15-record\fR(1), \fBperf_4.15-report\fR(1), \fBperf_4.15-archive\fR(1)