diff options
Diffstat (limited to 'tools/perf/Documentation/perf-inject.txt')
| -rw-r--r-- | tools/perf/Documentation/perf-inject.txt | 119 |
1 files changed, 119 insertions, 0 deletions
diff --git a/tools/perf/Documentation/perf-inject.txt b/tools/perf/Documentation/perf-inject.txt new file mode 100644 index 0000000000..c972032f4c --- /dev/null +++ b/tools/perf/Documentation/perf-inject.txt @@ -0,0 +1,119 @@ +perf-inject(1) +============== + +NAME +---- +perf-inject - Filter to augment the events stream with additional information + +SYNOPSIS +-------- +[verse] +'perf inject <options>' + +DESCRIPTION +----------- +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. + +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. + +OPTIONS +------- +-b:: +--build-ids:: + Inject build-ids of DSOs hit by samples into the output stream. + This means it needs to process all SAMPLE records to find the DSOs. + +--buildid-all:: + Inject build-ids of all DSOs into the output stream regardless of hits + and skip SAMPLE processing. + +--known-build-ids=:: + Override build-ids to inject using these comma-separated pairs of + build-id and path. Understands file://filename to read these pairs + from a file, which can be generated with perf buildid-list. + +-v:: +--verbose:: + Be more verbose. +-i:: +--input=:: + Input file name. (default: stdin) +-o:: +--output=:: + Output file name. (default: stdout) +-s:: +--sched-stat:: + 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. + +-k:: +--vmlinux=<file>:: + vmlinux pathname + +--ignore-vmlinux:: + Ignore vmlinux files. + +--kallsyms=<file>:: + kallsyms pathname + +--itrace:: + Decode Instruction Tracing data, replacing it with synthesized events. + Options are: + +include::itrace.txt[] + +--strip:: + Use with --itrace to strip out non-synthesized events. + +-j:: +--jit:: + 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. + +-f:: +--force:: + Don't complain, do it. + +--vm-time-correlation[=OPTIONS]:: + Some architectures may capture AUX area data which contains timestamps + affected by virtualization. This option will update those timestamps + in place, to correlate with host timestamps. The in-place update means + that an output file is not specified, and instead the input file is + modified. The options are architecture specific, except that they may + start with "dry-run" which will cause the file to be processed but + without updating it. Currently this option is supported only by + Intel PT, refer linkperf:perf-intel-pt[1] + +--guest-data=<path>,<pid>[,<time offset>[,<time scale>]]:: + Insert events from a perf.data file recorded in a virtual machine at + the same time as the input perf.data file was recorded on the host. + The Process ID (PID) of the QEMU hypervisor process must be provided, + and the time offset and time scale (multiplier) will likely be needed + to convert guest time stamps into host time stamps. For example, for + x86 the TSC Offset and Multiplier could be provided for a virtual machine + using Linux command line option no-kvmclock. + Currently only mmap, mmap2, comm, task, context_switch, ksymbol, + and text_poke events are inserted, as well as build ID information. + The QEMU option -name debug-threads=on is needed so that thread names + can be used to determine which thread is running which VCPU. Note + libvirt seems to use this by default. + When using perf record in the guest, option --sample-identifier + should be used, and also --buildid-all and --switch-events may be + useful. + +:GMEXAMPLECMD: inject +:GMEXAMPLESUBCMD: +include::guestmount.txt[] + +SEE ALSO +-------- +linkperf:perf-record[1], linkperf:perf-report[1], linkperf:perf-archive[1], +linkperf:perf-intel-pt[1] |