'\" t
.\" Title: perf-sched
.\" Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
.\" Generator: DocBook XSL Stylesheets vsnapshot
.\" Date: 11/12/2025
.\" Manual: perf Manual
.\" Source: perf
.\" Language: English
.\"
.TH "PERF\-SCHED" "1" "11/12/2025" "perf" "perf Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
perf-sched \- Tool to trace/measure scheduler properties (latencies)
.SH "SYNOPSIS"
.sp
.nf
\fIperf sched\fR {record|latency|map|replay|script|timehist}
.fi
.SH "DESCRIPTION"
.sp
There are several variants of \fIperf sched\fR:
.sp
.if n \{\
.RS 4
.\}
.nf
\*(Aqperf sched record \*(Aq to record the scheduling events
of an arbitrary workload\&.
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
\*(Aqperf sched latency\*(Aq to report the per task scheduling latencies
and other scheduling properties of the workload\&.
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
\*(Aqperf sched script\*(Aq to see a detailed trace of the workload that
was recorded (aliased to \*(Aqperf script\*(Aq for now)\&.
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
\*(Aqperf sched replay\*(Aq to simulate the workload that was recorded
via perf sched record\&. (this is done by starting up mockup threads
that mimic the workload based on the events in the trace\&. These
threads can then replay the timings (CPU runtime and sleep patterns)
of the workload as it occurred when it was recorded \- and can repeat
it a number of times, measuring its performance\&.)
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
\*(Aqperf sched map\*(Aq to print a textual context\-switching outline of
workload captured via perf sched record\&. Columns stand for
individual CPUs, and the two\-letter shortcuts stand for tasks that
are running on a CPU\&. A \*(Aq*\*(Aq denotes the CPU that had the event, and
a dot signals an idle CPU\&.
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
\*(Aqperf sched timehist\*(Aq provides an analysis of scheduling events\&.
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
Example usage:
perf sched record \-\- sleep 1
perf sched timehist
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
By default it shows the individual schedule events, including the wait
time (time between sched\-out and next sched\-in events for the task), the
task scheduling delay (time between wakeup and actually running) and run
time for the task:
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
time cpu task name wait time sch delay run time
[tid/pid] (msec) (msec) (msec)
\-\-\-\-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-
79371\&.874569 [0011] gcc[31949] 0\&.014 0\&.000 1\&.148
79371\&.874591 [0010] gcc[31951] 0\&.000 0\&.000 0\&.024
79371\&.874603 [0010] migration/10[59] 3\&.350 0\&.004 0\&.011
79371\&.874604 [0011] 1\&.148 0\&.000 0\&.035
79371\&.874723 [0005] 0\&.016 0\&.000 1\&.383
79371\&.874746 [0005] gcc[31949] 0\&.153 0\&.078 0\&.022
\&.\&.\&.
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
Times are in msec\&.usec\&.
.fi
.if n \{\
.RE
.\}
.SH "OPTIONS"
.PP
\-i, \-\-input=
.RS 4
Input file name\&. (default: perf\&.data unless stdin is a fifo)
.RE
.PP
\-v, \-\-verbose
.RS 4
Be more verbose\&. (show symbol address, etc)
.RE
.PP
\-D, \-\-dump\-raw\-trace=
.RS 4
Display verbose dump of the sched data\&.
.RE
.PP
\-f, \-\-force
.RS 4
Don\(cqt complain, do it\&.
.RE
.SH "OPTIONS FOR \FIPERF SCHED MAP\FR"
.PP
\-\-compact
.RS 4
Show only CPUs with activity\&. Helps visualizing on high core count systems\&.
.RE
.PP
\-\-cpus
.RS 4
Show just entries with activities for the given CPUs\&.
.RE
.PP
\-\-color\-cpus
.RS 4
Highlight the given cpus\&.
.RE
.PP
\-\-color\-pids
.RS 4
Highlight the given pids\&.
.RE
.SH "OPTIONS FOR \FIPERF SCHED TIMEHIST\FR"
.PP
\-k, \-\-vmlinux=
.RS 4
vmlinux pathname
.RE
.PP
\-\-kallsyms=
.RS 4
kallsyms pathname
.RE
.PP
\-g, \-\-call\-graph
.RS 4
Display call chains if present (default on)\&.
.RE
.PP
\-\-max\-stack
.RS 4
Maximum number of functions to display in backtrace, default 5\&.
.RE
.PP
\-C=, \-\-cpu=
.RS 4
Only show events for the given CPU(s) (comma separated list)\&.
.RE
.PP
\-p=, \-\-pid=
.RS 4
Only show events for given process ID (comma separated list)\&.
.RE
.PP
\-t=, \-\-tid=
.RS 4
Only show events for given thread ID (comma separated list)\&.
.RE
.PP
\-s, \-\-summary
.RS 4
Show only a summary of scheduling by thread with min, max, and average run times (in sec) and relative stddev\&.
.RE
.PP
\-S, \-\-with\-summary
.RS 4
Show all scheduling events followed by a summary by thread with min, max, and average run times (in sec) and relative stddev\&.
.RE
.PP
\-\-symfs=
.RS 4
Look for files with symbols relative to this directory\&.
.RE
.PP
\-V, \-\-cpu\-visual
.RS 4
Show visual aid for sched switches by CPU:
\fIi\fR
marks idle time,
\fIs\fR
are scheduler events\&.
.RE
.PP
\-w, \-\-wakeups
.RS 4
Show wakeup events\&.
.RE
.PP
\-M, \-\-migrations
.RS 4
Show migration events\&.
.RE
.PP
\-n, \-\-next
.RS 4
Show next task\&.
.RE
.PP
\-I, \-\-idle\-hist
.RS 4
Show idle\-related events only\&.
.RE
.PP
\-\-time
.RS 4
Only analyze samples within given time window: ,\&. Times have the format seconds\&.microseconds\&. If start is not given (i\&.e\&., time string is
\fI,x\&.y\fR) then analysis starts at the beginning of the file\&. If stop time is not given (i\&.e, time string is
\fIx\&.y,\fR) then analysis goes to end of file\&.
.RE
.PP
\-\-state
.RS 4
Show task state when it switched out\&.
.RE
.SH "SEE ALSO"
.sp
\fBperf-record\fR(1)