[PATCH v2] Documentation: trace: histogram-design: fix bracket, improve wording

[PATCH v2] Documentation: trace: histogram-design: fix bracket, improve wording

[Manuel Ebner]

Add missing ')' and add note about the new way of triggering an event.

CC: Randy Dunlap <rdunlap@infradead.org>
Suggested-by: Steven Rostedt <rostedt@goodmis.org>
Signed-off-by: Manuel Ebner <manuelebnerli@mailbox.org>
---
@ Steven, I added this line, because else the references wouldn't make sense.
References: $wakeup_lat, next_pid

+ ... (which
+could equivalently be written trace(wakeup_latency,$wakeup_lat,next_pid)
 are implemented, the parameters specified to the trace handler must be
 variables.  In this case, $wakeup_lat is obviously a variable, but
 next_pid isn't, since it's just naming a field in the sched_switch
---
 Documentation/trace/histogram-design.rst | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

diff --git a/Documentation/trace/histogram-design.rst b/Documentation/trace/histogram-design.rst
index 41a726cd3..86c83b177 100644
--- a/Documentation/trace/histogram-design.rst
+++ b/Documentation/trace/histogram-design.rst
@@ -25,7 +25,7 @@ tracing_map.c.
 
 If the kernel is compiled with CONFIG_HIST_TRIGGERS_DEBUG set, an
 event file named 'hist_debug' will appear in each event's
-subdirectory.  This file can be read at any time and will display some
+
 of the hist trigger internals described in this document. Specific
 examples and output will be described in test cases below.
 
@@ -916,6 +916,13 @@ means it will be automatically converted into a field variable::
           onmatch(sched.sched_waking).wakeup_latency($wakeup_lat,next_pid)' >>
 	  /sys/kernel/tracing/events/sched/sched_switch/trigger
 
+Note that the above is the old way to trigger a synthetic event, whereas the
+newer way is preferred, which uses the trace() action handler::
+
+  # echo 'hist:keys=next_pid:wakeup_lat=common_timestamp.usecs-$ts0: \
+          onmatch(sched.sched_waking).trace(wakeup_latency,$wakeup_lat,next_pid)' >>
+	  /sys/kernel/tracing/events/sched/sched_switch/trigger
+
 The diagram for the sched_switch event is similar to previous examples
 but shows the additional field_vars[] array for hist_data and shows
 the linkages between the field_vars and the variables and references
-- 
2.54.0

[PATCH v2] Documentation: trace: histogram-design: fix bracket, improve wording

[Manuel Ebner]

Add missing ')' and add note about the new way of triggering an event.

CC: Randy Dunlap <rdunlap@infradead.org>
Suggested-by: Steven Rostedt <rostedt@goodmis.org>
Signed-off-by: Manuel Ebner <manuelebnerli@mailbox.org>
---
I sent the previous mail on accident, sorry.

@ Steven, I added this line to your suggestion because else the references
wouldn't make sense. References: $wakeup_lat, next_pid
Let me know what you think.

+ ... (which
+could equivalently be written trace(wakeup_latency,$wakeup_lat,next_pid)
 are implemented, the parameters specified to the trace handler must be
 variables.  In this case, $wakeup_lat is obviously a variable, but
 next_pid isn't, since it's just naming a field in the sched_switch
---
 Documentation/trace/histogram-design.rst | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

diff --git a/Documentation/trace/histogram-design.rst b/Documentation/trace/histogram-design.rst
index 41a726cd3..c0271463b 100644
--- a/Documentation/trace/histogram-design.rst
+++ b/Documentation/trace/histogram-design.rst
@@ -877,7 +877,7 @@ variables specified in the wakeup_latency() trace action, and use
 them to generate a new wakeup_latency event into the trace stream.
 
 Note that the way the trace handlers such as wakeup_latency() (which
-could equivalently be written trace(wakeup_latency,$wakeup_lat,next_pid)
+could equivalently be written trace(wakeup_latency,$wakeup_lat,next_pid))
 are implemented, the parameters specified to the trace handler must be
 variables.  In this case, $wakeup_lat is obviously a variable, but
 next_pid isn't, since it's just naming a field in the sched_switch
@@ -916,6 +916,13 @@ means it will be automatically converted into a field variable::
           onmatch(sched.sched_waking).wakeup_latency($wakeup_lat,next_pid)' >>
 	  /sys/kernel/tracing/events/sched/sched_switch/trigger
 
+Note that the above is the old way to trigger a synthetic event, whereas the
+newer way is preferred, which uses the trace() action handler::
+
+  # echo 'hist:keys=next_pid:wakeup_lat=common_timestamp.usecs-$ts0: \
+          onmatch(sched.sched_waking).trace(wakeup_latency,$wakeup_lat,next_pid)' >>
+	  /sys/kernel/tracing/events/sched/sched_switch/trigger
+
 The diagram for the sched_switch event is similar to previous examples
 but shows the additional field_vars[] array for hist_data and shows
 the linkages between the field_vars and the variables and references
-- 
2.54.0

Re: [PATCH v2] Documentation: trace: histogram-design: fix bracket, improve wording

[Steven Rostedt]

On Thu,  3 Sep 2026 09:11:05 +0200
Manuel Ebner <manuelebnerli@mailbox.org> wrote:

> Add missing ')' and add note about the new way of triggering an event.
> 
> CC: Randy Dunlap <rdunlap@infradead.org>
> Suggested-by: Steven Rostedt <rostedt@goodmis.org>
> Signed-off-by: Manuel Ebner <manuelebnerli@mailbox.org>
> ---
> I sent the previous mail on accident, sorry.
> 
> @ Steven, I added this line to your suggestion because else the references
> wouldn't make sense. References: $wakeup_lat, next_pid
> Let me know what you think.

It still looks fine without it. Here's the statement in full without the line:

   Note that the way the trace handlers such as wakeup_latency() are
   implemented, the parameters specified to the trace handler must be
   variables.  In this case, $wakeup_lat is obviously a variable, but
   next_pid isn't, since it's just naming a field in the sched_switch trace
   event.  Since this is something that almost every trace() and save()
   action does, a special shortcut is implemented to allow field names to
   be used directly in those cases.  How it works is that under the covers,
   a temporary variable is created for the named field, and this variable
   is what is actually passed to the trace handler.  In the code and
   documentation, this type of variable is called a 'field variable'.

Perhaps it may look better if we move the text around a bit:

  The onmatch() action below basically says that whenever we have a
  sched_switch event, if we have a matching sched_waking event, in this
  case if we have a pid in the sched_waking histogram that matches the
  next_pid field on this sched_switch event, we retrieve the
  variables specified in the wakeup_latency() trace action, and use
  them to generate a new wakeup_latency event into the trace stream.

  First, we define the wakeup_latency synthetic event::

    # echo 'wakeup_latency u64 lat; pid_t pid' >> synthetic_events

  Next, the sched_waking hist trigger as before::

    # echo 'hist:keys=pid:ts0=common_timestamp.usecs' >>
            events/sched/sched_waking/trigger

  Finally, we create a hist trigger on the sched_switch event that
  generates a wakeup_latency() trace event.  In this case we pass
  next_pid into the wakeup_latency synthetic event invocation, which
  means it will be automatically converted into a field variable::

    # echo 'hist:keys=next_pid:wakeup_lat=common_timestamp.usecs-$ts0: \
            onmatch(sched.sched_waking).trace(wakeup_latency,$wakeup_lat,next_pid)' >>
	    /sys/kernel/tracing/events/sched/sched_switch/trigger

  Note, the above can also be written where wakeup_latency() is the
  action handler instead of trace()::

    # echo 'hist:keys=next_pid:wakeup_lat=common_timestamp.usecs-$ts0: \
            onmatch(sched.sched_waking).wakeup_latency($wakeup_lat,next_pid)' >>
            /sys/kernel/tracing/events/sched/sched_switch/trigger

  The diagram above illustrates the new elements described in the context
  of the sched_switch histogram using the onmatch() handler and the trace()
  action.

  Note that the way the trace handlers such as wakeup_latency() are
  implemented, the parameters specified to the trace handler must be
  variables.  In this case, $wakeup_lat is obviously a variable, but
  next_pid isn't, since it's just naming a field in the sched_switch trace
  event.  Since this is something that almost every trace() and save()
  action does, a special shortcut is implemented to allow field names to
  be used directly in those cases.  How it works is that under the covers,
  a temporary variable is created for the named field, and this variable
  is what is actually passed to the trace handler.  In the code and
  documentation, this type of variable is called a 'field variable'.

  Fields on other trace event's histograms can be used as well.  In that
  case we have to generate a new histogram and an unfortunately named
  'synthetic_field' (the use of synthetic here has nothing to do with
  synthetic events) and use that special histogram field as a variable.


-- Steve