0001 perf-sched(1)
0002 =============
0003
0004 NAME
0005 ----
0006 perf-sched - Tool to trace/measure scheduler properties (latencies)
0007
0008 SYNOPSIS
0009 --------
0010 [verse]
0011 'perf sched' {record|latency|map|replay|script|timehist}
0012
0013 DESCRIPTION
0014 -----------
0015 There are several variants of 'perf sched':
0016
0017 'perf sched record <command>' to record the scheduling events
0018 of an arbitrary workload.
0019
0020 'perf sched latency' to report the per task scheduling latencies
0021 and other scheduling properties of the workload.
0022
0023 'perf sched script' to see a detailed trace of the workload that
0024 was recorded (aliased to 'perf script' for now).
0025
0026 'perf sched replay' to simulate the workload that was recorded
0027 via perf sched record. (this is done by starting up mockup threads
0028 that mimic the workload based on the events in the trace. These
0029 threads can then replay the timings (CPU runtime and sleep patterns)
0030 of the workload as it occurred when it was recorded - and can repeat
0031 it a number of times, measuring its performance.)
0032
0033 'perf sched map' to print a textual context-switching outline of
0034 workload captured via perf sched record. Columns stand for
0035 individual CPUs, and the two-letter shortcuts stand for tasks that
0036 are running on a CPU. A '*' denotes the CPU that had the event, and
0037 a dot signals an idle CPU.
0038
0039 'perf sched timehist' provides an analysis of scheduling events.
0040
0041 Example usage:
0042 perf sched record -- sleep 1
0043 perf sched timehist
0044
0045 By default it shows the individual schedule events, including the wait
0046 time (time between sched-out and next sched-in events for the task), the
0047 task scheduling delay (time between wakeup and actually running) and run
0048 time for the task:
0049
0050 time cpu task name wait time sch delay run time
0051 [tid/pid] (msec) (msec) (msec)
0052 -------------- ------ -------------------- --------- --------- ---------
0053 79371.874569 [0011] gcc[31949] 0.014 0.000 1.148
0054 79371.874591 [0010] gcc[31951] 0.000 0.000 0.024
0055 79371.874603 [0010] migration/10[59] 3.350 0.004 0.011
0056 79371.874604 [0011] <idle> 1.148 0.000 0.035
0057 79371.874723 [0005] <idle> 0.016 0.000 1.383
0058 79371.874746 [0005] gcc[31949] 0.153 0.078 0.022
0059 ...
0060
0061 Times are in msec.usec.
0062
0063 OPTIONS
0064 -------
0065 -i::
0066 --input=<file>::
0067 Input file name. (default: perf.data unless stdin is a fifo)
0068
0069 -v::
0070 --verbose::
0071 Be more verbose. (show symbol address, etc)
0072
0073 -D::
0074 --dump-raw-trace=::
0075 Display verbose dump of the sched data.
0076
0077 -f::
0078 --force::
0079 Don't complain, do it.
0080
0081 OPTIONS for 'perf sched map'
0082 ----------------------------
0083
0084 --compact::
0085 Show only CPUs with activity. Helps visualizing on high core
0086 count systems.
0087
0088 --cpus::
0089 Show just entries with activities for the given CPUs.
0090
0091 --color-cpus::
0092 Highlight the given cpus.
0093
0094 --color-pids::
0095 Highlight the given pids.
0096
0097 OPTIONS for 'perf sched timehist'
0098 ---------------------------------
0099 -k::
0100 --vmlinux=<file>::
0101 vmlinux pathname
0102
0103 --kallsyms=<file>::
0104 kallsyms pathname
0105
0106 -g::
0107 --call-graph::
0108 Display call chains if present (default on).
0109
0110 --max-stack::
0111 Maximum number of functions to display in backtrace, default 5.
0112
0113 -C=::
0114 --cpu=::
0115 Only show events for the given CPU(s) (comma separated list).
0116
0117 -p=::
0118 --pid=::
0119 Only show events for given process ID (comma separated list).
0120
0121 -t=::
0122 --tid=::
0123 Only show events for given thread ID (comma separated list).
0124
0125 -s::
0126 --summary::
0127 Show only a summary of scheduling by thread with min, max, and average
0128 run times (in sec) and relative stddev.
0129
0130 -S::
0131 --with-summary::
0132 Show all scheduling events followed by a summary by thread with min,
0133 max, and average run times (in sec) and relative stddev.
0134
0135 --symfs=<directory>::
0136 Look for files with symbols relative to this directory.
0137
0138 -V::
0139 --cpu-visual::
0140 Show visual aid for sched switches by CPU: 'i' marks idle time,
0141 's' are scheduler events.
0142
0143 -w::
0144 --wakeups::
0145 Show wakeup events.
0146
0147 -M::
0148 --migrations::
0149 Show migration events.
0150
0151 -n::
0152 --next::
0153 Show next task.
0154
0155 -I::
0156 --idle-hist::
0157 Show idle-related events only.
0158
0159 --time::
0160 Only analyze samples within given time window: <start>,<stop>. Times
0161 have the format seconds.microseconds. If start is not given (i.e., time
0162 string is ',x.y') then analysis starts at the beginning of the file. If
0163 stop time is not given (i.e, time string is 'x.y,') then analysis goes
0164 to end of file.
0165
0166 --state::
0167 Show task state when it switched out.
0168
0169 SEE ALSO
0170 --------
0171 linkperf:perf-record[1]
