.\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "RTLA-OSNOISE-TOP" 1 "" ""
.SH NAME
rtla-osnoise-top \- Display a summary of the operating system noise
.SH SYNOPSIS
.sp
\fBrtla osnoise top\fP [\fIOPTIONS\fP]
.SH DESCRIPTION
.sp
The \fBrtla osnoise\fP tool is an interface for the \fIosnoise\fP tracer. The
\fIosnoise\fP tracer dispatches a kernel thread per\-cpu. These threads read the
time in a loop while with preemption, softirq and IRQs enabled, thus
allowing all the sources of operating system noise during its execution.
The \fIosnoise\fP\(aqs tracer threads take note of the delta between each time
read, along with an interference counter of all sources of interference.
At the end of each period, the \fIosnoise\fP tracer displays a summary of
the results.
.sp
\fBrtla osnoise top\fP collects the periodic summary from the \fIosnoise\fP tracer,
including the counters of the occurrence of the interference source,
displaying the results in a user\-friendly format.
.sp
The tool also allows many configurations of the \fIosnoise\fP tracer and the
collection of the tracer output.
.SH OPTIONS
.sp
\fB\-a\fP, \fB\-\-auto\fP \fIus\fP
.INDENT 0.0
.INDENT 3.5
Set the automatic trace mode. This mode sets some commonly used options
while debugging the system. It is equivalent to use \fB\-s\fP \fIus\fP \fB\-T 1 \-t\fP\&.
.UNINDENT
.UNINDENT
.sp
\fB\-p\fP, \fB\-\-period\fP \fIus\fP
.INDENT 0.0
.INDENT 3.5
Set the \fIosnoise\fP tracer period in microseconds.
.UNINDENT
.UNINDENT
.sp
\fB\-r\fP, \fB\-\-runtime\fP \fIus\fP
.INDENT 0.0
.INDENT 3.5
Set the \fIosnoise\fP tracer runtime in microseconds.
.UNINDENT
.UNINDENT
.sp
\fB\-s\fP, \fB\-\-stop\fP \fIus\fP
.INDENT 0.0
.INDENT 3.5
Stop the trace if a single sample is higher than the argument in microseconds.
If \fB\-T\fP is set, it will also save the trace to the output.
.UNINDENT
.UNINDENT
.sp
\fB\-S\fP, \fB\-\-stop\-total\fP \fIus\fP
.INDENT 0.0
.INDENT 3.5
Stop the trace if the total sample is higher than the argument in microseconds.
If \fB\-T\fP is set, it will also save the trace to the output.
.UNINDENT
.UNINDENT
.sp
\fB\-T\fP, \fB\-\-threshold\fP \fIus\fP
.INDENT 0.0
.INDENT 3.5
Specify the minimum delta between two time reads to be considered noise.
The default threshold is \fI5 us\fP\&.
.UNINDENT
.UNINDENT
.sp
\fB\-q\fP, \fB\-\-quiet\fP
.INDENT 0.0
.INDENT 3.5
Print only a summary at the end of the session.
.UNINDENT
.UNINDENT
.sp
\fB\-c\fP, \fB\-\-cpus\fP \fIcpu\-list\fP
.INDENT 0.0
.INDENT 3.5
Set the osnoise tracer to run the sample threads in the cpu\-list.
.UNINDENT
.UNINDENT
.sp
\fB\-H\fP, \fB\-\-house\-keeping\fP \fIcpu\-list\fP
.INDENT 0.0
.INDENT 3.5
Run rtla control threads only on the given cpu\-list.
.UNINDENT
.UNINDENT
.sp
\fB\-d\fP, \fB\-\-duration\fP \fItime[s|m|h|d]\fP
.INDENT 0.0
.INDENT 3.5
Set the duration of the session.
.UNINDENT
.UNINDENT
.sp
\fB\-D\fP, \fB\-\-debug\fP
.INDENT 0.0
.INDENT 3.5
Print debug info.
.UNINDENT
.UNINDENT
.sp
\fB\-t\fP, \fB\-\-trace\fP[\fI=file\fP]
.INDENT 0.0
.INDENT 3.5
Save the stopped trace to [\fIfile|osnoise_trace.txt\fP].
.UNINDENT
.UNINDENT
.sp
\fB\-e\fP, \fB\-\-event\fP \fIsys:event\fP
.INDENT 0.0
.INDENT 3.5
Enable an event in the trace (\fB\-t\fP) session. The argument can be a specific event, e.g., \fB\-e\fP \fIsched:sched_switch\fP, or all events of a system group, e.g., \fB\-e\fP \fIsched\fP\&. Multiple \fB\-e\fP are allowed. It is only active when \fB\-t\fP or \fB\-a\fP are set.
.UNINDENT
.UNINDENT
.sp
\fB\-\-filter\fP \fI<filter>\fP
.INDENT 0.0
.INDENT 3.5
Filter the previous \fB\-e\fP \fIsys:event\fP event with \fI<filter>\fP\&. For further information about event filtering see \fI\%https://www.kernel.org/doc/html/latest/trace/events.html#event\-filtering\fP\&.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-\-trigger\fP \fI<trigger>\fP
Enable a trace event trigger to the previous \fB\-e\fP \fIsys:event\fP\&.
If the \fIhist:\fP trigger is activated, the output histogram will be automatically saved to a file named \fIsystem_event_hist.txt\fP\&.
For example, the command:
.sp
rtla <command> <mode> \-t \-e osnoise:irq_noise \-\-trigger=\(dqhist:key=desc,duration/1000:sort=desc,duration/1000:vals=hitcount\(dq
.sp
Will automatically save the content of the histogram associated to \fIosnoise:irq_noise\fP event in \fIosnoise_irq_noise_hist.txt\fP\&.
.sp
For further information about event trigger see \fI\%https://www.kernel.org/doc/html/latest/trace/events.html#event\-triggers\fP\&.
.UNINDENT
.sp
\fB\-P\fP, \fB\-\-priority\fP \fIo:prio|r:prio|f:prio|d:runtime:period\fP
.INDENT 0.0
.INDENT 3.5
Set scheduling parameters to the osnoise tracer threads, the format to set the priority are:
.INDENT 0.0
.IP \(bu 2
\fIo:prio\fP \- use SCHED_OTHER with \fIprio\fP;
.IP \(bu 2
\fIr:prio\fP \- use SCHED_RR with \fIprio\fP;
.IP \(bu 2
\fIf:prio\fP \- use SCHED_FIFO with \fIprio\fP;
.IP \(bu 2
\fId:runtime[us|ms|s]:period[us|ms|s]\fP \- use SCHED_DEADLINE with \fIruntime\fP and \fIperiod\fP in nanoseconds.
.UNINDENT
.UNINDENT
.UNINDENT
.sp
\fB\-C\fP, \fB\-\-cgroup\fP[\fI=cgroup\fP]
.INDENT 0.0
.INDENT 3.5
Set a \fIcgroup\fP to the tracer\(aqs threads. If the \fB\-C\fP option is passed without arguments, the tracer\(aqs thread will inherit \fBrtla\fP\(aqs \fIcgroup\fP\&. Otherwise, the threads will be placed on the \fIcgroup\fP passed to the option.
.UNINDENT
.UNINDENT
.sp
\fB\-h\fP, \fB\-\-help\fP
.INDENT 0.0
.INDENT 3.5
Print help menu.
.UNINDENT
.UNINDENT
.SH EXAMPLE
.sp
In the example below, the \fBrtla osnoise top\fP tool is set to run with a
real\-time priority \fIFIFO:1\fP, on CPUs \fI0\-3\fP, for \fI900ms\fP at each period
(\fI1s\fP by default). The reason for reducing the runtime is to avoid starving
the rtla tool. The tool is also set to run for \fIone minute\fP and to display
a summary of the report at the end of the session:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
[root@f34 ~]# rtla osnoise top \-P F:1 \-c 0\-3 \-r 900000 \-d 1M \-q
                                        Operating System Noise
duration:   0 00:01:00 | time is in us
CPU Period       Runtime        Noise  % CPU Aval   Max Noise   Max Single          HW          NMI          IRQ      Softirq       Thread
  0 #59         53100000       304896    99.42580        6978           56         549            0        53111         1590           13
  1 #59         53100000       338339    99.36282        8092           24         399            0        53130         1448           31
  2 #59         53100000       290842    99.45227        6582           39         855            0        53110         1406           12
  3 #59         53100000       204935    99.61405        6251           33         290            0        53156         1460           12
.EE
.UNINDENT
.UNINDENT
.SH SEE ALSO
.sp
\fBrtla\-osnoise\fP(1), \fBrtla\-osnoise\-hist\fP(1)
.sp
Osnoise tracer documentation: <\fI\%https://www.kernel.org/doc/html/latest/trace/osnoise\-tracer.html\fP>
.SH AUTHOR
.sp
Written by Daniel Bristot de Oliveira <\fI\%bristot@kernel.org\fP>
.SH REPORTING BUGS
.sp
Report bugs to <\fI\%linux\-kernel@vger.kernel.org\fP>
and <\fI\%linux\-trace\-devel@vger.kernel.org\fP>
.SH LICENSE
.sp
\fBrtla\fP is Free Software licensed under the GNU GPLv2
.SH COPYING
.sp
Copyright (C) 2021 Red Hat, Inc. Free use of this software is granted under
the terms of the GNU Public License (GPL).
.\" Generated by docutils manpage writer.
.