linux/tools/perf/Documentation
Claire Jensen df936cadfb perf stat: Add JSON output option
CSV output is tricky to format and column layout changes are susceptible
to breaking parsers. New JSON-formatted output has variable names to
identify fields that are consistent and informative, making the output
parseable.

CSV output example:

  1.20,msec,task-clock:u,1204272,100.00,0.697,CPUs utilized
  0,,context-switches:u,1204272,100.00,0.000,/sec
  0,,cpu-migrations:u,1204272,100.00,0.000,/sec
  70,,page-faults:u,1204272,100.00,58.126,K/sec

JSON output example:

  {"counter-value" : "3805.723968", "unit" : "msec", "event" :
  "cpu-clock", "event-runtime" : 3805731510100.00, "pcnt-running"
  : 100.00, "metric-value" : 4.007571, "metric-unit" : "CPUs utilized"}
  {"counter-value" : "6166.000000", "unit" : "", "event" :
  "context-switches", "event-runtime" : 3805723045100.00, "pcnt-running"
  : 100.00, "metric-value" : 1.620191, "metric-unit" : "K/sec"}
  {"counter-value" : "466.000000", "unit" : "", "event" :
  "cpu-migrations", "event-runtime" : 3805727613100.00, "pcnt-running"
  : 100.00, "metric-value" : 122.447136, "metric-unit" : "/sec"}
  {"counter-value" : "208.000000", "unit" : "", "event" :
  "page-faults", "event-runtime" : 3805726799100.00, "pcnt-running"
  : 100.00, "metric-value" : 54.654516, "metric-unit" : "/sec"}

Also added documentation for JSON option.

There is some tidy up of CSV code including a potential memory over run
in the os.nfields set up. To facilitate this an AGGR_MAX value is added.

Committer notes:

Fixed up using PRIu64 to format u64 values, not %lu.

Committer testing:

  ⬢[acme@toolbox perf]$ perf stat -j sleep 1
  {"counter-value" : "0.731750", "unit" : "msec", "event" : "task-clock:u", "event-runtime" : 731750, "pcnt-running" : 100.00, "metric-value" : 0.000731, "metric-unit" : "CPUs utilized"}
  {"counter-value" : "0.000000", "unit" : "", "event" : "context-switches:u", "event-runtime" : 731750, "pcnt-running" : 100.00, "metric-value" : 0.000000, "metric-unit" : "/sec"}
  {"counter-value" : "0.000000", "unit" : "", "event" : "cpu-migrations:u", "event-runtime" : 731750, "pcnt-running" : 100.00, "metric-value" : 0.000000, "metric-unit" : "/sec"}
  {"counter-value" : "75.000000", "unit" : "", "event" : "page-faults:u", "event-runtime" : 731750, "pcnt-running" : 100.00, "metric-value" : 102.494021, "metric-unit" : "K/sec"}
  {"counter-value" : "578765.000000", "unit" : "", "event" : "cycles:u", "event-runtime" : 379366, "pcnt-running" : 49.00, "metric-value" : 0.790933, "metric-unit" : "GHz"}
  {"counter-value" : "1298.000000", "unit" : "", "event" : "stalled-cycles-frontend:u", "event-runtime" : 768020, "pcnt-running" : 100.00, "metric-value" : 0.224271, "metric-unit" : "frontend cycles idle"}
  {"counter-value" : "21984.000000", "unit" : "", "event" : "stalled-cycles-backend:u", "event-runtime" : 768020, "pcnt-running" : 100.00, "metric-value" : 3.798433, "metric-unit" : "backend cycles idle"}
  {"counter-value" : "468197.000000", "unit" : "", "event" : "instructions:u", "event-runtime" : 768020, "pcnt-running" : 100.00, "metric-value" : 0.808959, "metric-unit" : "insn per cycle"}
  {"metric-value" : 0.046955, "metric-unit" : "stalled cycles per insn"}
  {"counter-value" : "103335.000000", "unit" : "", "event" : "branches:u", "event-runtime" : 768020, "pcnt-running" : 100.00, "metric-value" : 141.216262, "metric-unit" : "M/sec"}
  {"counter-value" : "2381.000000", "unit" : "", "event" : "branch-misses:u", "event-runtime" : 388654, "pcnt-running" : 50.00, "metric-value" : 2.304156, "metric-unit" : "of all branches"}
  ⬢[acme@toolbox perf]$

