iv/linux
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

tracing: Make hist trigger Documentation better reflect actions/handlers

Browse Source 
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
1 changed files with 43 additions and 13 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

56
Documentation/trace/histogram.rst
View File

@ -25,7 +25,7 @@ Documentation written by Tom Zanussi
hist:keys=<field1[,field2,...]>[:values=<field1[,field2,...]>]
[: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
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
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
histogram entry is added or updated.
A hist trigger 'action' is a function that's executed (in most cases
conditionally) whenever a histogram entry is added or updated.
The default 'action' if no special function is explicitly 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.
When a histogram entry is added or updated, a hist trigger 'handler'
is what decides whether the corresponding action is actually invoked
or not.
The following additional actions are available. To specify an action
for a given event, simply specify the action between colons in the
hist trigger specification.
Hist trigger handlers and actions are paired together in the general
form:
<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)