linux/tools/perf/Documentation
Aaron Tomlin bf10e6ee2a perf sched latency: Add histogram and time interval options
While 'perf sched latency' reports task runtime and delay statistics
(average and maximum delay), it does not provide a visual representation
of how task wait times are distributed across latency ranges between
snapshots (start and finish of the analysis window).

The --histogram option collects CPU wait latencies (time between when
a task becomes runnable and when it gets scheduled onto a CPU) into 22
latency buckets, displaying an ASCII bar chart distribution.

The --hist-mode option configures the bucketing scheme:
  - log (default). Logarithmic latency buckets ranging from
    sub-microsecond (< 1 us) up to >= 1.05 seconds

  - linear. Equal-width linear latency buckets
    (i.e., 100 us steps up to >= 2.1 ms)

The --time option allows filtering trace event processing to a
specific time interval [start,stop].

Example histogram output excerpt:

    ❯ sudo perf sched latency --histogram --CPU 0

     CPU Wait Latency Distribution Histogram (between snapshots) (total samples: 36114)
     -------------------------------------------------------------------
      Latency Range    |      Count |    Pct | Histogram Graph
     -------------------------------------------------------------------
      < 1 us           |         17 |   0.0% | #
      2 - 4 us         |        673 |   1.9% | #
      4 - 8 us         |       6237 |  17.3% | ######
      8 - 16 us        |       3224 |   8.9% | ###
      16 - 32 us       |       1388 |   3.8% | #
      32 - 64 us       |        709 |   2.0% | #
      64 - 128 us      |        690 |   1.9% | #
      128 - 256 us     |        789 |   2.2% | #
      256 - 512 us     |        541 |   1.5% | #
      512 - 1024 us    |       2256 |   6.2% | ##
      1 - 2 ms         |       3577 |   9.9% | ###
      2 - 4 ms         |      13259 |  36.7% | ##############
      4 - 8 ms         |       2523 |   7.0% | ##
      8 - 16 ms        |        222 |   0.6% | #
      16 - 32 ms       |         10 |   0.0% | #
      >= 1.05 s        |          3 |   0.0% | #
     -------------------------------------------------------------------

