linux-stable/tools/perf/Documentation
Andi Kleen 36ce565114 perf script: Allow adding and removing fields
With 'perf script' it is common that we just want to add or remove a field.

Currently this requires figuring out the long list of default fields and
specifying them first, and then adding/removing the new field.

This patch adds a new + - syntax to merely add or remove fields,
that allows more succint and clearer command lines

For example to remove the comm field from PMU samples:

Previously

  $ perf script -F tid,cpu,time,event,sym,ip,dso,period | head -1
  swapper  0 [000] 504345.383126:          1 cycles:  ffffffff90060c66 native_write_msr ([kernel.kallsyms])

with the new syntax

  perf script -F -comm | head -1
  0 [000] 504345.383126:          1 cycles:  ffffffff90060c66 native_write_msr ([kernel.kallsyms])

The new syntax cannot be mixed with normal overriding.

v2: Fix example in description. Use tid vs pid. No functional changes.
v3: Don't skip initialization when user specified explicit type.
v4: Rebase. Remove empty line.

Committer testing:

  # perf record -a usleep 1
  [ perf record: Woken up 1 times to write data ]
  [ perf record: Captured and wrote 1.748 MB perf.data (14 samples) ]

Without a explicit field list specified via -F, defaults to:

  # perf script | head -2
      perf 6338 [000] 18467.058607: 1 cycles: ffffffff89060c36 native_write_msr (/lib/modules/4.11.0-rc8+/build/vmlinux)
   swapper    0 [001] 18467.058617: 1 cycles: ffffffff89060c36 native_write_msr (/lib/modules/4.11.0-rc8+/build/vmlinux)
  #

Which is equivalent to:

  # perf script -F comm,tid,cpu,time,period,event,ip,sym,dso | head -2
      perf 6338 [000] 18467.058607: 1 cycles: ffffffff89060c36 native_write_msr (/lib/modules/4.11.0-rc8+/build/vmlinux)
   swapper    0 [001] 18467.058617: 1 cycles: ffffffff89060c36 native_write_msr (/lib/modules/4.11.0-rc8+/build/vmlinux)
  #

So if we want to remove the comm, as in your original example, we would have to
figure out the default field list and remove ' comm' from it:

  # perf script -F tid,cpu,time,period,event,ip,sym,dso | head -2
   6338 [000] 18467.058607: 1 cycles: ffffffff89060c36 native_write_msr (/lib/modules/4.11.0-rc8+/build/vmlinux)
      0 [001] 18467.058617: 1 cycles: ffffffff89060c36 native_write_msr (/lib/modules/4.11.0-rc8+/build/vmlinux)
  #

With your patch this becomes simpler, one can remove fields by prefixing them
with '-':

  # perf script -F -comm | head -2
  6338 [000] 18467.058607: 1 cycles: ffffffff89060c36 native_write_msr (/lib/modules/4.11.0-rc8+/build/vmlinux)
     0 [001] 18467.058617: 1 cycles: ffffffff89060c36 native_write_msr (/lib/modules/4.11.0-rc8+/build/vmlinux)
  #

