cpudist(8) System Manager's Manual cpudist(8)
NAME
cpudist - On- and off-CPU task time as a histogram.
SYNOPSIS
cpudist [-h] [-O] [-T] [-m] [-P] [-L] [-p PID] [-I] [-e] [interval]
[count]
DESCRIPTION
This measures the time a task spends on the CPU before being desched-
uled, and shows the times as a histogram. Tasks that spend a very short
time on the CPU can be indicative of excessive context-switches and
poor workload distribution, and possibly point to a shared source of
contention that keeps tasks switching in and out as it becomes avail-
able (such as a mutex).
Similarly, the tool can also measure the time a task spends off-CPU be-
fore it is scheduled again. This can be helpful in identifying long
blocking and I/O operations, or alternatively very short descheduling
times due to short-lived locks or timers.
By default CPU idle time are excluded by simply excluding PID 0.
This tool uses in-kernel eBPF maps for storing timestamps and the his-
togram, for efficiency. Despite this, the overhead of this tool may be-
come significant for some workloads: see the OVERHEAD section.
Since this uses BPF, only the root user can use this tool.
REQUIREMENTS
CONFIG_BPF and bcc.
OPTIONS
-h Print usage message.
-O Measure off-CPU time instead of on-CPU time.
-T Include timestamps on output.
-m Output histogram in milliseconds.
-P Print a histogram for each PID (tgid from the kernel's perspec-
tive).
-L Print a histogram for each TID (pid from the kernel's perspec-
tive).
-p PID Only show this PID (filtered in kernel for efficiency).
-I Include CPU idle time (by default these are excluded).
-e Show extension summary (average/total/count).
interval
Output interval, in seconds.
count Number of outputs.
EXAMPLES
Summarize task on-CPU time as a histogram:
# cpudist
Summarize task off-CPU time as a histogram:
# cpudist -O
Print 1 second summaries, 10 times:
# cpudist 1 10
Print 1 second summaries, using milliseconds as units for the his-
togram, and include timestamps on output:
# cpudist -mT 1
Trace PID 185 only, 1 second summaries:
# cpudist -p 185 1
Include CPU idle time:
# cpudist -I
Also show extension summary:
# cpudist -e
FIELDS
usecs Microsecond range
msecs Millisecond range
count How many times a task event fell into this range
distribution
An ASCII bar chart to visualize the distribution (count column)
OVERHEAD
This traces scheduler tracepoints, which can become very frequent.
While eBPF has very low overhead, and this tool uses in-kernel maps for
efficiency, the frequency of scheduler events for some workloads may be
high enough that the overhead of this tool becomes significant. Measure
in a lab environment to quantify the overhead before use.
SOURCE
This is from bcc.
https://github.com/iovisor/bcc
Also look in the bcc distribution for a companion _example.txt file
containing example usage, output, and commentary for this tool.
OS
Linux
STABILITY
Unstable - in development.
AUTHOR
Sasha Goldshtein, Rocky Xing
SEE ALSO
pidstat(1), runqlat(8)
USER COMMANDS 2016-06-28 cpudist(8)
Generated by dwww version 1.16 on Tue Dec 16 06:00:25 CET 2025.