cpudist(8) System Manager's Manual cpudist(8)

# [NAME](#NAME)

cpudist - On- and off-CPU task time as a histogram.

# [SYNOPSIS](#SYNOPSIS)

**cpudist \[-h] \[-O] \[-T] \[-m] \[-P] \[-L] \[-p PID] \[-I] \[-e] \[interval] \[count]**

# [DESCRIPTION](#DESCRIPTION)

This measures the time a task spends on the CPU before being descheduled, 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 available (such as a mutex).

Similarly, the tool can also measure the time a task spends off-CPU before 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 histogram, for efficiency. Despite this, the overhead of this tool may become significant for some workloads: see the OVERHEAD section.

Since this uses BPF, only the root user can use this tool.

# [REQUIREMENTS](#REQUIREMENTS)

CONFIG\_BPF and bcc.

# [OPTIONS](#OPTIONS)

[-h](#h)

Print usage message.

[-O](#O)

Measure off-CPU time instead of on-CPU time.

[-T](#T)

Include timestamps on output.

[-m](#m)

Output histogram in milliseconds.

[-P](#P)

Print a histogram for each PID (tgid from the kernel's perspective).

[-L](#L)

Print a histogram for each TID (pid from the kernel's perspective).

[-p PID](#p)

Only show this PID (filtered in kernel for efficiency).

[-I](#I)

Include CPU idle time (by default these are excluded).

[-e](#e)

Show extension summary (average/total/count).

[interval](#interval)

Output interval, in seconds.

[count](#count)

Number of outputs.

# [EXAMPLES](#EXAMPLES)

[Summarize task on-CPU time as a histogram:](#Summarize)

\# **cpudist**

[Summarize task off-CPU time as a histogram:](#Summarize~2)

\# **cpudist -O**

[Print 1 second summaries, 10 times:](#Print)

\# **cpudist 1 10**

[Print 1 second summaries, using milliseconds as units for the histogram, and include timestamps on output:](#Print~2)

\# **cpudist -mT 1**

[Trace PID 185 only, 1 second summaries:](#Trace)

\# **cpudist -p 185 1**

[Include CPU idle time:](#Include)

\# **cpudist -I**

[Also show extension summary:](#Also)

\# **cpudist -e**

# [FIELDS](#FIELDS)

[usecs](#usecs)

Microsecond range

[msecs](#msecs)

Millisecond range

[count](#count~2)

How many times a task event fell into this range

[distribution](#distribution)

An ASCII bar chart to visualize the distribution (count column)

# [OVERHEAD](#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](#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](#OS)

Linux

# [STABILITY](#STABILITY)

Unstable - in development.

# [AUTHOR](#AUTHOR)

Sasha Goldshtein, Rocky Xing

# [SEE ALSO](#SEE_ALSO)

[pidstat(1)](/man/enterprise-packages/bcc/pidstat.1), [runqlat(8)](/man/enterprise-packages/bcc/runqlat.8)

2016-06-28 USER COMMANDS

---

Document: cpudist(8) from bcc 0.37.0-r2 (Chainguard OS)
Source: https://github.com/iovisor/bcc