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@xxxxxxxxxxx> wrote:

> Add missing ')' and add note about the new way of triggering an event.
> 
> CC: Randy Dunlap <rdunlap@xxxxxxxxxxxxx>
> Suggested-by: Steven Rostedt <rostedt@xxxxxxxxxxx>
> Signed-off-by: Manuel Ebner <manuelebnerli@xxxxxxxxxxx>
> ---
> 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