1PERF-SCHED(1)                     perf Manual                    PERF-SCHED(1)
2
3
4

NAME

6       perf-sched - Tool to trace/measure scheduler properties (latencies)
7

SYNOPSIS

9       perf sched {record|latency|map|replay|script|timehist}
10

DESCRIPTION

12       There are several variants of perf sched:
13
14           'perf sched record <command>' to record the scheduling events
15           of an arbitrary workload.
16
17           'perf sched latency' to report the per task scheduling latencies
18           and other scheduling properties of the workload.
19
20           'perf sched script' to see a detailed trace of the workload that
21            was recorded (aliased to 'perf script' for now).
22
23           'perf sched replay' to simulate the workload that was recorded
24           via perf sched record. (this is done by starting up mockup threads
25           that mimic the workload based on the events in the trace. These
26           threads can then replay the timings (CPU runtime and sleep patterns)
27           of the workload as it occurred when it was recorded - and can repeat
28           it a number of times, measuring its performance.)
29
30           'perf sched map' to print a textual context-switching outline of
31           workload captured via perf sched record.  Columns stand for
32           individual CPUs, and the two-letter shortcuts stand for tasks that
33           are running on a CPU. A '*' denotes the CPU that had the event, and
34           a dot signals an idle CPU.
35
36           'perf sched timehist' provides an analysis of scheduling events.
37
38           Example usage:
39               perf sched record -- sleep 1
40               perf sched timehist
41
42           By default it shows the individual schedule events, including the wait
43           time (time between sched-out and next sched-in events for the task), the
44           task scheduling delay (time between wakeup and actually running) and run
45           time for the task:
46
47                       time    cpu  task name             wait time  sch delay   run time
48                                    [tid/pid]                (msec)     (msec)     (msec)
49             -------------- ------  --------------------  ---------  ---------  ---------
50               79371.874569 [0011]  gcc[31949]                0.014      0.000      1.148
51               79371.874591 [0010]  gcc[31951]                0.000      0.000      0.024
52               79371.874603 [0010]  migration/10[59]          3.350      0.004      0.011
53               79371.874604 [0011]  <idle>                    1.148      0.000      0.035
54               79371.874723 [0005]  <idle>                    0.016      0.000      1.383
55               79371.874746 [0005]  gcc[31949]                0.153      0.078      0.022
56           ...
57
58           Times are in msec.usec.
59

OPTIONS

61       -i, --input=<file>
62           Input file name. (default: perf.data unless stdin is a fifo)
63
64       -v, --verbose
65           Be more verbose. (show symbol address, etc)
66
67       -D, --dump-raw-trace=
68           Display verbose dump of the sched data.
69
70       -f, --force
71           Don’t complain, do it.
72

OPTIONS FOR PERF SCHED MAP

74       --compact
75           Show only CPUs with activity. Helps visualizing on high core count
76           systems.
77
78       --cpus
79           Show just entries with activities for the given CPUs.
80
81       --color-cpus
82           Highlight the given cpus.
83
84       --color-pids
85           Highlight the given pids.
86

OPTIONS FOR PERF SCHED TIMEHIST

88       -k, --vmlinux=<file>
89           vmlinux pathname
90
91       --kallsyms=<file>
92           kallsyms pathname
93
94       -g, --call-graph
95           Display call chains if present (default on).
96
97       --max-stack
98           Maximum number of functions to display in backtrace, default 5.
99
100       -C=, --cpu=
101           Only show events for the given CPU(s) (comma separated list).
102
103       -p=, --pid=
104           Only show events for given process ID (comma separated list).
105
106       -t=, --tid=
107           Only show events for given thread ID (comma separated list).
108
109       -s, --summary
110           Show only a summary of scheduling by thread with min, max, and
111           average run times (in sec) and relative stddev.
112
113       -S, --with-summary
114           Show all scheduling events followed by a summary by thread with
115           min, max, and average run times (in sec) and relative stddev.
116
117       --symfs=<directory>
118           Look for files with symbols relative to this directory.
119
120       -V, --cpu-visual
121           Show visual aid for sched switches by CPU: i marks idle time, s are
122           scheduler events.
123
124       -w, --wakeups
125           Show wakeup events.
126
127       -M, --migrations
128           Show migration events.
129
130       -n, --next
131           Show next task.
132
133       -I, --idle-hist
134           Show idle-related events only.
135
136       --time
137           Only analyze samples within given time window: <start>,<stop>.
138           Times have the format seconds.microseconds. If start is not given
139           (i.e., time string is ,x.y) then analysis starts at the beginning
140           of the file. If stop time is not given (i.e, time string is x.y,)
141           then analysis goes to end of file.
142
143       --state
144           Show task state when it switched out.
145

SEE ALSO

147       perf-record(1)
148
149
150
151perf                              11/28/2023                     PERF-SCHED(1)