---
name: "perf-stat-hist"
section: "8"
platform: "linux"
package: "perf-tools-unstable"
version: "0.0.1~20140723+git942be0b-4"
release: "Debian 8 (Jessie)"
platforms: ["linux"]
url: "https://new.carta.tech/perf-stat-hist"
---

# perf-stat-hist(8)

histogram summary of tracepoint values. Uses Linux perf\_events.

## NAME

perf-stat-hist - histogram summary of tracepoint values. Uses Linux perf\_events.

## SYNOPSIS

**perf-stat-hist** \[-h\] \[-b buckets\|-P power\] \[-m max\] tracepoint variable \[seconds\]

## 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.

## REQUIREMENTS

Linux perf\_events: add linux-tools-common, run "perf", then add any additional packages it requests. Also uses awk.

## OPTIONS

- \-h

  Usage message.

- \-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.

- \-P power

  Power for power-of histogram. By default, a power-of-4 histogram is created. This and the -b option are exclusive.

- \-m max

  Max value for power-of histograms.

- tracepoint

  Tracepoint specification. Eg, syscalls:sys\_enter\_read.

- variable

  The tracepoint variable name to summarize. To see what are available, cat the format file under /sys/kernel/debug/tracing/events/\*/\*/format.

- seconds

  Number of seconds to trace. If not specified, this runs until Ctrl-C.

## EXAMPLES

- Trace read() syscalls until Ctrl-C, and show histogram of requested size:

  \# **perf-stat-hist syscalls:sys\_enter\_read count**

- Trace read() syscall completions until Ctrl-C, and show histogram of successful returned size:

  \# **perf-stat-hist syscalls:sys\_exit\_read ret**

- Trace read() return sizes for 10 seconds, showing histogram:

  \# **perf-stat-hist syscalls:sys\_exit\_read ret 10**

- Trace network transmits until Ctrl-C, and show histogram of packet size:

  \# **perf-stat-hist net:net\_dev\_xmit len**

- Trace read() return sizes, using a power-of-10 histogram:

  **perf-stat-hist -P 10 syscalls:sys\_exit\_read ret**

- Trace read() return sizes, using a power-of-2 histogram, and a max of 1024:

  **perf-stat-hist -P 2 -m 1024 syscalls:sys\_exit\_read ret**

- Trace read() return sizes, using the specified bucket points:

  **perf-stat-hist -b "10 50 100 5000" syscalls:sys\_exit\_read ret**

- Trace read() return sizes, and bifurcate statistics by the value 10:

  **perf-stat-hist -b 10 syscalls:sys\_exit\_read ret**

## FIELDS

- Range

  Range of the histogram bucket, in units of the variable specified.

- Count

  Number of occurrences (tracepoint events) of the variable in this range.

- Distribution

  ASCII histogram representation of the Count column.

## 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.

## SOURCE

This is from the perf-tools collection.

-

  https://github.com/brendangregg/perf-tools

Also look under the examples directory for a text file containing example usage, output, and commentary for this tool.

## OS

Linux

## STABILITY

Unstable - in development.

## AUTHOR

Brendan Gregg

## SEE ALSO

[perf(1)](/perf/1.md)