Commit 70165c78 authored by Tomas Glozar's avatar Tomas Glozar Committed by Steven Rostedt (Google)
Browse files

Documentation/rtla: Add actions feature 

Document both --on-threshold and --on-end, with examples.

Cc: John Kacur <jkacur@redhat.com>
Cc: Luis Goncalves <lgoncalv@redhat.com>
Cc: Arnaldo Carvalho de Melo <acme@kernel.org>
Cc: Chang Yin <cyin@redhat.com>
Cc: Costa Shulyupin <costa.shul@redhat.com>
Cc: Crystal Wood <crwood@redhat.com>
Cc: Gabriele Monaco <gmonaco@redhat.com>
Link: https://lore.kernel.org/20250626123405.1496931-10-tglozar@redhat.com


Signed-off-by: default avatarTomas Glozar <tglozar@redhat.com>
Signed-off-by: default avatarSteven Rostedt (Google) <rostedt@goodmis.org>
parent 04f83716

Documentation/tools/rtla/common_timerlat_options.rst

+64 −0
Original line number Diff line number Diff line
@@ -55,3 +55,67 @@ 
        Set timerlat to run without workload, waiting for the user to dispatch a per-cpu

        task that waits for a new period on the tracing/osnoise/per_cpu/cpu$ID/timerlat_fd.

        See linux/tools/rtla/sample/timerlat_load.py for an example of user-load code.



**--on-threshold** *action*



        Defines an action to be executed when tracing is stopped on a latency threshold

        specified by **-i/--irq** or **-T/--thread**.



        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 nlike -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 timerlat -T 20 --on-threshold trace

        --on-threshold shell,command="grep ipi_send timerlat_trace.txt"

        --on-threshold signal,num=2,pid=parent



        This will save a trace with the default filename "timerlat_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:



        For time-sensitive actions, it is recommended to run **rtla timerlat** with BPF

        support and RT priority. Note that due to implementational limitations, actions

        might be delayed up to one second after tracing is stopped if BPF mode is not

        available or disabled.



**--on-end** *action*



        Defines an action to be executed at the end of **rtla timerlat** 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 timerlat -d 5s --on-end trace



        This runs rtla timerlat with default options and save trace output at the end.