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

       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 perspective).

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

       -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 histogram, 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)