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.]trace_clock = CLOCK
  65    Set given CLOCK to ftrace's trace_clock.
  66
  67 ftrace.[instance.INSTANCE.]buffer_size = SIZE
  68    Configure ftrace buffer size to SIZE. You can use "KB" or "MB"
  69    for that SIZE.
  70
  71 ftrace.[instance.INSTANCE.]alloc_snapshot
  72    Allocate snapshot buffer.
  73
  74 ftrace.[instance.INSTANCE.]cpumask = CPUMASK
  75    Set CPUMASK as trace cpu-mask.
  76
  77 ftrace.[instance.INSTANCE.]events = EVENT[, EVENT2[...]]
  78    Enable given events on boot. You can use a wild card in EVENT.
  79
  80 ftrace.[instance.INSTANCE.]tracer = TRACER
  81    Set TRACER to current tracer on boot. (e.g. function)
  82
  83 ftrace.[instance.INSTANCE.]ftrace.filters
  84    This will take an array of tracing function filter rules.
  85
  86 ftrace.[instance.INSTANCE.]ftrace.notraces
  87    This will take an array of NON-tracing function filter rules.
  88
  89
  90 Ftrace Per-Event Options
  91 ------------------------
  92
  93 These options are setting per-event options.
  94
  95 ftrace.[instance.INSTANCE.]event.GROUP.EVENT.enable
  96    Enable GROUP:EVENT tracing.
  97
  98 ftrace.[instance.INSTANCE.]event.GROUP.EVENT.filter = FILTER
  99    Set FILTER rule to the GROUP:EVENT.
 100
 101 ftrace.[instance.INSTANCE.]event.GROUP.EVENT.actions = ACTION[, ACTION2[...]]
 102    Set ACTIONs to the GROUP:EVENT.
 103
 104 ftrace.[instance.INSTANCE.]event.kprobes.EVENT.probes = PROBE[, PROBE2[...]]
 105    Defines new kprobe event based on PROBEs. It is able to define
 106    multiple probes on one event, but those must have same type of
 107    arguments. This option is available only for the event which
 108    group name is "kprobes".
 109
 110 ftrace.[instance.INSTANCE.]event.synthetic.EVENT.fields = FIELD[, FIELD2[...]]
 111    Defines new synthetic event with FIELDs. Each field should be
 112    "type varname".
 113
 114 Note that kprobe and synthetic event definitions can be written under
 115 instance node, but those are also visible from other instances. So please
 116 take care for event name conflict.
 117
 118
 119 Examples
 120 ========
 121
 122 For example, to add filter and actions for each event, define kprobe
 123 events, and synthetic events with histogram, write a boot config like
 124 below::
 125
 126   ftrace.event {
 127         task.task_newtask {
 128                 filter = "pid < 128"
 129                 enable
 130         }
 131         kprobes.vfs_read {
 132                 probes = "vfs_read $arg1 $arg2"
 133                 filter = "common_pid < 200"
 134                 enable
 135         }
 136         synthetic.initcall_latency {
 137                 fields = "unsigned long func", "u64 lat"
 138                 actions = "hist:keys=func.sym,lat:vals=lat:sort=lat"
 139         }
 140         initcall.initcall_start {
 141                 actions = "hist:keys=func:ts0=common_timestamp.usecs"
 142         }
 143         initcall.initcall_finish {
 144                 actions = "hist:keys=func:lat=common_timestamp.usecs-$ts0:onmatch(initcall.initcall_start).initcall_latency(func,$lat)"
 145         }
 146   }
 147
 148 Also, boot-time tracing supports "instance" node, which allows us to run
 149 several tracers for different purpose at once. For example, one tracer
 150 is for tracing functions starting with "user\_", and others tracing
 151 "kernel\_" functions, you can write boot config as below::
 152
 153   ftrace.instance {
 154         foo {
 155                 tracer = "function"
 156                 ftrace.filters = "user_*"
 157         }
 158         bar {
 159                 tracer = "function"
 160                 ftrace.filters = "kernel_*"
 161         }
 162   }
 163
 164 The instance node also accepts event nodes so that each instance
 165 can customize its event tracing.
 166
 167 This boot-time tracing also supports ftrace kernel parameters via boot
 168 config.
 169 For example, following kernel parameters::
 170
 171  trace_options=sym-addr trace_event=initcall:* tp_printk trace_buf_size=1M ftrace=function ftrace_filter="vfs*"
 172
 173 This can be written in boot config like below::
 174
 175   kernel {
 176         trace_options = sym-addr
 177         trace_event = "initcall:*"
 178         tp_printk
 179         trace_buf_size = 1M
 180         ftrace = function
 181         ftrace_filter = "vfs*"
 182   }
 183
 184 Note that parameters start with "kernel" prefix instead of "ftrace".