RTLA-OSNOISE-HIST(1)

💖 RTLA-OSNOISE-HIST(1) 💖

okay so bestie, welcome to the manual page for rtla-osnoise-hist — it lives in the General Commands Manual section of your friendly neighbourhood man setup, and it is lowkey one of the most useful pages in the whole rtla girlie universe. let's get into it 🫶

---

🌸 NAME 🌸

rtla-osnoise-hist — Display a histogram of the osnoise tracer samples ✨

---

🦋 SYNOPSIS 🦋

rtla osnoise hist [OPTIONS]

---

✨ DESCRIPTION ✨

So rtla osnoise</p> is basically the ~interface~ to the osnoise tracer, right? And the osnoise tracer does this iconic thing where it dispatches a kernel thread per-cpu. Those threads just sit there reading the time in a loop, but with preemption, softirq and IRQs enabled — which is the whole point, because that lets every single source of operating system noise sneak in while they're executing. very main character of them 💅

The osnoise tracer's threads keep notes on the delta between each time read, plus an interference counter of all the sources of interference. Then, at the end of every period, the osnoise tracer shows you a lil summary of the results. cute, right?

Now rtla osnoise hist</p> — this tool — collects every single osnoise:sample_threshold occurrence into a histogram, and displays the results in a user-friendly way ✨. And because she's generous, the tool also lets you configure the osnoise tracer in a whole bunch of ways and collect the tracer output. obsessed.

---

💅 OPTIONS 💅

• -a, --auto us — Sets the automatic trace mode, bestie. This mode sets some commonly used options while you're out here debugging the system. It is equivalent to using -s us -T 1 -t.
• -p, --period us — Set the osnoise tracer period in microseconds.
• -r, --runtime us — Set the osnoise tracer runtime in microseconds.
• -s, --stop us — Stop the trace if a single sample is higher than the argument, in microseconds. If -T is set, it will also save the trace to the output.
• -S, --stop-total us — Stop the trace if the total sample is higher than the argument, in microseconds. If -T is set, it will also save the trace to the output.
• -T, --threshold us — Specify the minimum delta between two time reads to be considered noise. The default threshold is 5 us. 📏
• -t, --trace [file] — Save the stopped trace to [file|osnoise_trace.txt].
• -b, --bucket-size N — Set the histogram bucket size (default 1).
• -E, --entries N — Set the number of entries of the histogram (default 256).
• --no-header — Do not print header. 🙈
• --no-summary — Do not print summary.
• --no-index — Do not print index.
• --with-zeros — Print zero only entries.
• -c, --cpus cpu-list — Set the osnoise hist tracer to run the sample threads in the cpu-list.

By default, the osnoise hist tracer runs the sample threads on all CPUs.

• -H, --house-keeping cpu-list — Run rtla control threads only on the given cpu-list.

If omitted, rtla will attempt to auto-migrate its main thread to any CPU that is not running any workload threads. 🧚

• -d, --duration time[s|m|h|d] — Set the duration of the session. ⏰
• -D, --debug — Print debug info.
• -e, --event sys:event — Enable an event in the -t session. The argument can be a specific event, e.g., -e sched:sched_switch, or all events of a system group, e.g., -e sched. Multiple -e are allowed. It is only active when -t or -a are set. 👑
• --filter <filter> — Filter the previous -e sys:event event with <filter>. For further information about event filtering see https://www.kernel.org/doc/html/latest/trace/events.html#event-filtering .
• --trigger <trigger> — Enable a trace event trigger to the previous -e sys:event. If the hist: trigger is activated, the output histogram will be automatically saved to a file named system_event_hist.txt. For example, the command:

rtla <command> <mode> -t -e osnoise:irq_noise
--trigger="hist:key=desc,duration/1000:sort=desc,duration/1000:vals=hitcount"

Will automatically save the content of the histogram associated to osnoise:irq_noise event in osnoise_irq_noise_hist.txt.

For further information about event trigger see https://www.kernel.org/doc/html/latest/trace/events.html#event-triggers .

• -P, --priority o:prio|r:prio|f:prio|d:runtime:period — Set scheduling parameters to the osnoise hist tracer threads. The format to set the priority are:
  • o:prio — use SCHED_OTHER with prio;
  • r:prio — use SCHED_RR with prio;
  • f:prio — use SCHED_FIFO with prio;
  • d:runtime[us|ms|s]:period[us|ms|s] — use SCHED_DEADLINE with runtime and period in nanoseconds.

If not set, tracer threads keep their default priority. For rtla user threads, it is set to SCHED_FIFO with priority 95. For kernel threads, see osnoise and timerlat tracer documentation for the running kernel version.

• -C, --cgroup [cgroup] — Set a cgroup to the tracer's threads. If the -C option is passed without arguments, the tracer's thread will inherit rtla's cgroup. Otherwise, the threads will be placed on the cgroup passed to the option.

