| 1 |
**-c**, **--cpus** *cpu-list* |
| 2 |
|
| 3 |
Set the |tool| tracer to run the sample threads in the cpu-list. |
| 4 |
|
| 5 |
By default, the |tool| tracer runs the sample threads on all CPUs. |
| 6 |
|
| 7 |
**-H**, **--house-keeping** *cpu-list* |
| 8 |
|
| 9 |
Run rtla control threads only on the given cpu-list. |
| 10 |
|
| 11 |
If omitted, rtla will attempt to auto-migrate its main thread to any CPU that is not running any workload threads. |
| 12 |
|
| 13 |
**-d**, **--duration** *time[s|m|h|d]* |
| 14 |
|
| 15 |
Set the duration of the session. |
| 16 |
|
| 17 |
**-D**, **--debug** |
| 18 |
|
| 19 |
Print debug info. |
| 20 |
|
| 21 |
**-e**, **--event** *sys:event* |
| 22 |
|
| 23 |
Enable an event in the trace (**-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. |
| 24 |
|
| 25 |
**--filter** *<filter>* |
| 26 |
|
| 27 |
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. |
| 28 |
|
| 29 |
**--trigger** *<trigger>* |
| 30 |
Enable a trace event trigger to the previous **-e** *sys:event*. |
| 31 |
If the *hist:* trigger is activated, the output histogram will be automatically saved to a file named *system_event_hist.txt*. |
| 32 |
For example, the command: |
| 33 |
|
| 34 |
rtla <command> <mode> -t -e osnoise:irq_noise --trigger="hist:key=desc,duration/1000:sort=desc,duration/1000:vals=hitcount" |
| 35 |
|
| 36 |
Will automatically save the content of the histogram associated to *osnoise:irq_noise* event in *osnoise_irq_noise_hist.txt*. |
| 37 |
|
| 38 |
For further information about event trigger see https://www.kernel.org/doc/html/latest/trace/events.html#event-triggers. |
| 39 |
|
| 40 |
**-P**, **--priority** *o:prio|r:prio|f:prio|d:runtime:period* |
| 41 |
|
| 42 |
Set scheduling parameters to the |tool| tracer threads, the format to set the priority are: |
| 43 |
|
| 44 |
- *o:prio* - use SCHED_OTHER with *prio*; |
| 45 |
- *r:prio* - use SCHED_RR with *prio*; |
| 46 |
- *f:prio* - use SCHED_FIFO with *prio*; |
| 47 |
- *d:runtime[us|ms|s]:period[us|ms|s]* - use SCHED_DEADLINE with *runtime* and *period* in nanoseconds. |
| 48 |
|
| 49 |
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. |
| 50 |
|
| 51 |
**-C**, **--cgroup** \[*cgroup*] |
| 52 |
|
| 53 |
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. |
| 54 |
|
| 55 |
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. |
| 56 |
|
| 57 |
**--warm-up** *s* |
| 58 |
|
| 59 |
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. |
| 60 |
|
| 61 |
**--trace-buffer-size** *kB* |
| 62 |
Set the per-cpu trace buffer size in kB for the tracing output. |
| 63 |
|
| 64 |
If not set, the default tracefs buffer size is used. |
| 65 |
|
| 66 |
**--on-threshold** *action* |
| 67 |
|
| 68 |
Defines an action to be executed when tracing is stopped on a latency threshold |
| 69 |
specified by |threshold|. |
| 70 |
|
| 71 |
Multiple --on-threshold actions may be specified, and they will be executed in |
| 72 |
the order they are provided. If any action fails, subsequent actions in the list |
| 73 |
will not be executed. |
| 74 |
|
| 75 |
Supported actions are: |
| 76 |
|
| 77 |
- *trace[,file=<filename>]* |
| 78 |
|
| 79 |
Saves trace output, optionally taking a filename. Alternative to -t/--trace. |
| 80 |
Note that unlike -t/--trace, specifying this multiple times will result in |
| 81 |
the trace being saved multiple times. |
| 82 |
|
| 83 |
- *signal,num=<sig>,pid=<pid>* |
| 84 |
|
| 85 |
Sends signal to process. "parent" might be specified in place of pid to target |
| 86 |
the parent process of rtla. |
| 87 |
|
| 88 |
- *shell,command=<command>* |
| 89 |
|
| 90 |
Execute shell command. |
| 91 |
|
| 92 |
- *continue* |
| 93 |
|
| 94 |
Continue tracing after actions are executed instead of stopping. |
| 95 |
|
| 96 |
Example: |
| 97 |
|
| 98 |
$ rtla |tool| |thresharg| 20 --on-threshold trace |
| 99 |
--on-threshold shell,command="grep ipi_send |tracer|\_trace.txt" |
| 100 |
--on-threshold signal,num=2,pid=parent |
| 101 |
|
| 102 |
This will save a trace with the default filename "|tracer|\_trace.txt", print its |
| 103 |
lines that contain the text "ipi_send" on standard output, and send signal 2 |
| 104 |
(SIGINT) to the parent process. |
| 105 |
|
| 106 |
Performance Considerations: |
| 107 |
|
| 108 |
|actionsperf| |
| 109 |
|
| 110 |
**--on-end** *action* |
| 111 |
|
| 112 |
Defines an action to be executed at the end of tracing. |
| 113 |
|
| 114 |
Multiple --on-end actions can be specified, and they will be executed in the order |
| 115 |
they are provided. If any action fails, subsequent actions in the list will not be |
| 116 |
executed. |
| 117 |
|
| 118 |
See the documentation for **--on-threshold** for the list of supported actions, with |
| 119 |
the exception that *continue* has no effect. |
| 120 |
|
| 121 |
Example: |
| 122 |
|
| 123 |
$ rtla |tool| -d 5s --on-end trace |
| 124 |
|
| 125 |
This runs rtla with the default options, and saves trace output at the end. |
| 126 |
|
| 127 |
**-h**, **--help** |
| 128 |
|
| 129 |
Print help menu. |