Documentation/trace/boottime-trace.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 =================
   4 Boot-time tracing
   5 =================
   6
   7 :Author: Masami Hiramatsu <mhiramat@kernel.org>
   8
   9 Overview
  10 ========
  11
  12 Boot-time tracing allows users to trace boot-time process including
  13 device initialization with full features of ftrace including per-event
  14 filter and actions, histograms, kprobe-events and synthetic-events,
  15 and trace instances.
  16 Since kernel command line is not enough to control these complex features,
  17 this uses bootconfig file to describe tracing feature programming.
  18
  19 Options in the Boot Config
  20 ==========================
  21
  22 Here is the list of available options list for boot time tracing in
  23 boot config file [1]_. All options are under "ftrace." or "kernel."
  24 prefix. See kernel parameters for the options which starts
  25 with "kernel." prefix [2]_.
  26
  27 .. [1] See :ref:`Documentation/admin-guide/bootconfig.rst <bootconfig>`
  28 .. [2] See :ref:`Documentation/admin-guide/kernel-parameters.rst <kernelparameters>`
  29
  30 Ftrace Global Options
  31 ---------------------
  32
  33 Ftrace global options have "kernel." prefix in boot config, which means
  34 these options are passed as a part of kernel legacy command line.
  35
  36 kernel.tp_printk
  37    Output trace-event data on printk buffer too.
  38
  39 kernel.dump_on_oops [= MODE]
  40    Dump ftrace on Oops. If MODE = 1 or omitted, dump trace buffer
  41    on all CPUs. If MODE = 2, dump a buffer on a CPU which kicks Oops.
  42
  43 kernel.traceoff_on_warning
  44    Stop tracing if WARN_ON() occurs.
  45
  46 kernel.fgraph_max_depth = MAX_DEPTH
  47    Set MAX_DEPTH to maximum depth of fgraph tracer.
  48
  49 kernel.fgraph_filters = FILTER[, FILTER2...]
  50    Add fgraph tracing function filters.
  51
  52 kernel.fgraph_notraces = FILTER[, FILTER2...]
  53    Add fgraph non-tracing function filters.
  54
  55
  56 Ftrace Per-instance Options
  57 ---------------------------
  58
  59 These options can be used for each instance including global ftrace node.
  60
  61 ftrace.[instance.INSTANCE.]options = OPT1[, OPT2[...]]
  62    Enable given ftrace options.
  63
  64 ftrace.[instance.INSTANCE.]tracing_on = 0|1
  65    Enable/Disable tracing on this instance when starting boot-time tracing.
  66    (you can enable it by the "traceon" event trigger action)
  67
  68 ftrace.[instance.INSTANCE.]trace_clock = CLOCK
  69    Set given CLOCK to ftrace's trace_clock.
  70
  71 ftrace.[instance.INSTANCE.]buffer_size = SIZE
  72    Configure ftrace buffer size to SIZE. You can use "KB" or "MB"
  73    for that SIZE.
  74
  75 ftrace.[instance.INSTANCE.]alloc_snapshot
  76    Allocate snapshot buffer.
  77
  78 ftrace.[instance.INSTANCE.]cpumask = CPUMASK
  79    Set CPUMASK as trace cpu-mask.
  80
  81 ftrace.[instance.INSTANCE.]events = EVENT[, EVENT2[...]]
  82    Enable given events on boot. You can use a wild card in EVENT.
  83
  84 ftrace.[instance.INSTANCE.]tracer = TRACER
  85    Set TRACER to current tracer on boot. (e.g. function)
  86
  87 ftrace.[instance.INSTANCE.]ftrace.filters
  88    This will take an array of tracing function filter rules.
  89
  90 ftrace.[instance.INSTANCE.]ftrace.notraces
  91    This will take an array of NON-tracing function filter rules.
  92
  93
  94 Ftrace Per-Event Options
  95 ------------------------
  96
  97 These options are setting per-event options.
  98
  99 ftrace.[instance.INSTANCE.]event.GROUP.EVENT.enable
 100    Enable GROUP:EVENT tracing.
 101
 102 ftrace.[instance.INSTANCE.]event.GROUP.enable
 103    Enable all event tracing within GROUP.
 104
 105 ftrace.[instance.INSTANCE.]event.enable
 106    Enable all event tracing.
 107
 108 ftrace.[instance.INSTANCE.]event.GROUP.EVENT.filter = FILTER
 109    Set FILTER rule to the GROUP:EVENT.
 110
 111 ftrace.[instance.INSTANCE.]event.GROUP.EVENT.actions = ACTION[, ACTION2[...]]
 112    Set ACTIONs to the GROUP:EVENT.
 113
 114 ftrace.[instance.INSTANCE.]event.kprobes.EVENT.probes = PROBE[, PROBE2[...]]
 115    Defines new kprobe event based on PROBEs. It is able to define
 116    multiple probes on one event, but those must have same type of
 117    arguments. This option is available only for the event which
 118    group name is "kprobes".
 119
 120 ftrace.[instance.INSTANCE.]event.synthetic.EVENT.fields = FIELD[, FIELD2[...]]
 121    Defines new synthetic event with FIELDs. Each field should be
 122    "type varname".
 123
 124 Note that kprobe and synthetic event definitions can be written under
 125 instance node, but those are also visible from other instances. So please
 126 take care for event name conflict.
 127
 128 Ftrace Histogram Options
 129 ------------------------
 130
 131 Since it is too long to write a histogram action as a string for per-event
 132 action option, there are tree-style options under per-event 'hist' subkey
 133 for the histogram actions. For the detail of the each parameter,
 134 please read the event histogram document (Documentation/trace/histogram.rst)
 135
 136 ftrace.[instance.INSTANCE.]event.GROUP.EVENT.hist.[N.]keys = KEY1[, KEY2[...]]
 137   Set histogram key parameters. (Mandatory)
 138   The 'N' is a digit string for the multiple histogram. You can omit it
 139   if there is one histogram on the event.
 140
 141 ftrace.[instance.INSTANCE.]event.GROUP.EVENT.hist.[N.]values = VAL1[, VAL2[...]]
 142   Set histogram value parameters.
 143
 144 ftrace.[instance.INSTANCE.]event.GROUP.EVENT.hist.[N.]sort = SORT1[, SORT2[...]]
 145   Set histogram sort parameter options.
 146
 147 ftrace.[instance.INSTANCE.]event.GROUP.EVENT.hist.[N.]size = NR_ENTRIES
 148   Set histogram size (number of entries).
 149
 150 ftrace.[instance.INSTANCE.]event.GROUP.EVENT.hist.[N.]name = NAME
 151   Set histogram name.
 152
 153 ftrace.[instance.INSTANCE.]event.GROUP.EVENT.hist.[N.]var.VARIABLE = EXPR
 154   Define a new VARIABLE by EXPR expression.
 155
 156 ftrace.[instance.INSTANCE.]event.GROUP.EVENT.hist.[N.]<pause|continue|clear>
 157   Set histogram control parameter. You can set one of them.
 158
 159 ftrace.[instance.INSTANCE.]event.GROUP.EVENT.hist.[N.]onmatch.[M.]event = GROUP.EVENT
 160   Set histogram 'onmatch' handler matching event parameter.
 161   The 'M' is a digit string for the multiple 'onmatch' handler. You can omit it
 162   if there is one 'onmatch' handler on this histogram.
 163
 164 ftrace.[instance.INSTANCE.]event.GROUP.EVENT.hist.[N.]onmatch.[M.]trace = EVENT[, ARG1[...]]
 165   Set histogram 'trace' action for 'onmatch'.
 166   EVENT must be a synthetic event name, and ARG1... are parameters
 167   for that event. Mandatory if 'onmatch.event' option is set.
 168
 169 ftrace.[instance.INSTANCE.]event.GROUP.EVENT.hist.[N.]onmax.[M.]var = VAR
 170   Set histogram 'onmax' handler variable parameter.
 171
 172 ftrace.[instance.INSTANCE.]event.GROUP.EVENT.hist.[N.]onchange.[M.]var = VAR
 173   Set histogram 'onchange' handler variable parameter.
 174
 175 ftrace.[instance.INSTANCE.]event.GROUP.EVENT.hist.[N.]<onmax|onchange>.[M.]save = ARG1[, ARG2[...]]
 176   Set histogram 'save' action parameters for 'onmax' or 'onchange' handler.
 177   This option or below 'snapshot' option is mandatory if 'onmax.var' or
 178   'onchange.var' option is set.
 179
 180 ftrace.[instance.INSTANCE.]event.GROUP.EVENT.hist.[N.]<onmax|onchange>.[M.]snapshot
 181   Set histogram 'snapshot' action for 'onmax' or 'onchange' handler.
 182   This option or above 'save' option is mandatory if 'onmax.var' or
 183   'onchange.var' option is set.
 184
 185 ftrace.[instance.INSTANCE.]event.GROUP.EVENT.hist.filter = FILTER_EXPR
 186   Set histogram filter expression. You don't need 'if' in the FILTER_EXPR.
 187
 188 Note that this 'hist' option can conflict with the per-event 'actions'
 189 option if the 'actions' option has a histogram action.
 190
 191
 192 When to Start
 193 =============
 194
 195 All boot-time tracing options starting with ``ftrace`` will be enabled at the
 196 end of core_initcall. This means you can trace the events from postcore_initcall.
 197 Most of the subsystems and architecture dependent drivers will be initialized
 198 after that (arch_initcall or subsys_initcall). Thus, you can trace those with
 199 boot-time tracing.
 200 If you want to trace events before core_initcall, you can use the options
 201 starting with ``kernel``. Some of them will be enabled eariler than the initcall
 202 processing (for example,. ``kernel.ftrace=function`` and ``kernel.trace_event``
 203 will start before the initcall.)
 204
 205
 206 Examples
 207 ========
 208
 209 For example, to add filter and actions for each event, define kprobe
 210 events, and synthetic events with histogram, write a boot config like
 211 below::
 212
 213   ftrace.event {
 214         task.task_newtask {
 215                 filter = "pid < 128"
 216                 enable
 217         }
 218         kprobes.vfs_read {
 219                 probes = "vfs_read $arg1 $arg2"
 220                 filter = "common_pid < 200"
 221                 enable
 222         }
 223         synthetic.initcall_latency {
 224                 fields = "unsigned long func", "u64 lat"
 225                 hist {
 226                         keys = func.sym, lat
 227                         values = lat
 228                         sort = lat
 229                 }
 230         }
 231         initcall.initcall_start.hist {
 232                 keys = func
 233                 var.ts0 = common_timestamp.usecs
 234         }
 235         initcall.initcall_finish.hist {
 236                 keys = func
 237                 var.lat = common_timestamp.usecs - $ts0
 238                 onmatch {
 239                         event = initcall.initcall_start
 240                         trace = initcall_latency, func, $lat
 241                 }
 242         }
 243   }
 244
 245 Also, boot-time tracing supports "instance" node, which allows us to run
 246 several tracers for different purpose at once. For example, one tracer
 247 is for tracing functions starting with "user\_", and others tracing
 248 "kernel\_" functions, you can write boot config as below::
 249
 250   ftrace.instance {
 251         foo {
 252                 tracer = "function"
 253                 ftrace.filters = "user_*"
 254         }
 255         bar {
 256                 tracer = "function"
 257                 ftrace.filters = "kernel_*"
 258         }
 259   }
 260
 261 The instance node also accepts event nodes so that each instance
 262 can customize its event tracing.
 263
 264 With the trigger action and kprobes, you can trace function-graph while
 265 a function is called. For example, this will trace all function calls in
 266 the pci_proc_init()::
 267
 268   ftrace {
 269         tracing_on = 0
 270         tracer = function_graph
 271         event.kprobes {
 272                 start_event {
 273                         probes = "pci_proc_init"
 274                         actions = "traceon"
 275                 }
 276                 end_event {
 277                         probes = "pci_proc_init%return"
 278                         actions = "traceoff"
 279                 }
 280         }
 281   }
 282
 283
 284 This boot-time tracing also supports ftrace kernel parameters via boot
 285 config.
 286 For example, following kernel parameters::
 287
 288  trace_options=sym-addr trace_event=initcall:* tp_printk trace_buf_size=1M ftrace=function ftrace_filter="vfs*"
 289
 290 This can be written in boot config like below::
 291
 292   kernel {
 293         trace_options = sym-addr
 294         trace_event = "initcall:*"
 295         tp_printk
 296         trace_buf_size = 1M
 297         ftrace = function
 298         ftrace_filter = "vfs*"
 299   }
 300
 301 Note that parameters start with "kernel" prefix instead of "ftrace".