bcc-cpudist(8)

1cpudist(8)                  System Manager's Manual                 cpudist(8)
2
3
4

NAME

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

SYNOPSIS

9       cpudist  [-h]  [-O]  [-T]  [-m] [-P] [-L] [-p PID] [-I] [-e] [interval]
10       [count]
11

DESCRIPTION

13       This measures the time a task spends on the CPU before  being  desched‐
14       uled, and shows the times as a histogram. Tasks that spend a very short
15       time on the CPU can be indicative  of  excessive  context-switches  and
16       poor  workload  distribution,  and possibly point to a shared source of
17       contention that keeps tasks switching in and out as it  becomes  avail‐
18       able (such as a mutex).
19
20       Similarly, the tool can also measure the time a task spends off-CPU be‐
21       fore it is scheduled again. This can be  helpful  in  identifying  long
22       blocking  and  I/O operations, or alternatively very short descheduling
23       times due to short-lived locks or timers.
24
25       By default CPU idle time are excluded by simply excluding PID 0.
26
27       This tool uses in-kernel eBPF maps for storing timestamps and the  his‐
28       togram, for efficiency. Despite this, the overhead of this tool may be‐
29       come significant for some workloads: see the OVERHEAD section.
30
31       Since this uses BPF, only the root user can use this tool.
32

REQUIREMENTS

34       CONFIG_BPF and bcc.
35

OPTIONS

37       -h     Print usage message.
38
39       -O     Measure off-CPU time instead of on-CPU time.
40
41       -T     Include timestamps on output.
42
43       -m     Output histogram in milliseconds.
44
45       -P     Print a histogram for each PID (tgid from the kernel's  perspec‐
46              tive).
47
48       -L     Print  a  histogram for each TID (pid from the kernel's perspec‐
49              tive).
50
51       -p PID Only show this PID (filtered in kernel for efficiency).
52
53       -I     Include CPU idle time (by default these are excluded).
54
55       -e     Show extension summary (average/total/count).
56
57       interval
58              Output interval, in seconds.
59
60       count  Number of outputs.
61

EXAMPLES

63       Summarize task on-CPU time as a histogram:
64              # cpudist
65
66       Summarize task off-CPU time as a histogram:
67              # cpudist -O
68
69       Print 1 second summaries, 10 times:
70              # cpudist 1 10
71
72       Print 1 second summaries, using milliseconds  as  units  for  the  his‐
73       togram, and include timestamps on output:
74              # cpudist -mT 1
75
76       Trace PID 185 only, 1 second summaries:
77              # cpudist -p 185 1
78
79       Include CPU idle time:
80              # cpudist -I
81
82       Also show extension summary:
83              # cpudist -e
84

FIELDS

86       usecs  Microsecond range
87
88       msecs  Millisecond range
89
90       count  How many times a task event fell into this range
91
92       distribution
93              An ASCII bar chart to visualize the distribution (count column)
94

OVERHEAD

96       This  traces  scheduler  tracepoints,  which  can become very frequent.
97       While eBPF has very low overhead, and this tool uses in-kernel maps for
98       efficiency, the frequency of scheduler events for some workloads may be
99       high enough that the overhead of this tool becomes significant. Measure
100       in a lab environment to quantify the overhead before use.
101

SOURCE

103       This is from bcc.
104
105              https://github.com/iovisor/bcc
106
107       Also  look  in  the  bcc distribution for a companion _example.txt file
108       containing example usage, output, and commentary for this tool.
109

OS

111       Linux
112

STABILITY

114       Unstable - in development.
115

AUTHOR

117       Sasha Goldshtein, Rocky Xing
118