bcc-runqslower(8)

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

NAME

6       runqslower - Trace long process scheduling delays.
7

SYNOPSIS

9       runqslower [-p PID] [-t TID] [-P] [min_us]
10

DESCRIPTION

12       This measures the time a task spends waiting on a run queue (or equiva‐
13       lent scheduler data structure) for a turn on-CPU, and shows occurrences
14       of  time  exceeding  passed threshold. This time should be small, but a
15       task may need to wait its turn due to CPU  load.  The  higher  the  CPU
16       load, the longer a task will generally need to wait its turn.
17
18       This tool measures two types of run queue latency:
19
20       1.  The  time  from a task being enqueued on a run queue to its context
21       switch and execution. This traces ttwu_do_wakeup(),  wake_up_new_task()
22       ->  finish_task_switch()  with either raw tracepoints (if supported) or
23       kprobes and instruments the run queue latency after a voluntary context
24       switch.
25
26       2. The time from when a task was involuntary context switched and still
27       in the runnable state, to when it next executed. This  is  instrumented
28       from finish_task_switch() alone.
29
30       The  overhead  of  this tool may become significant for some workloads:
31       see the OVERHEAD section.
32
33       This works by tracing various kernel scheduler functions using  dynamic
34       tracing,  and  will  need  updating to match any changes to these func‐
35       tions.
36
37       Since this uses BPF, only the root user can use this tool.
38

REQUIREMENTS

40       CONFIG_BPF and bcc.
41

OPTIONS

43       -h     Print usage message.
44
45       -p PID Only show this PID (filtered in kernel for efficiency).
46
47       -t TID Only show this TID (filtered in kernel for efficiency).
48
49       min_us Minimum scheduling delay in microseconds to output.
50
51       -P     Also show previous task comm and TID.
52

EXAMPLES

54       Show scheduling delays longer than 10ms:
55              # runqslower
56
57       Show scheduling delays longer than 1ms for process with PID 123:
58              # runqslower -p 123 1000
59

FIELDS

61       TIME   Time of when scheduling event occurred.
62
63       COMM   Process name.
64
65       PID    Process ID.
66
67       LAT(us)
68              Scheduling latency from time when task was ready to run  to  the
69              time it was assigned to a CPU to run.
70

OVERHEAD

72       This  traces scheduler functions, which can become very frequent. While
73       eBPF has very low overhead, and this tool uses in-kernel maps for effi‐
74       ciency,  the  frequency  of  scheduler events for some workloads may be
75       high enough that the overhead of this tool becomes significant. Measure
76       in a lab environment to quantify the overhead before use.
77

SOURCE

79       This is from bcc.
80
81              https://github.com/iovisor/bcc
82
83       Also  look  in  the bcc distribution for a companion _examples.txt file
84       containing example usage, output, and commentary for this tool.
85

OS

87       Linux
88

STABILITY

90       Unstable - in development.
91

AUTHOR

93       Ivan Babrou, original BCC Python version Andrii Nakryiko, CO-RE version
94