Commit 55978953 authored by Masami Hiramatsu's avatar Masami Hiramatsu Committed by Steven Rostedt (VMware)
Browse files

Documentation: tracing: Add histogram syntax to boot-time tracing 

Add the documentation about histogram syntax in boot-time tracing.
This will allow user to write the histogram setting in a structured
parameters.

Link: https://lkml.kernel.org/r/162856127129.203126.15551542847575916525.stgit@devnote2



Signed-off-by: default avatarMasami Hiramatsu <mhiramat@kernel.org>
Signed-off-by: default avatarSteven Rostedt (VMware) <rostedt@goodmis.org>
parent 64dc7f69

Documentation/trace/boottime-trace.rst

+80 −5
Original line number Diff line number Diff line
@@ -125,6 +125,71 @@ Note that kprobe and synthetic event definitions can be written under 
instance node, but those are also visible from other instances. So please

take care for event name conflict.



Ftrace Histogram Options

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



Since it is too long to write a histogram action as a string for per-event

action option, there are tree-style options under per-event 'hist' subkey

for the histogram actions. For the detail of the each parameter,

please read the event histogram document [3]_.



.. [3] See :ref:`Documentation/trace/histogram.rst <histogram>`



ftrace.[instance.INSTANCE.]event.GROUP.EVENT.hist.[N.]keys = KEY1[, KEY2[...]]

  Set histogram key parameters. (Mandatory)

  The 'N' is a digit string for the multiple histogram. You can omit it

  if there is one histogram on the event.



ftrace.[instance.INSTANCE.]event.GROUP.EVENT.hist.[N.]values = VAL1[, VAL2[...]]

  Set histogram value parameters.



ftrace.[instance.INSTANCE.]event.GROUP.EVENT.hist.[N.]sort = SORT1[, SORT2[...]]

  Set histogram sort parameter options.



ftrace.[instance.INSTANCE.]event.GROUP.EVENT.hist.[N.]size = NR_ENTRIES

  Set histogram size (number of entries).



ftrace.[instance.INSTANCE.]event.GROUP.EVENT.hist.[N.]name = NAME

  Set histogram name.



ftrace.[instance.INSTANCE.]event.GROUP.EVENT.hist.[N.]var.VARIABLE = EXPR

  Define a new VARIABLE by EXPR expression.



ftrace.[instance.INSTANCE.]event.GROUP.EVENT.hist.[N.]<pause|continue|clear>

  Set histogram control parameter. You can set one of them.



ftrace.[instance.INSTANCE.]event.GROUP.EVENT.hist.[N.]onmatch.[M.]event = GROUP.EVENT

  Set histogram 'onmatch' handler matching event parameter.

  The 'M' is a digit string for the multiple 'onmatch' handler. You can omit it

  if there is one 'onmatch' handler on this histogram.



ftrace.[instance.INSTANCE.]event.GROUP.EVENT.hist.[N.]onmatch.[M.]trace = EVENT[, ARG1[...]]

  Set histogram 'trace' action for 'onmatch'.

  EVENT must be a synthetic event name, and ARG1... are parameters

  for that event. Mandatory if 'onmatch.event' option is set.



ftrace.[instance.INSTANCE.]event.GROUP.EVENT.hist.[N.]onmax.[M.]var = VAR

  Set histogram 'onmax' handler variable parameter.



ftrace.[instance.INSTANCE.]event.GROUP.EVENT.hist.[N.]onchange.[M.]var = VAR

  Set histogram 'onchange' handler variable parameter.



ftrace.[instance.INSTANCE.]event.GROUP.EVENT.hist.[N.]<onmax|onchange>.[M.]save = ARG1[, ARG2[...]]

  Set histogram 'save' action parameters for 'onmax' or 'onchange' handler.

  This option or below 'snapshot' option is mandatory if 'onmax.var' or

  'onchange.var' option is set.



ftrace.[instance.INSTANCE.]event.GROUP.EVENT.hist.[N.]<onmax|onchange>.[M.]snapshot

  Set histogram 'snapshot' action for 'onmax' or 'onchange' handler.

  This option or above 'save' option is mandatory if 'onmax.var' or

  'onchange.var' option is set.



ftrace.[instance.INSTANCE.]event.GROUP.EVENT.hist.filter = FILTER_EXPR

  Set histogram filter expression. You don't need 'if' in the FILTER_EXPR.



Note that this 'hist' option can conflict with the per-event 'actions'

option if the 'actions' option has a histogram action.





When to Start

=============
@@ -159,13 +224,23 @@ below:: 
        }

        synthetic.initcall_latency {

                fields = "unsigned long func", "u64 lat"

                actions = "hist:keys=func.sym,lat:vals=lat:sort=lat"

                hist {

                        keys = func.sym, lat

                        values = lat

                        sort = lat

                }

        }

        initcall.initcall_start.hist {

                keys = func

                var.ts0 = common_timestamp.usecs

        }

        initcall.initcall_start {

                actions = "hist:keys=func:ts0=common_timestamp.usecs"

        initcall.initcall_finish.hist {

                keys = func

                var.lat = common_timestamp.usecs - $ts0

                onmatch {

                        event = initcall.initcall_start

                        trace = initcall_latency, func, $lat

                }

        initcall.initcall_finish {

                actions = "hist:keys=func:lat=common_timestamp.usecs-$ts0:onmatch(initcall.initcall_start).initcall_latency(func,$lat)"

        }

  }