Reviewed-by: Ian Rogers <irogers@google.com>
Signed-off-by: Aaron Tomlin <atomlin@atomlin.com>
Signed-off-by: Namhyung Kim <namhyung@kernel.org>
2026-08-07 10:56:23 -07:00
..
android.txt perf docs: Document building with Clang 2025-10-06 16:49:25 -03:00
arm-coresight.txt perf docs: Fix man page build wrt perf-arm-coresight.txt 2022-10-25 17:40:48 -03:00
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 docs: Document building with Clang 2025-10-06 16:49:25 -03:00
callchain-overhead-calculation.txt perf report: Add latency and parallelism profiling documentation 2025-02-18 14:04:32 -08:00
cat-texi.perl perf doc: Fix perfman.info build 2021-08-02 09:56:17 -03:00
cpu-and-latency-overheads.txt perf report: Add latency and parallelism profiling documentation 2025-02-18 14:04:32 -08: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
guest-files.txt perf tools: Tidy guest option documentation 2022-08-11 18:50:17 -03:00
guestmount.txt perf tools: Tidy guest option documentation 2022-08-11 18:50:17 -03:00
intel-acr.txt perf record: Add ratio-to-prev term 2025-10-03 16:49:51 -03:00
intel-bts.txt perf tools: Add Intel BTS support 2015-08-21 11:34:10 -03:00
intel-hybrid.txt perf tools: Fix up some comments and code to properly use the event_source bus 2025-02-19 13:23:43 -08: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 arm-spe: Update --itrace help text 2024-10-29 16:10:17 -07: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: Add support for KBUILD_BUILD_TIMESTAMP 2023-05-15 17:49:01 -03:00
manpage-1.72.xsl
manpage-base.xsl
manpage-bold-literal.xsl
manpage-normal.xsl
manpage-suppress-sp.xsl
perf-amd-ibs.txt perf doc: Document new IBS capabilities in man page 2026-05-22 21:32:28 -03:00
perf-annotate.txt perf tools: Add layout support for --symfs option 2026-03-10 23:13:30 -07:00
perf-archive.txt
perf-arm-spe.txt KVM: arm64: Remove all traces of FEAT_TME 2026-02-05 09:02:13 +00:00
perf-bench.txt perf bench: Add -t/--threads option to perf bench mem mmap 2026-02-26 10:54:12 -08: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 adding memory event table 2026-01-20 17:31:28 -03:00
perf-check.txt perf build: Remove NO_AUXTRACE build option 2025-11-13 23:03:11 -08:00
perf-config.txt perf config: Make symbol_conf::addr2line_disable_warn configurable 2026-04-08 10:28:49 -07:00
perf-daemon.txt perf daemon: Add examples to man page 2021-02-11 10:19:52 -03:00
perf-data.txt perf data: Allow filtering conversion by time range 2026-01-06 19:20:02 -03:00
perf-diff.txt perf tools: Add layout support for --symfs option 2026-03-10 23:13:30 -07:00
perf-dlfilter.txt perf dlfilter: Add al_cleanup() 2023-08-15 16:41:49 -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: add graph tracer options args/retval/retval-hex/retaddr 2025-07-22 17:47:22 -07:00
perf-help.txt
perf-inject.txt perf inject: Add --convert-callchain option 2026-01-20 17:18:24 -03:00
perf-intel-pt.txt perf intel-pt: Add documentation for pause / resume 2024-12-18 16:24:32 -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 docs: Refine the description for the buffer size 2024-08-12 13:59:22 -03:00
perf-kwork.txt perf tools: Add layout support for --symfs option 2026-03-10 23:13:30 -07:00
perf-list.txt perf record: Add ratio-to-prev term 2025-10-03 16:49:51 -03:00
perf-lock.txt perf lock contention: Reject more than 10ms delays for safety 2025-05-31 08:45:24 -03:00
perf-mem.txt perf mem: Document new output fields (op, cache, mem, dtlb, snoop) 2025-06-16 14:05:10 -03:00
perf-probe.txt perf tools: Add layout support for --symfs option 2026-03-10 23:13:30 -07:00
perf-record.txt perf Documentation: Correct branch stack sampling call-stack option 2026-01-13 17:29:57 -03:00
perf-report.txt perf report: Update document for SIMD flags 2026-04-10 09:52:06 -07:00
perf-sched.txt perf sched latency: Add histogram and time interval options 2026-08-07 10:56:23 -07:00
perf-script-perl.txt perf tools docs: Use canonical ftrace path 2023-02-02 16:32:19 -03:00
perf-script-python.txt perf scripting python: Add function to get a config value 2024-09-24 11:47:03 -07:00
perf-script.txt perf tools: Add layout support for --symfs option 2026-03-10 23:13:30 -07:00
perf-stat.txt perf stat: Add --hide-zero-events option to suppress zero-count events 2026-07-19 21:49:30 -07:00
perf-test.txt perf test: Add Arm CoreSight callchain test 2026-07-03 16:52:00 -07:00
perf-timechart.txt perf tools: Add layout support for --symfs option 2026-03-10 23:13:30 -07:00
perf-top.txt perf docs: Refine the description for the buffer size 2024-08-12 13:59:22 -03:00
perf-trace.txt perf trace: Add --bitmask-list command-line option 2026-07-23 22:59:42 -07: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 tools: Document recent additions to the perf.data file header 2026-06-15 16:54:39 -03:00
perf.txt perf doc: Add AMD IBS usage document 2024-06-20 16:51:55 -07:00
perfconfig.example perf config: Show default report configuration in example and docs 2016-09-01 09:44:13 -03:00
security.txt perf docs: Introduce security.txt file to document related issues 2020-05-28 10:03:26 -03:00
tips.txt perf tools: Add layout support for --symfs option 2026-03-10 23:13:30 -07:00
topdown.txt perf doc: Fix mmap failure checks in topdown example 2026-07-15 11:16:41 -07:00