0001 perf-inject(1)
0002 ==============
0003
0004 NAME
0005 ----
0006 perf-inject - Filter to augment the events stream with additional information
0007
0008 SYNOPSIS
0009 --------
0010 [verse]
0011 'perf inject <options>'
0012
0013 DESCRIPTION
0014 -----------
0015 perf-inject reads a perf-record event stream and repipes it to stdout. At any
0016 point the processing code can inject other events into the event stream - in
0017 this case build-ids (-b option) are read and injected as needed into the event
0018 stream.
0019
0020 Build-ids are just the first user of perf-inject - potentially anything that
0021 needs userspace processing to augment the events stream with additional
0022 information could make use of this facility.
0023
0024 OPTIONS
0025 -------
0026 -b::
0027 --build-ids::
0028 Inject build-ids into the output stream
0029
0030 --buildid-all:
0031 Inject build-ids of all DSOs into the output stream
0032
0033 -v::
0034 --verbose::
0035 Be more verbose.
0036 -i::
0037 --input=::
0038 Input file name. (default: stdin)
0039 -o::
0040 --output=::
0041 Output file name. (default: stdout)
0042 -s::
0043 --sched-stat::
0044 Merge sched_stat and sched_switch for getting events where and how long
0045 tasks slept. sched_switch contains a callchain where a task slept and
0046 sched_stat contains a timeslice how long a task slept.
0047
0048 -k::
0049 --vmlinux=<file>::
0050 vmlinux pathname
0051
0052 --ignore-vmlinux::
0053 Ignore vmlinux files.
0054
0055 --kallsyms=<file>::
0056 kallsyms pathname
0057
0058 --itrace::
0059 Decode Instruction Tracing data, replacing it with synthesized events.
0060 Options are:
0061
0062 include::itrace.txt[]
0063
0064 --strip::
0065 Use with --itrace to strip out non-synthesized events.
0066
0067 -j::
0068 --jit::
0069 Process jitdump files by injecting the mmap records corresponding to jitted
0070 functions. This option also generates the ELF images for each jitted function
0071 found in the jitdumps files captured in the input perf.data file. Use this option
0072 if you are monitoring environment using JIT runtimes, such as Java, DART or V8.
0073
0074 -f::
0075 --force::
0076 Don't complain, do it.
0077
0078 --vm-time-correlation[=OPTIONS]::
0079 Some architectures may capture AUX area data which contains timestamps
0080 affected by virtualization. This option will update those timestamps
0081 in place, to correlate with host timestamps. The in-place update means
0082 that an output file is not specified, and instead the input file is
0083 modified. The options are architecture specific, except that they may
0084 start with "dry-run" which will cause the file to be processed but
0085 without updating it. Currently this option is supported only by
0086 Intel PT, refer linkperf:perf-intel-pt[1]
0087
0088 --guest-data=<path>,<pid>[,<time offset>[,<time scale>]]::
0089 Insert events from a perf.data file recorded in a virtual machine at
0090 the same time as the input perf.data file was recorded on the host.
0091 The Process ID (PID) of the QEMU hypervisor process must be provided,
0092 and the time offset and time scale (multiplier) will likely be needed
0093 to convert guest time stamps into host time stamps. For example, for
0094 x86 the TSC Offset and Multiplier could be provided for a virtual machine
0095 using Linux command line option no-kvmclock.
0096 Currently only mmap, mmap2, comm, task, context_switch, ksymbol,
0097 and text_poke events are inserted, as well as build ID information.
0098 The QEMU option -name debug-threads=on is needed so that thread names
0099 can be used to determine which thread is running which VCPU. Note
0100 libvirt seems to use this by default.
0101 When using perf record in the guest, option --sample-identifier
0102 should be used, and also --buildid-all and --switch-events may be
0103 useful.
0104
0105 :GMEXAMPLECMD: inject
0106 :GMEXAMPLESUBCMD:
0107 include::guestmount.txt[]
0108
0109 SEE ALSO
0110 --------
0111 linkperf:perf-record[1], linkperf:perf-report[1], linkperf:perf-archive[1],
0112 linkperf:perf-intel-pt[1]
