tracing: Make hist trigger Documentation better reflect actions/handlers

The action/handler code refactoring didn't change the action/handler
syntax, but did generalize it - the Documentation should reflect that.

Link: http://lkml.kernel.org/r/c2fe4144678829c70cad67aaa847dca27d57cb83.1550100284.git.tom.zanussi@linux.intel.com

Signed-off-by: Tom Zanussi <tom.zanussi@linux.intel.com>
Signed-off-by: Steven Rostedt (VMware) <rostedt@goodmis.org>
This commit is contained in:
Tom Zanussi 2019-02-13 17:42:42 -06:00 committed by Steven Rostedt (VMware)
parent 7d18a10c31
commit 5032b38189

View File

@ -25,7 +25,7 @@ Documentation written by Tom Zanussi
hist:keys=<field1[,field2,...]>[:values=<field1[,field2,...]>] hist:keys=<field1[,field2,...]>[:values=<field1[,field2,...]>]
[:sort=<field1[,field2,...]>][:size=#entries][:pause][:continue] [:sort=<field1[,field2,...]>][:size=#entries][:pause][:continue]
[:clear][:name=histname1] [if <filter>] [:clear][:name=histname1][:<handler>.<action>] [if <filter>]
When a matching event is hit, an entry is added to a hash table When a matching event is hit, an entry is added to a hash table
using the key(s) and value(s) named. Keys and values correspond to using the key(s) and value(s) named. Keys and values correspond to
@ -1831,21 +1831,51 @@ and looks and behaves just like any other event::
Like any other event, once a histogram is enabled for the event, the Like any other event, once a histogram is enabled for the event, the
output can be displayed by reading the event's 'hist' file. output can be displayed by reading the event's 'hist' file.
2.2.3 Hist trigger 'actions' 2.2.3 Hist trigger 'handlers' and 'actions'
---------------------------- -------------------------------------------
A hist trigger 'action' is a function that's executed whenever a A hist trigger 'action' is a function that's executed (in most cases
histogram entry is added or updated. conditionally) whenever a histogram entry is added or updated.
The default 'action' if no special function is explicitly specified is When a histogram entry is added or updated, a hist trigger 'handler'
as it always has been, to simply update the set of values associated is what decides whether the corresponding action is actually invoked
with an entry. Some applications, however, may want to perform or not.
additional actions at that point, such as generate another event, or
compare and save a maximum.
The following additional actions are available. To specify an action Hist trigger handlers and actions are paired together in the general
for a given event, simply specify the action between colons in the form:
hist trigger specification.
<handler>.<action>
To specify a handler.action pair for a given event, simply specify
that handler.action pair between colons in the hist trigger
specification.
In theory, any handler can be combined with any action, but in
practice, not every handler.action combination is currently supported;
if a given handler.action combination isn't supported, the hist
trigger will fail with -EINVAL;
The default 'handler.action' if none is explicity specified is as it
always has been, to simply update the set of values associated with an
entry. Some applications, however, may want to perform additional
actions at that point, such as generate another event, or compare and
save a maximum.
The supported handlers and actions are listed below, and each is
described in more detail in the following paragraphs, in the context
of descriptions of some common and useful handler.action combinations.
The available handlers are:
- onmatch(matching.event) - invoke action on any addition or update
- onmax(var) - invoke action if var exceeds current max
The available actions are:
- <synthetic_event_name>(param list) - generate synthetic event
- save(field,...) - save current event fields
The following commonly-used handler.action pairs are available:
- onmatch(matching.event).<synthetic_event_name>(param list) - onmatch(matching.event).<synthetic_event_name>(param list)