[PATCH] Documentation/ftrace: Correct wording on trace_options sharing

[PATCH] Documentation/ftrace: Correct wording on trace_options sharing

[Dmitry Safonov]

I'm writing just another net selftest, where I'm planning to check
tcp-ao tracepoints. As I want the test to clean up after itself and
affect other possible tests as little as possible, I'm creating an
ftrace instance with event filters. In order to simplify, going to
disable most of trace_options I don't need. And the current wording
made me think it's not possible to set per-instance trace_options.
And trying that in practice contradicted the documentation:

> # echo 1 > events/signal/enable
> # cd -
> /root/ksft-ftrace-4Py39Z/instances/ksft
> # echo 1 > events/signal/enable
> # cat trace
> # tracer: nop
> #
> # entries-in-buffer/entries-written: 6/6   #P:2
> #
> #           TASK-PID     CPU#     TIMESTAMP  FUNCTION
> #              | |         |         |         |
>              cat-7568    [000]  491748.118710: signal_generate: sig=17 errno=0 code=1 comm=bash pid=6189 grp=1 res=0
>             bash-6189    [001]  491748.119003: signal_deliver: sig=17 errno=0 code=1 sa_handler=55c728d3bce0 sa_flags=14000000
> # cd -
> /root/ksft-ftrace-4Py39Z/instances/ppp
> # cat trace
> # tracer: nop
> #
> JZÊ<¿type: 154
> f>ï>¿type: 154
> -¸ó>¿type: 153
> vW.A?¿type: 154

It seems that since commit 16270145ce6b ("tracing: Add trace options for
core options to instances") it is possible to set per-instance
trace_options, with an exception to three of them.

Document the current state of affairs.

Signed-off-by: Dmitry Safonov <dima@arista.com>
---
 Documentation/trace/ftrace.rst | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/trace/ftrace.rst b/Documentation/trace/ftrace.rst
index 7e7b8ec17934..c79a6bcef3c9 100644
--- a/Documentation/trace/ftrace.rst
+++ b/Documentation/trace/ftrace.rst
@@ -3603,9 +3603,9 @@ The files in the new directory work just like the files with the
 same name in the tracing directory except the buffer that is used
 is a separate and new buffer. The files affect that buffer but do not
 affect the main buffer with the exception of trace_options. Currently,
-the trace_options affect all instances and the top level buffer
-the same, but this may change in future releases. That is, options
-may become specific to the instance they reside in.
+most of the options are specific to the instance they reside in, but
+trace_printk, printk-msg-only and record-cmd are affecting all instances
+and the top level buffer, but this may change in future releases.
 
 Notice that none of the function tracer files are there, nor is
 current_tracer and available_tracers. This is because the buffers

---
base-commit: b401b621758e46812da61fa58a67c3fd8d91de0d
change-id: 20240220-ftrace-options-docs-81ecf05d07e4

Best regards,
-- 
Dmitry Safonov <dima@arista.com>

Re: [PATCH] Documentation/ftrace: Correct wording on trace_options sharing

[Dmitry Safonov]

On 2/20/24 21:00, Dmitry Safonov wrote:
[..]
> diff --git a/Documentation/trace/ftrace.rst b/Documentation/trace/ftrace.rst
> index 7e7b8ec17934..c79a6bcef3c9 100644
> --- a/Documentation/trace/ftrace.rst
> +++ b/Documentation/trace/ftrace.rst
> @@ -3603,9 +3603,9 @@ The files in the new directory work just like the files with the
>  same name in the tracing directory except the buffer that is used
>  is a separate and new buffer. The files affect that buffer but do not
>  affect the main buffer with the exception of trace_options. Currently,
> -the trace_options affect all instances and the top level buffer
> -the same, but this may change in future releases. That is, options
> -may become specific to the instance they reside in.
> +most of the options are specific to the instance they reside in, but
> +trace_printk, printk-msg-only and record-cmd are affecting all instances
> +and the top level buffer, but this may change in future releases.

Actually, it seems that at least on -next these 3 are not shared as
well? (if my tests aren't misbehaving)

So, just remove the part about trace_options exception?

Thanks,
             Dmitry

Re: [PATCH] Documentation/ftrace: Correct wording on trace_options sharing

[Steven Rostedt]

On Wed, 21 Feb 2024 01:59:53 +0000
Dmitry Safonov <dima@arista.com> wrote:

> On 2/20/24 21:00, Dmitry Safonov wrote:
> [..]
> > diff --git a/Documentation/trace/ftrace.rst b/Documentation/trace/ftrace.rst
> > index 7e7b8ec17934..c79a6bcef3c9 100644
> > --- a/Documentation/trace/ftrace.rst
> > +++ b/Documentation/trace/ftrace.rst
> > @@ -3603,9 +3603,9 @@ The files in the new directory work just like the files with the
> >  same name in the tracing directory except the buffer that is used
> >  is a separate and new buffer. The files affect that buffer but do not
> >  affect the main buffer with the exception of trace_options. Currently,
> > -the trace_options affect all instances and the top level buffer
> > -the same, but this may change in future releases. That is, options
> > -may become specific to the instance they reside in.
> > +most of the options are specific to the instance they reside in, but
> > +trace_printk, printk-msg-only and record-cmd are affecting all instances
> > +and the top level buffer, but this may change in future releases.  
> 
> Actually, it seems that at least on -next these 3 are not shared as
> well? (if my tests aren't misbehaving)
> 
> So, just remove the part about trace_options exception?
>

In reality, if we want to be specific. It should state that all options
listed in the instance options directory are unique to the instance. If an
option only exists in the top directory, then it is global or for a tracer
that can only be used in the top directory.

-- Steve