Signed-off-by: Andi Kleen <ak@linux.intel.com>
Acked-by: Jiri Olsa <jolsa@kernel.org>
Tested-by: Arnaldo Carvalho de Melo <acme@redhat.com>
Tested-by: Milian Wolff <milian.wolff@kdab.com>
Link: http://lkml.kernel.org/r/20170602154810.15875-1-andi@firstfloor.org
Signed-off-by: Arnaldo Carvalho de Melo <acme@redhat.com>
2017-06-19 15:14:58 -03:00
..
android.txt perf tools: Update android build documentation 2016-07-04 20:27:27 -03:00
asciidoc.conf
Build.txt perf build: Add build documentation 2015-02-12 17:53:00 -03:00
callchain-overhead-calculation.txt perf tools: Document --children option in more detail 2015-04-29 10:38:06 -03:00
examples.txt perf record: Remove -f/--force option 2013-07-08 17:37:25 -03:00
intel-bts.txt perf tools: Add Intel BTS support 2015-08-21 11:34:10 -03:00
intel-pt.txt perf intel-pt: Update documentation about context switch events 2016-11-11 13:18:52 -03:00
itrace.txt perf tools: Add support for skipping itrace instructions 2016-03-30 11:14:09 -03:00
jit-interface.txt
jitdump-specification.txt perf jit: Add jitdump format specification document 2016-10-24 11:07:41 -03:00
Makefile tools: Move utilities.mak from perf to tools/scripts/ 2016-03-18 13:57:20 -03:00
manpage-1.72.xsl
manpage-base.xsl
manpage-bold-literal.xsl
manpage-normal.xsl
manpage-suppress-sp.xsl
perf-annotate.txt perf annotate: Add -q/--quiet option 2017-02-20 11:47:18 -03:00
perf-archive.txt perf archive: Remove duplicated 'runs' in man page 2013-12-09 15:21:45 -03:00
perf-bench.txt perf bench mem: Rename 'routine' to 'function' 2015-10-19 16:10:25 -03:00
perf-buildid-cache.txt perf buildid-cache: Scan and import user SDT events to probe cache 2016-07-04 19:39:00 -03:00
perf-buildid-list.txt
perf-c2c.txt perf tools: Fix spelling mistakes 2017-05-04 09:59:53 -03:00
perf-config.txt perf diff: Add diff.compute config option 2017-02-13 14:29:37 -03:00
perf-data.txt perf data ctf: Add '--all' option for 'perf data convert' 2016-06-28 10:54:57 -03:00
perf-diff.txt perf diff: Add -q/--quiet option 2017-02-20 11:47:08 -03:00
perf-evlist.txt perf evlist: Add --trace-fields option to show trace fields 2016-01-08 14:23:02 -03:00
perf-ftrace.txt perf ftrace: Add support for -a and -C option 2017-03-03 19:07:17 -03:00
perf-help.txt
perf-inject.txt perf inject: Add jitdump mmap injection support 2016-02-05 09:46:45 -03:00
perf-kallsyms.txt perf kallsyms: Introduce tool to look for extended symbol information on the running kernel 2017-01-11 16:48:01 -03:00
perf-kmem.txt perf kmem: Add option to specify time window of interest 2016-12-01 13:03:02 -03:00
perf-kvm.txt perf tools: Configurable per thread proc map processing time out 2015-06-19 18:27:13 -03:00
perf-list.txt perf list sdt: Show option in man page 2017-03-27 11:58:09 -03:00
perf-lock.txt perf lock: Account for lock average wait time 2013-10-09 11:24:01 -03:00
perf-mem.txt perf mem: Add --ldlat option 2016-06-15 10:35:27 -03:00
perf-probe.txt perf probe: Fix examples section of documentation 2017-06-07 20:23:11 -03:00
perf-record.txt perf tools: Fix spelling mistakes 2017-05-04 09:59:53 -03:00
perf-report.txt perf tools: Fix spelling mistakes 2017-05-04 09:59:53 -03:00
perf-sched.txt perf sched timehist: Add --next option 2017-03-14 15:17:38 -03:00
perf-script-perl.txt perf script: Fix documentation errors 2017-06-07 20:27:20 -03:00
perf-script-python.txt perf script python: Remove dups in documentation examples 2017-06-07 20:36:12 -03:00
perf-script.txt perf script: Allow adding and removing fields 2017-06-19 15:14:58 -03:00
perf-stat.txt perf stat: Collapse identically named events 2017-03-21 16:04:11 -03:00
perf-test.txt perf test: Add -F/--dont-fork option 2016-06-30 18:27:45 -03:00
perf-timechart.txt perf timechart: Add more options to IO mode 2014-07-10 00:22:54 +02:00
perf-top.txt perf tools: Explicitly document that --children is enabled by default 2016-12-07 12:00:35 -03:00
perf-trace.txt perf trace: Add usage of --no-syscalls in man page 2017-04-13 10:54:04 -03:00
perf.data-file-format.txt perf tools: Fix spelling mistakes 2017-05-04 09:59:53 -03:00
perf.txt perf tools: Handle -h and -v options 2015-10-05 16:36:18 -03:00
perfconfig.example perf config: Show default report configuration in example and docs 2016-09-01 09:44:13 -03:00
tips.txt perf tools: Fix spelling mistakes 2017-05-04 09:59:53 -03:00