'\" t
.\"     Title: perf-sched
.\"    Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 07/31/2026
.\"    Manual: perf Manual
.\"    Source: perf
.\"  Language: English
.\"
.TH "PERF\-SCHED" "1" "07/31/2026" "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 <command>\*(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]  <idle>                    1\&.148      0\&.000      0\&.035
    79371\&.874723 [0005]  <idle>                    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=<file>
.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=<file>
.RS 4
vmlinux pathname
.RE
.PP
\-\-kallsyms=<file>
.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=<directory>
.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: <start>,<stop>\&. 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)
