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.EVENT.filter = FILTER
 103    Set FILTER rule to the GROUP:EVENT.
 104
 105 ftrace.[instance.INSTANCE.]event.GROUP.EVENT.actions = ACTION[, ACTION2[...]]
 106    Set ACTIONs to the GROUP:EVENT.
 107
 108 ftrace.[instance.INSTANCE.]event.kprobes.EVENT.probes = PROBE[, PROBE2[...]]
 109    Defines new kprobe event based on PROBEs. It is able to define
 110    multiple probes on one event, but those must have same type of
 111    arguments. This option is available only for the event which
 112    group name is "kprobes".
 113
 114 ftrace.[instance.INSTANCE.]event.synthetic.EVENT.fields = FIELD[, FIELD2[...]]
 115    Defines new synthetic event with FIELDs. Each field should be
 116    "type varname".
 117
 118 Note that kprobe and synthetic event definitions can be written under
 119 instance node, but those are also visible from other instances. So please
 120 take care for event name conflict.
 121
 122
 123 When to Start
 124 =============
 125
 126 All boot-time tracing options starting with ``ftrace`` will be enabled at the
 127 end of core_initcall. This means you can trace the events from postcore_initcall.
 128 Most of the subsystems and architecture dependent drivers will be initialized
 129 after that (arch_initcall or subsys_initcall). Thus, you can trace those with
 130 boot-time tracing.
 131 If you want to trace events before core_initcall, you can use the options
 132 starting with ``kernel``. Some of them will be enabled eariler than the initcall
 133 processing (for example,. ``kernel.ftrace=function`` and ``kernel.trace_event``
 134 will start before the initcall.)
 135
 136
 137 Examples
 138 ========
 139
 140 For example, to add filter and actions for each event, define kprobe
 141 events, and synthetic events with histogram, write a boot config like
 142 below::
 143
 144   ftrace.event {
 145         task.task_newtask {
 146                 filter = "pid < 128"
 147                 enable
 148         }
 149         kprobes.vfs_read {
 150                 probes = "vfs_read $arg1 $arg2"
 151                 filter = "common_pid < 200"
 152                 enable
 153         }
 154         synthetic.initcall_latency {
 155                 fields = "unsigned long func", "u64 lat"
 156                 actions = "hist:keys=func.sym,lat:vals=lat:sort=lat"
 157         }
 158         initcall.initcall_start {
 159                 actions = "hist:keys=func:ts0=common_timestamp.usecs"
 160         }
 161         initcall.initcall_finish {
 162                 actions = "hist:keys=func:lat=common_timestamp.usecs-$ts0:onmatch(initcall.initcall_start).initcall_latency(func,$lat)"
 163         }
 164   }
 165
 166 Also, boot-time tracing supports "instance" node, which allows us to run
 167 several tracers for different purpose at once. For example, one tracer
 168 is for tracing functions starting with "user\_", and others tracing
 169 "kernel\_" functions, you can write boot config as below::
 170
 171   ftrace.instance {
 172         foo {
 173                 tracer = "function"
 174                 ftrace.filters = "user_*"
 175         }
 176         bar {
 177                 tracer = "function"
 178                 ftrace.filters = "kernel_*"
 179         }
 180   }
 181
 182 The instance node also accepts event nodes so that each instance
 183 can customize its event tracing.
 184
 185 With the trigger action and kprobes, you can trace function-graph while
 186 a function is called. For example, this will trace all function calls in
 187 the pci_proc_init()::
 188
 189   ftrace {
 190         tracing_on = 0
 191         tracer = function_graph
 192         event.kprobes {
 193                 start_event {
 194                         probes = "pci_proc_init"
 195                         actions = "traceon"
 196                 }
 197                 end_event {
 198                         probes = "pci_proc_init%return"
 199                         actions = "traceoff"
 200                 }
 201         }
 202   }
 203
 204
 205 This boot-time tracing also supports ftrace kernel parameters via boot
 206 config.
 207 For example, following kernel parameters::
 208
 209  trace_options=sym-addr trace_event=initcall:* tp_printk trace_buf_size=1M ftrace=function ftrace_filter="vfs*"
 210
 211 This can be written in boot config like below::
 212
 213   kernel {
 214         trace_options = sym-addr
 215         trace_event = "initcall:*"
 216         tp_printk
 217         trace_buf_size = 1M
 218         ftrace = function
 219         ftrace_filter = "vfs*"
 220   }
 221
 222 Note that parameters start with "kernel" prefix instead of "ftrace".