.\" 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-HIST" 1 "" ""
.SH NAME
rtla-osnoise-hist \- Display a histogram of the osnoise tracer samples
.SH SYNOPSIS
.sp
\fBrtla osnoise hist\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
The \fBrtla osnoise hist\fP tool collects all \fBosnoise:sample_threshold\fP
occurrence in a histogram, displaying the results in a user\-friendly way.
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\-b\fP, \fB\-\-bucket\-size\fP \fIN\fP
.INDENT 0.0
.INDENT 3.5
Set the histogram bucket size (default \fI1\fP).
.UNINDENT
.UNINDENT
.sp
\fB\-E\fP, \fB\-\-entries\fP \fIN\fP
.INDENT 0.0
.INDENT 3.5
Set the number of entries of the histogram (default 256).
.UNINDENT
.UNINDENT
.sp
\fB\-\-no\-header\fP
.INDENT 0.0
.INDENT 3.5
Do not print header.
.UNINDENT
.UNINDENT
.sp
\fB\-\-no\-summary\fP
.INDENT 0.0
.INDENT 3.5
Do not print summary.
.UNINDENT
.UNINDENT
.sp
\fB\-\-no\-index\fP
.INDENT 0.0
.INDENT 3.5
Do not print index.
.UNINDENT
.UNINDENT
.sp
\fB\-\-with\-zeros\fP
.INDENT 0.0
.INDENT 3.5
Print zero only entries.
.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, \fIosnoise\fP tracer threads are set to run with real\-time
priority \fIFIFO:1\fP, on CPUs \fI0\-11\fP, for \fI900ms\fP at each period (\fI1s\fP by
default). The reason for reducing the runtime is to avoid starving the
\fBrtla\fP tool. The tool is also set to run for \fIone minute\fP\&. The output
histogram is set to group outputs in buckets of \fI10us\fP and \fI25\fP entries:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
[root@f34 ~/]# rtla osnoise hist \-P F:1 \-c 0\-11 \-r 900000 \-d 1M \-b 10 \-E 25
# RTLA osnoise histogram
# Time unit is microseconds (us)
# Duration:   0 00:01:00
Index   CPU\-000   CPU\-001   CPU\-002   CPU\-003   CPU\-004   CPU\-005   CPU\-006   CPU\-007   CPU\-008   CPU\-009   CPU\-010   CPU\-011
0         42982     46287     51779     53740     52024     44817     49898     36500     50408     50128     49523     52377
10        12224      8356      2912       878      2667     10155      4573     18894      4214      4836      5708      2413
20            8         5        12         2        13        24        20        41        29        53        39        39
30            1         1         0         0        10         3         6        19        15        31        30        38
40            0         0         0         0         0         4         2         7         2         3         8        11
50            0         0         0         0         0         0         0         0         0         1         1         2
over:         0         0         0         0         0         0         0         0         0         0         0         0
count:    55215     54649     54703     54620     54714     55003     54499     55461     54668     55052     55309     54880
min:          0         0         0         0         0         0         0         0         0         0         0         0
avg:          0         0         0         0         0         0         0         0         0         0         0         0
max:         30        30        20        20        30        40        40        40        40        50        50        50
.EE
.UNINDENT
.UNINDENT
.SH SEE ALSO
.sp
\fBrtla\-osnoise\fP(1), \fBrtla\-osnoise\-top\fP(1)
.sp
\fIosnoise\fP 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.
.