If not set, the behavior differs between workload types. User workloads created by rtla will inherit rtla's cgroup. Kernel workloads are assigned the root cgroup.

• --warm-up s — After starting the workload, let it run for s seconds before starting collecting the data, allowing the system to warm-up. Statistical data generated during warm-up is discarded. 🔥
• --trace-buffer-size kB — Set the per-cpu trace buffer size in kB for the tracing output.

If not set, the default tracefs buffer size is used.

• --on-threshold action — Defines an action to be executed when tracing is stopped on a latency threshold specified by -a/--auto, -s/--stop, or -S/--stop-total.

Multiple --on-threshold actions may be specified, and they will be executed in the order they are provided. If any action fails, subsequent actions in the list will not be executed. 💀

Supported actions are:

• trace[,file=<filename>]

Saves trace output, optionally taking a filename. Alternative to -t/--trace. Note that unlike -t/--trace, specifying this multiple times will result in the trace being saved multiple times.

• signal,num=<sig>,pid=<pid>

Sends signal to process. "parent" might be specified in place of pid to target the parent process of rtla.

• shell,command=<command>

Execute shell command.

• continue

Continue tracing after actions are executed instead of stopping.

Example:

$ rtla osnoise hist -s 20 --on-threshold trace --on-threshold
shell,command="grep ipi_send osnoise_trace.txt" --on-threshold
signal,num=2,pid=parent

This will save a trace with the default filename "osnoise_trace.txt", print its lines that contain the text "ipi_send" on standard output, and send signal 2 (SIGINT) to the parent process.

Performance Considerations:

Due to implementational limitations, actions might be delayed up to one second after tracing is stopped. 😭

• --on-end action — Defines an action to be executed at the end of tracing.

Multiple --on-end actions can be specified, and they will be executed in the order they are provided. If any action fails, subsequent actions in the list will not be executed.

See the documentation for --on-threshold for the list of supported actions, with the exception that continue has no effect.

Example:

$ rtla osnoise hist -d 5s --on-end trace

This runs rtla with the default options, and saves trace output at the end. 🎀

• -h, --help — Print help menu.

---

🌈 EXAMPLE 🌈

In the example below, osnoise tracer threads are set to run with real-time priority FIFO:1, on CPUs 0-11, for 900ms at each period (1s by default). The reason for reducing the runtime is to avoid starving the rtla tool. The tool is also set to run for one minute. The output histogram is set to group outputs in buckets of 10us and 25 entries:

[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

---

🫶 SEE ALSO 🫶

• rtla-osnoise(1), rtla-osnoise-top(1)
• Osnoise tracer https://docs.kernel.org/trace/osnoise-tracer.html

---

👑 AUTHOR 👑

Written by Daniel Bristot de Oliveira < bristot@kernel.org > 💖

---

😭 SIGINT BEHAVIOR 😭

On the first SIGINT, RTLA exits after collecting all outstanding samples up to the point of receiving the signal.

When receiving more than one SIGINT, RTLA discards any outstanding samples, and exits while displaying only samples that have already been processed. 💀

If SIGINT is received during RTLA cleanup, RTLA exits immediately via the default signal handler.

Note: For the purpose of SIGINT behavior, the expiry of duration specified via the -d/--duration option is treated as equivalent to receiving a SIGINT. For example, a SIGINT received after duration expired but samples have not been processed yet will drop any outstanding samples.

Also note that when using the timerlat tool in BPF mode, samples are processed in-kernel; RTLA only copies them out to display them to the user. A second SIGINT does not affect in-kernel sample aggregation. 🧚

---

⭐ EXIT STATUS ⭐

• 0 — Passed: the test did not hit the stop tracing condition ✅
• 1 — Error: invalid argument 🙈
• 2 — Failed: the test hit the stop tracing condition 💀
• 129 — Help: either user requested help or incorrect option was specified 🎀

---

🐛 REPORTING BUGS 🐛

Report bugs to < linux-kernel@vger.kernel.org > and < linux-trace-devel@vger.kernel.org >

📜 LICENSE 📜

okay so the legal tea, bestie, but make it cute:

rtla is Free Software, and it's licensed under the GNU GPLv2. that's it, that's the whole vibe. free as in freedom, fr fr. 💖

---

©️ COPYING ©️

here's the receipts:

• Copyright (C) 2021 Red Hat, Inc.
• Free use of this software is granted under the terms of the GNU Public License (GPL).

so yeah — you can use it, share it, remix it, all of it, as long as you play by the GPL's rules. no gatekeeping here, we're all in the group chat together 🫶✨

ngl, always read the actual license text if you're doing anything serious with it — this is the summary vibe, not the legal document 💅

---

and that's a wrap on rtla-osnoise-hist(1) bestie!! 🎀 you made it all the way to the bottom of the page, which is honestly main character energy 👑 this footer is giving RTLA-OSNOISE-HIST(1) from the rtla package, and it's dated May 2022 🦋 so go forth, trace those OS noise events, and slay ✨💜