Commit 064f35a9 authored by Joel Fernandes (Google)'s avatar Joel Fernandes (Google) Committed by Steven Rostedt (VMware)
Browse files

tracing: Fix some errors in histogram documentation 

Fix typos, inconsistencies in using quotes, incorrect section number,
etc. in the trace histogram documentation.

Link: http://lkml.kernel.org/r/20180614224859.55864-1-joel@joelfernandes.org



Reviewed-by: default avatarMasami Hiramatsu <mhiramat@kernel.org>
Acked-by: default avatarTom Zanussi <tom.zanussi@linux.intel.com>
Signed-off-by: default avatarJoel Fernandes (Google) <joel@joelfernandes.org>
Signed-off-by: default avatarSteven Rostedt (VMware) <rostedt@goodmis.org>
parent 08ae88f8

Documentation/trace/histogram.txt

+12 −11
Original line number Original line Diff line number Diff line
@@ -1729,35 +1729,35 @@ If a variable isn't a key variable or prefixed with 'vals=', the 
associated event field will be saved in a variable but won't be summed

associated event field will be saved in a variable but won't be summed

as a value:

as a value:





  # echo 'hist:keys=next_pid:ts1=common_timestamp ... >> event/trigger

  # echo 'hist:keys=next_pid:ts1=common_timestamp ...' >> event/trigger





Multiple variables can be assigned at the same time.  The below would

Multiple variables can be assigned at the same time.  The below would

result in both ts0 and b being created as variables, with both

result in both ts0 and b being created as variables, with both

common_timestamp and field1 additionally being summed as values:

common_timestamp and field1 additionally being summed as values:





  # echo 'hist:keys=pid:vals=$ts0,$b:ts0=common_timestamp,b=field1 ... >> \

  # echo 'hist:keys=pid:vals=$ts0,$b:ts0=common_timestamp,b=field1 ...' >> \

	event/trigger

	event/trigger





Note that variable assignments can appear either preceding or

Note that variable assignments can appear either preceding or

following their use.  The command below behaves identically to the

following their use.  The command below behaves identically to the

command above:

command above:





  # echo 'hist:keys=pid:ts0=common_timestamp,b=field1:vals=$ts0,$b ... >> \

  # echo 'hist:keys=pid:ts0=common_timestamp,b=field1:vals=$ts0,$b ...' >> \

	event/trigger

	event/trigger





Any number of variables not bound to a 'vals=' prefix can also be

Any number of variables not bound to a 'vals=' prefix can also be

assigned by simply separating them with colons.  Below is the same

assigned by simply separating them with colons.  Below is the same

thing but without the values being summed in the histogram:

thing but without the values being summed in the histogram:





  # echo 'hist:keys=pid:ts0=common_timestamp:b=field1 ... >> event/trigger

  # echo 'hist:keys=pid:ts0=common_timestamp:b=field1 ...' >> event/trigger





Variables set as above can be referenced and used in expressions on

Variables set as above can be referenced and used in expressions on

another event.

another event.





For example, here's how a latency can be calculated:

For example, here's how a latency can be calculated:





  # echo 'hist:keys=pid,prio:ts0=common_timestamp ... >> event1/trigger

  # echo 'hist:keys=pid,prio:ts0=common_timestamp ...' >> event1/trigger

  # echo 'hist:keys=next_pid:wakeup_lat=common_timestamp-$ts0 ... >> event2/trigger

  # echo 'hist:keys=next_pid:wakeup_lat=common_timestamp-$ts0 ...' >> event2/trigger





In the first line above, the event's timetamp is saved into the

In the first line above, the event's timetamp is saved into the

variable ts0.  In the next line, ts0 is subtracted from the second

variable ts0.  In the next line, ts0 is subtracted from the second
@@ -1766,7 +1766,7 @@ yet another variable, 'wakeup_lat'. The hist trigger below in turn 
makes use of the wakeup_lat variable to compute a combined latency

makes use of the wakeup_lat variable to compute a combined latency

using the same key and variable from yet another event:

using the same key and variable from yet another event:





  # echo 'hist:key=pid:wakeupswitch_lat=$wakeup_lat+$switchtime_lat ... >> event3/trigger

  # echo 'hist:key=pid:wakeupswitch_lat=$wakeup_lat+$switchtime_lat ...' >> event3/trigger





2.2.2 Synthetic Events

2.2.2 Synthetic Events

----------------------

----------------------
@@ -1807,10 +1807,11 @@ the command that defined it with a '!': 
At this point, there isn't yet an actual 'wakeup_latency' event

At this point, there isn't yet an actual 'wakeup_latency' event

instantiated in the event subsytem - for this to happen, a 'hist

instantiated in the event subsytem - for this to happen, a 'hist

trigger action' needs to be instantiated and bound to actual fields

trigger action' needs to be instantiated and bound to actual fields

and variables defined on other events (see Section 6.3.3 below).

and variables defined on other events (see Section 2.2.3 below on

how that is done using hist trigger 'onmatch' action). Once that is

done, the 'wakeup_latency' synthetic event instance is created.





Once that is done, an event instance is created, and a histogram can

A histogram can now be defined for the new synthetic event:

be defined using it:





  # echo 'hist:keys=pid,prio,lat.log2:sort=pid,lat' >> \

  # echo 'hist:keys=pid,prio,lat.log2:sort=pid,lat' >> \

        /sys/kernel/debug/tracing/events/synthetic/wakeup_latency/trigger

        /sys/kernel/debug/tracing/events/synthetic/wakeup_latency/trigger
@@ -1960,7 +1961,7 @@ hist trigger specification. 
    back to that pid, the timestamp difference is calculated.  If the

    back to that pid, the timestamp difference is calculated.  If the

    resulting latency, stored in wakeup_lat, exceeds the current

    resulting latency, stored in wakeup_lat, exceeds the current

    maximum latency, the values specified in the save() fields are

    maximum latency, the values specified in the save() fields are

    recoreded:

    recorded:





    # echo 'hist:keys=pid:ts0=common_timestamp.usecs \

    # echo 'hist:keys=pid:ts0=common_timestamp.usecs \

            if comm=="cyclictest"' >> \

            if comm=="cyclictest"' >> \

CRA Git | Maintained and supported by SUSTech CRA and CCSE