Signed-off-by: Claire Jensen <cjense@google.com>
Acked-by: Namhyung Kim <namhyung@kernel.org>
Tested-by: Arnaldo Carvalho de Melo <acme@redhat.com>
Cc: Alexander Shishkin <alexander.shishkin@linux.intel.com>
Cc: Alyssa Ross <hi@alyssa.is>
Cc: Claire Jensen <clairej735@gmail.com>
Cc: Florian Fischer <florian.fischer@muhq.space>
Cc: Ingo Molnar <mingo@redhat.com>
Cc: James Clark <james.clark@arm.com>
Cc: Jiri Olsa <jolsa@kernel.org>
Cc: Kan Liang <kan.liang@linux.intel.com>
Cc: Like Xu <likexu@tencent.com>
Cc: Mark Rutland <mark.rutland@arm.com>
Cc: Peter Zijlstra <peterz@infradead.org>
Cc: Sandipan Das <sandipan.das@amd.com>
Cc: Stephane Eranian <eranian@google.com>
Cc: Xing Zhengjun <zhengjun.xing@linux.intel.com>
Link: https://lore.kernel.org/r/20220805200105.2020995-2-irogers@google.com
Signed-off-by: Ian Rogers <irogers@google.com>
Signed-off-by: Arnaldo Carvalho de Melo <acme@redhat.com>
2022-08-10 10:43:29 -03:00
..
android.txt
asciidoc.conf perf docs: Allow man page date to be specified 2019-09-27 09:26:14 -03:00
asciidoctor-extensions.rb perf Documentation: Support for asciidoctor 2018-04-26 13:47:10 -03:00
build-docdep.perl perf doc: Fix doc.dep 2021-08-02 09:56:17 -03:00
build-xed.txt perf script: Add --insn-trace for instruction decoding 2018-10-24 15:29:50 -03:00
Build.txt perf tools: Add doc about how to build perf with Asan and UBSan 2019-03-19 16:52:04 -03:00
callchain-overhead-calculation.txt
cat-texi.perl perf doc: Fix perfman.info build 2021-08-02 09:56:17 -03:00
db-export.txt perf db-export: Add brief documentation 2019-06-05 09:47:57 -03:00
examples.txt perf tools: Replace lkml.org links with lore 2021-02-11 12:54:27 -03:00
intel-bts.txt
intel-hybrid.txt perf docs: Fix accidental em-dashes 2021-08-10 11:05:21 -03:00
intel-pt.txt perf intel-pt: Update intel-pt.txt file with new location of the documentation 2020-03-11 11:00:33 -03:00
itrace.txt perf auxtrace: Add itrace option "I" 2022-02-15 17:10:30 -03:00
jit-interface.txt
jitdump-specification.txt perf doc: Fix typos all over the place 2021-09-27 09:32:28 -03:00
Makefile perf doc: Reorganize ARTICLES variables. 2021-08-02 09:56:18 -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 --percent-limit option 2022-05-10 14:37:55 -03:00
perf-archive.txt
perf-arm-spe.txt perf docs: Add man page entry for Arm SPE 2022-04-14 08:54:03 -03:00
perf-bench.txt perf bench: Add basic syscall benchmark 2020-07-28 08:50:48 -03:00
perf-buildid-cache.txt perf record: Disable debuginfod by default 2022-01-15 17:41:25 -03:00
perf-buildid-list.txt perf buildid-list: Add a "-m" option to show kernel and modules build-ids 2022-07-18 16:35:34 -03:00
perf-c2c.txt perf c2c: Update documentation for store metric 'N/A' 2022-05-23 09:36:47 -03:00
perf-config.txt perf record: Disable debuginfod by default 2022-01-15 17:41:25 -03:00
perf-daemon.txt perf daemon: Add examples to man page 2021-02-11 10:19:52 -03:00
perf-data.txt perf data: Add JSON export 2021-04-29 10:30:58 -03:00
perf-diff.txt perf diff: Support hot streams comparison 2020-10-14 13:34:48 -03:00
perf-dlfilter.txt perf dlfilter: Add machine_pid and vcpu 2022-07-20 11:08:13 -03:00
perf-evlist.txt perf tools: Fix documentation of verbose options 2021-03-06 16:54:26 -03:00
perf-ftrace.txt perf ftrace latency: Update documentation 2022-03-22 17:45:39 -03:00
perf-help.txt
perf-inject.txt perf inject: Add support for injecting guest sideband events 2022-07-20 11:08:37 -03:00
perf-intel-pt.txt perf intel-pt: Add documentation for tracing guest machine user space 2022-07-20 11:09:07 -03:00
perf-iostat.txt perf docs: Fix accidental em-dashes 2021-08-10 11:05:21 -03:00
perf-kallsyms.txt perf tools: Fix documentation of verbose options 2021-03-06 16:54:26 -03:00
perf-kmem.txt perf kmem: Improve man page for record options 2021-10-08 16:10:02 -03:00
perf-kvm.txt perf kvm report: Add guest_code support 2022-05-23 10:19:15 -03:00
perf-kwork.txt perf kwork: Implement BPF trace 2022-07-26 16:31:54 -03:00
perf-list.txt perf docs: Update link to AMD documentation 2021-12-07 22:18:24 -03:00
perf-lock.txt perf lock: Add --map-nr-entries option 2022-08-02 18:02:59 -03:00
perf-mem.txt perf mem: Support data page size 2021-01-20 14:34:20 -03:00
perf-probe.txt perf probe: Add permission and sysctl notice to man page 2021-06-04 10:24:38 -03:00
perf-record.txt perf record: Allow to specify max stack depth of fp callchain 2022-07-12 09:56:05 -03:00
perf-report.txt perf report: Add --skip-empty option to suppress 0 event stat 2021-04-29 10:30:59 -03:00
perf-sched.txt perf sched timehist: Add support for filtering on CPU 2020-01-06 11:46:09 -03:00
perf-script-perl.txt perf doc: Fix typos all over the place 2021-09-27 09:32:28 -03:00
perf-script-python.txt perf doc: Fix typos all over the place 2021-09-27 09:32:28 -03:00
perf-script.txt perf script: Add machine_pid and vcpu 2022-07-20 11:08:13 -03:00
perf-stat.txt perf stat: Add JSON output option 2022-08-10 10:43:29 -03:00
perf-test.txt
perf-timechart.txt perf timechart: Document missing --force option 2017-11-16 14:50:06 -03:00
perf-top.txt perf docs: Correct typo of event_sources 2022-06-03 21:14:51 +02:00
perf-trace.txt perf tools: Fix documentation of verbose options 2021-03-06 16:54:26 -03:00
perf-version.txt perf version: Add man page 2018-04-02 13:52:23 -03:00
perf.data-directory-format.txt perf record: Put a copy of kcore into the perf.data directory 2019-11-06 15:43:05 -03:00
perf.data-file-format.txt perf header: Record non-CPU PMU capabilities 2022-06-24 13:18:55 -03:00
perf.txt perf docs: Add man page entry for Arm SPE 2022-04-14 08:54:03 -03:00
perfconfig.example
security.txt perf docs: Introduce security.txt file to document related issues 2020-05-28 10:03:26 -03:00
tips.txt perf tools: Fix typos / broken sentences 2019-07-02 16:08:16 -03:00
topdown.txt perf doc: Fix typos all over the place 2021-09-27 09:32:28 -03:00