Documentation/tools/rtla/common_options.txt at v6.19

tjh.dev / kernel
fork
Linux kernel mirror (for testing) git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel os linux
fork
kernel / Documentation / tools / rtla / common_options.txt
at v6.19 129 lines 5.3 kB view raw
wrap content
  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.
Configure Feed

Configure Feed
