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 Examples
 124 ========
 125
 126 For example, to add filter and actions for each event, define kprobe
 127 events, and synthetic events with histogram, write a boot config like
 128 below::
 129
 130   ftrace.event {
 131         task.task_newtask {
 132                 filter = "pid < 128"
 133                 enable
 134         }
 135         kprobes.vfs_read {
 136                 probes = "vfs_read $arg1 $arg2"
 137                 filter = "common_pid < 200"
 138                 enable
 139         }
 140         synthetic.initcall_latency {
 141                 fields = "unsigned long func", "u64 lat"
 142                 actions = "hist:keys=func.sym,lat:vals=lat:sort=lat"
 143         }
 144         initcall.initcall_start {
 145                 actions = "hist:keys=func:ts0=common_timestamp.usecs"
 146         }
 147         initcall.initcall_finish {
 148                 actions = "hist:keys=func:lat=common_timestamp.usecs-$ts0:onmatch(initcall.initcall_start).initcall_latency(func,$lat)"
 149         }
 150   }
 151
 152 Also, boot-time tracing supports "instance" node, which allows us to run
 153 several tracers for different purpose at once. For example, one tracer
 154 is for tracing functions starting with "user\_", and others tracing
 155 "kernel\_" functions, you can write boot config as below::
 156
 157   ftrace.instance {
 158         foo {
 159                 tracer = "function"
 160                 ftrace.filters = "user_*"
 161         }
 162         bar {
 163                 tracer = "function"
 164                 ftrace.filters = "kernel_*"
 165         }
 166   }
 167
 168 The instance node also accepts event nodes so that each instance
 169 can customize its event tracing.
 170
 171 This boot-time tracing also supports ftrace kernel parameters via boot
 172 config.
 173 For example, following kernel parameters::
 174
 175  trace_options=sym-addr trace_event=initcall:* tp_printk trace_buf_size=1M ftrace=function ftrace_filter="vfs*"
 176
 177 This can be written in boot config like below::
 178
 179   kernel {
 180         trace_options = sym-addr
 181         trace_event = "initcall:*"
 182         tp_printk
 183         trace_buf_size = 1M
 184         ftrace = function
 185         ftrace_filter = "vfs*"
 186   }
 187
 188 Note that parameters start with "kernel" prefix instead of "ftrace".