mirror of
https://github.com/brendangregg/perf-tools.git
synced 2025-12-01 07:26:04 +07:00
112 lines
3.8 KiB
Groff
112 lines
3.8 KiB
Groff
.TH perf-stat-hist 8 "2014-07-07" "USER COMMANDS"
|
|
.SH NAME
|
|
perf-stat-hist \- histogram summary of tracepoint values. Uses Linux perf_events.
|
|
.SH SYNOPSIS
|
|
.B perf-stat-hist
|
|
[-h] [-b buckets|-P power] [-m max] tracepoint variable [seconds]
|
|
.SH DESCRIPTION
|
|
This is a proof-of-concept showing in-kernel histograms using Linux perf_events
|
|
(aka the "perf" command), on older kernels where perf_events does not have
|
|
this native capability.
|
|
|
|
These histograms show the distribution of variable, allowing details
|
|
including multiple modes and outliers to be studied.
|
|
|
|
This uses multiple counting tracepoints with different filters, one for each
|
|
histogram bucket. While this is summarized in-kernel, the use of multiple
|
|
tracepoints does add addiitonal overhead. Hopefully, in the
|
|
future this this functionality will be provided in an efficient way from
|
|
perf_events itself, at which point this tool can be deleted or rewritten.
|
|
.SH REQUIREMENTS
|
|
Linux perf_events: add linux-tools-common, run "perf", then add any additional
|
|
packages it requests. Also uses awk.
|
|
.SH OPTIONS
|
|
.TP
|
|
\-h
|
|
Usage message.
|
|
.TP
|
|
\-b buckets
|
|
Specify a list of bucket points for the histogram as a string (eg, "10 500
|
|
1000"). The histogram will include buckets for less-than the minimum, and
|
|
greater-than-or-equal-to the maximum. If a single value is specified, two
|
|
statistics only are gathered: for less-than and for greater-than-or-equal-to.
|
|
The overhead is relative to the number of buckets, so only specifying a
|
|
single value costs the lowest overhead.
|
|
.TP
|
|
\-P power
|
|
Power for power-of histogram. By default, a power-of-4 histogram is created.
|
|
This and the \-b option are exclusive.
|
|
.TP
|
|
\-m max
|
|
Max value for power-of histograms.
|
|
.TP
|
|
tracepoint
|
|
Tracepoint specification. Eg, syscalls:sys_enter_read.
|
|
.TP
|
|
variable
|
|
The tracepoint variable name to summarize. To see what are available, cat the
|
|
format file under /sys/kernel/debug/tracing/events/*/*/format.
|
|
.TP
|
|
seconds
|
|
Number of seconds to trace. If not specified, this runs until Ctrl-C.
|
|
.SH EXAMPLES
|
|
.TP
|
|
Trace read() syscalls until Ctrl-C, and show histogram of requested size:
|
|
#
|
|
.B perf\-stat\-hist syscalls:sys_enter_read count
|
|
.TP
|
|
Trace read() syscall completions until Ctrl-C, and show histogram of successful returned size:
|
|
#
|
|
.B perf\-stat\-hist syscalls:sys_exit_read ret
|
|
.TP
|
|
Trace read() return sizes for 10 seconds, showing histogram:
|
|
#
|
|
.B perf\-stat\-hist syscalls:sys_exit_read ret 10
|
|
.TP
|
|
Trace network transmits until Ctrl-C, and show histogram of packet size:
|
|
#
|
|
.B perf\-stat\-hist net:net_dev_xmit len
|
|
.TP
|
|
Trace read() return sizes, using a power-of-10 histogram:
|
|
.B perf\-stat\-hist \-P 10 syscalls:sys_exit_read ret
|
|
.TP
|
|
Trace read() return sizes, using a power-of-2 histogram, and a max of 1024:
|
|
.B perf\-stat\-hist \-P 2 \-m 1024 syscalls:sys_exit_read ret
|
|
.TP
|
|
Trace read() return sizes, using the specified bucket points:
|
|
.B perf\-stat\-hist \-b """10 50 100 5000""" syscalls:sys_exit_read ret
|
|
.TP
|
|
Trace read() return sizes, and bifurcate statistics by the value 10:
|
|
.B perf-stat-hist \-b 10 syscalls:sys_exit_read ret
|
|
.SH FIELDS
|
|
.TP
|
|
Range
|
|
Range of the histogram bucket, in units of the variable specified.
|
|
.TP
|
|
Count
|
|
Number of occurrences (tracepoint events) of the variable in this range.
|
|
.TP
|
|
Distribution
|
|
ASCII histogram representation of the Count column.
|
|
.SH OVERHEAD
|
|
While the counts are performed in-kernel, there is one tracepoint used per
|
|
histogram bucket, so the overheads are higher than usual (relative to the
|
|
number of buckets) than function counting using perf stat. The lowest
|
|
overhead is when \-b is used to specify one bucket only, bifurcating
|
|
statistics.
|
|
.SH SOURCE
|
|
This is from the perf-tools collection.
|
|
.IP
|
|
https://github.com/brendangregg/perf-tools
|
|
.PP
|
|
Also look under the examples directory for a text file containing example
|
|
usage, output, and commentary for this tool.
|
|
.SH OS
|
|
Linux
|
|
.SH STABILITY
|
|
Unstable - in development.
|
|
.SH AUTHOR
|
|
Brendan Gregg
|
|
.SH SEE ALSO
|
|
perf(1)
|