[PATCH] Documentation/rtla: Document SIGINT behavior

[PATCH] Documentation/rtla: Document SIGINT behavior

[Tomas Glozar]

The behavior of RTLA on receiving SIGINT is currently undocumented.

Describe it in RTLA's common appendix that appears in man pages for all
RTLA tools to avoid confusion.

Suggested-by: Attila Fazekas <afazekas@redhat.com>
Signed-off-by: Tomas Glozar <tglozar@redhat.com>
---

Note: There was a bug in SIGINT behavior, fixed in upcoming commit [1].

[1] https://lore.kernel.org/linux-trace-kernel/20260310160725.144443-1-tglozar@redhat.com/

 Documentation/tools/rtla/common_appendix.txt | 21 ++++++++++++++++++++
 1 file changed, 21 insertions(+)

diff --git a/Documentation/tools/rtla/common_appendix.txt b/Documentation/tools/rtla/common_appendix.txt
index 53cae7537537..8c90a02588e7 100644
--- a/Documentation/tools/rtla/common_appendix.txt
+++ b/Documentation/tools/rtla/common_appendix.txt
@@ -1,5 +1,26 @@
 .. SPDX-License-Identifier: GPL-2.0
 
+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
 ===========
 
-- 
2.53.0

Re: [PATCH] Documentation/rtla: Document SIGINT behavior

[Steven Rostedt]

On Tue, 24 Mar 2026 13:32:29 +0100
Tomas Glozar <tglozar@redhat.com> wrote:

> The behavior of RTLA on receiving SIGINT is currently undocumented.
> 
> Describe it in RTLA's common appendix that appears in man pages for all
> RTLA tools to avoid confusion.
> 
> Suggested-by: Attila Fazekas <afazekas@redhat.com>
> Signed-off-by: Tomas Glozar <tglozar@redhat.com>
> ---
> 
> Note: There was a bug in SIGINT behavior, fixed in upcoming commit [1].
> 
> [1] https://lore.kernel.org/linux-trace-kernel/20260310160725.144443-1-tglozar@redhat.com/

Hmm, this may be interesting enough to add to the change log itself.

> 
>  Documentation/tools/rtla/common_appendix.txt | 21 ++++++++++++++++++++
>  1 file changed, 21 insertions(+)
> 
> diff --git a/Documentation/tools/rtla/common_appendix.txt b/Documentation/tools/rtla/common_appendix.txt
> index 53cae7537537..8c90a02588e7 100644
> --- a/Documentation/tools/rtla/common_appendix.txt
> +++ b/Documentation/tools/rtla/common_appendix.txt
> @@ -1,5 +1,26 @@
>  .. SPDX-License-Identifier: GPL-2.0
>  
> +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.

But does it affect the user space side of reading that information?

> +
>  EXIT STATUS
>  ===========
>  

Other than that ... LGTM,

Reviewed-by: Steven Rostedt (Google) <rostedt@goodmis.org>

-- Steve

Re: [PATCH] Documentation/rtla: Document SIGINT behavior

[Tomas Glozar]

út 24. 3. 2026 v 16:22 odesílatel Steven Rostedt <rostedt@goodmis.org> napsal:
> >
> > Note: There was a bug in SIGINT behavior, fixed in upcoming commit [1].
> >
> > [1] https://lore.kernel.org/linux-trace-kernel/20260310160725.144443-1-tglozar@redhat.com/
>
> Hmm, this may be interesting enough to add to the change log itself.
>

I thought about that, but it felt a bit redundant, since the other
patch will also be a part of the commit history. I see that some
documentation patches do mention the commit that introduced the
change. Here, it is only the SIGINT during cleanup part that got
changed (segfault/undefined behavior -> default handler) so it might
make sense.

> > +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.
>
> But does it affect the user space side of reading that information?
>

No, it shouldn't, the pattern for both timerlat-top and timerlat-hist is:

while(stop_tracing) {
   timerlat_bpf_wait(...);
   timerlat_{top,hist}_pull_bpf_data(...);
   ...
}

The BPF program is detached after this, so all data gathered up to the
point of the SIGINT will be displayed. A second SIGINT does not affect
it, since it calls tracefs_iterate_stop() which stops
tracefs_iterate_raw_events(). It does not stop
timelat_{top,hist}_pull_bpf_data() - which is aggregated anyway, so
stopping it would just leave a part of the histogram/top empty.

> > +
> >  EXIT STATUS
> >  ===========
> >
>
> Other than that ... LGTM,
>
> Reviewed-by: Steven Rostedt (Google) <rostedt@goodmis.org>
>
> -- Steve
>

Thanks for looking at this.


Tomas