Documentation/trace: Add clarification how histogram onmatch works
Subsystems (2)
PATCH 1/1 Documentation/trace: Add clarification how histogram onmatch works
The current trace documentation, the section describing histogram's "onmatch" is not straightforward enough about how this action is applied. It is not clear what criteria are used to "match" both events. A short note is added, describing what exactly is compared in order to match the events.
--- Documentation/trace/histogram.txt | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-)
Documentation/trace/histogram.txt +7 -4
@@ -1863,7 +1863,10 @@ hist trigger specification. The 'matching.event' specification is simply the fully qualified event name of the event that matches the target event for the - onmatch() functionality, in the form 'system.event_name'. + onmatch() functionality, in the form 'system.event_name'. Histogram + keys of both events are compared to find if events match. In case + multiple histogram keys are used, they all must match in the specified + order. Finally, the number and type of variables/fields in the 'param list' must match the number and types of the fields in the
@@ -1920,9 +1923,9 @@ hist trigger specification. /sys/kernel/debug/tracing/events/sched/sched_waking/trigger Then, when the corresponding thread is actually scheduled onto the - CPU by a sched_switch event, calculate the latency and use that - along with another variable and an event field to generate a - wakeup_latency synthetic event: + CPU by a sched_switch event (saved_pid matches next_pid), calculate + the latency and use that along with another variable and an event field + to generate a wakeup_latency synthetic event: # echo 'hist:keys=next_pid:wakeup_lat=common_timestamp.usecs-$ts0:\ onmatch(sched.sched_waking).wakeup_latency($wakeup_lat,\
Signature · 1 line
2.20.1
Steven Rostedt
maintainerQuoted 4 lines · On Fri, 3 May 2019 17:35:37 +0300 Tzvetomir Stoyanov <[email protected]>…
The current trace documentation, the section describing histogram's "onmatch" is not straightforward enough about how this action is applied. It is not clear what criteria are used to "match" both events. A short note is added, describing what exactly is compared in order to match the events.
Hi Tzvetomir,
Thanks for sending this. Some minor tweaks below.
Quoted 11 lines
Signed-off-by Tzvetomir Stoyanov <[email protected]>--- Documentation/trace/histogram.txt | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-)Documentation/trace/histogram.txt +0
-0
Documentation/trace/histogram.txt hist trigger specification. · line 1869
Quoted 8 lines
Documentation/trace/histogram.txt +4
-1@@ -1863,7 +1863,10 @@ hist trigger specification. The 'matching.event' specification is simply the fully qualified event name of the event that matches the target event for the - onmatch() functionality, in the form 'system.event_name'. + onmatch() functionality, in the form 'system.event_name'. Histogram + keys of both events are compared to find if events match. In case + multiple histogram keys are used, they all must match in the specified + order.
I would reword that to be:
In the case that multiple histogram keys are used, both events must have the same number of keys, and the keys must match in the same order.
Documentation/trace/histogram.txt hist trigger specification. · line 1926
Quoted 11 lines
Documentation/trace/histogram.txt +1
-3Finally, the number and type of variables/fields in the 'param list' must match the number and types of the fields in the@@ -1920,9 +1923,9 @@ hist trigger specification. /sys/kernel/debug/tracing/events/sched/sched_waking/trigger Then, when the corresponding thread is actually scheduled onto the - CPU by a sched_switch event, calculate the latency and use that - along with another variable and an event field to generate a - wakeup_latency synthetic event: + CPU by a sched_switch event (saved_pid matches next_pid), calculate
CPU by a sched_switch event (where the sched_waking key "saved_pid" matches the sched_switch key "next_pid"),
Other than that, looks good.
Could you send a v2 with the updates?
Thanks!
-- Steve
Quoted 5 lines
Documentation/trace/histogram.txt +2
-0+ the latency and use that along with another variable and an event field + to generate a wakeup_latency synthetic event: # echo 'hist:keys=next_pid:wakeup_lat=common_timestamp.usecs-$ts0:\ onmatch(sched.sched_waking).wakeup_latency($wakeup_lat,\