boottime-trace.rst 7.1 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222
  1. .. SPDX-License-Identifier: GPL-2.0
  2. =================
  3. Boot-time tracing
  4. =================
  5. :Author: Masami Hiramatsu <mhiramat@kernel.org>
  6. Overview
  7. ========
  8. Boot-time tracing allows users to trace boot-time process including
  9. device initialization with full features of ftrace including per-event
  10. filter and actions, histograms, kprobe-events and synthetic-events,
  11. and trace instances.
  12. Since kernel command line is not enough to control these complex features,
  13. this uses bootconfig file to describe tracing feature programming.
  14. Options in the Boot Config
  15. ==========================
  16. Here is the list of available options list for boot time tracing in
  17. boot config file [1]_. All options are under "ftrace." or "kernel."
  18. prefix. See kernel parameters for the options which starts
  19. with "kernel." prefix [2]_.
  20. .. [1] See :ref:`Documentation/admin-guide/bootconfig.rst <bootconfig>`
  21. .. [2] See :ref:`Documentation/admin-guide/kernel-parameters.rst <kernelparameters>`
  22. Ftrace Global Options
  23. ---------------------
  24. Ftrace global options have "kernel." prefix in boot config, which means
  25. these options are passed as a part of kernel legacy command line.
  26. kernel.tp_printk
  27. Output trace-event data on printk buffer too.
  28. kernel.dump_on_oops [= MODE]
  29. Dump ftrace on Oops. If MODE = 1 or omitted, dump trace buffer
  30. on all CPUs. If MODE = 2, dump a buffer on a CPU which kicks Oops.
  31. kernel.traceoff_on_warning
  32. Stop tracing if WARN_ON() occurs.
  33. kernel.fgraph_max_depth = MAX_DEPTH
  34. Set MAX_DEPTH to maximum depth of fgraph tracer.
  35. kernel.fgraph_filters = FILTER[, FILTER2...]
  36. Add fgraph tracing function filters.
  37. kernel.fgraph_notraces = FILTER[, FILTER2...]
  38. Add fgraph non-tracing function filters.
  39. Ftrace Per-instance Options
  40. ---------------------------
  41. These options can be used for each instance including global ftrace node.
  42. ftrace.[instance.INSTANCE.]options = OPT1[, OPT2[...]]
  43. Enable given ftrace options.
  44. ftrace.[instance.INSTANCE.]tracing_on = 0|1
  45. Enable/Disable tracing on this instance when starting boot-time tracing.
  46. (you can enable it by the "traceon" event trigger action)
  47. ftrace.[instance.INSTANCE.]trace_clock = CLOCK
  48. Set given CLOCK to ftrace's trace_clock.
  49. ftrace.[instance.INSTANCE.]buffer_size = SIZE
  50. Configure ftrace buffer size to SIZE. You can use "KB" or "MB"
  51. for that SIZE.
  52. ftrace.[instance.INSTANCE.]alloc_snapshot
  53. Allocate snapshot buffer.
  54. ftrace.[instance.INSTANCE.]cpumask = CPUMASK
  55. Set CPUMASK as trace cpu-mask.
  56. ftrace.[instance.INSTANCE.]events = EVENT[, EVENT2[...]]
  57. Enable given events on boot. You can use a wild card in EVENT.
  58. ftrace.[instance.INSTANCE.]tracer = TRACER
  59. Set TRACER to current tracer on boot. (e.g. function)
  60. ftrace.[instance.INSTANCE.]ftrace.filters
  61. This will take an array of tracing function filter rules.
  62. ftrace.[instance.INSTANCE.]ftrace.notraces
  63. This will take an array of NON-tracing function filter rules.
  64. Ftrace Per-Event Options
  65. ------------------------
  66. These options are setting per-event options.
  67. ftrace.[instance.INSTANCE.]event.GROUP.EVENT.enable
  68. Enable GROUP:EVENT tracing.
  69. ftrace.[instance.INSTANCE.]event.GROUP.EVENT.filter = FILTER
  70. Set FILTER rule to the GROUP:EVENT.
  71. ftrace.[instance.INSTANCE.]event.GROUP.EVENT.actions = ACTION[, ACTION2[...]]
  72. Set ACTIONs to the GROUP:EVENT.
  73. ftrace.[instance.INSTANCE.]event.kprobes.EVENT.probes = PROBE[, PROBE2[...]]
  74. Defines new kprobe event based on PROBEs. It is able to define
  75. multiple probes on one event, but those must have same type of
  76. arguments. This option is available only for the event which
  77. group name is "kprobes".
  78. ftrace.[instance.INSTANCE.]event.synthetic.EVENT.fields = FIELD[, FIELD2[...]]
  79. Defines new synthetic event with FIELDs. Each field should be
  80. "type varname".
  81. Note that kprobe and synthetic event definitions can be written under
  82. instance node, but those are also visible from other instances. So please
  83. take care for event name conflict.
  84. When to Start
  85. =============
  86. All boot-time tracing options starting with ``ftrace`` will be enabled at the
  87. end of core_initcall. This means you can trace the events from postcore_initcall.
  88. Most of the subsystems and architecture dependent drivers will be initialized
  89. after that (arch_initcall or subsys_initcall). Thus, you can trace those with
  90. boot-time tracing.
  91. If you want to trace events before core_initcall, you can use the options
  92. starting with ``kernel``. Some of them will be enabled eariler than the initcall
  93. processing (for example,. ``kernel.ftrace=function`` and ``kernel.trace_event``
  94. will start before the initcall.)
  95. Examples
  96. ========
  97. For example, to add filter and actions for each event, define kprobe
  98. events, and synthetic events with histogram, write a boot config like
  99. below::
  100. ftrace.event {
  101. task.task_newtask {
  102. filter = "pid < 128"
  103. enable
  104. }
  105. kprobes.vfs_read {
  106. probes = "vfs_read $arg1 $arg2"
  107. filter = "common_pid < 200"
  108. enable
  109. }
  110. synthetic.initcall_latency {
  111. fields = "unsigned long func", "u64 lat"
  112. actions = "hist:keys=func.sym,lat:vals=lat:sort=lat"
  113. }
  114. initcall.initcall_start {
  115. actions = "hist:keys=func:ts0=common_timestamp.usecs"
  116. }
  117. initcall.initcall_finish {
  118. actions = "hist:keys=func:lat=common_timestamp.usecs-$ts0:onmatch(initcall.initcall_start).initcall_latency(func,$lat)"
  119. }
  120. }
  121. Also, boot-time tracing supports "instance" node, which allows us to run
  122. several tracers for different purpose at once. For example, one tracer
  123. is for tracing functions starting with "user\_", and others tracing
  124. "kernel\_" functions, you can write boot config as below::
  125. ftrace.instance {
  126. foo {
  127. tracer = "function"
  128. ftrace.filters = "user_*"
  129. }
  130. bar {
  131. tracer = "function"
  132. ftrace.filters = "kernel_*"
  133. }
  134. }
  135. The instance node also accepts event nodes so that each instance
  136. can customize its event tracing.
  137. With the trigger action and kprobes, you can trace function-graph while
  138. a function is called. For example, this will trace all function calls in
  139. the pci_proc_init()::
  140. ftrace {
  141. tracing_on = 0
  142. tracer = function_graph
  143. event.kprobes {
  144. start_event {
  145. probes = "pci_proc_init"
  146. actions = "traceon"
  147. }
  148. end_event {
  149. probes = "pci_proc_init%return"
  150. actions = "traceoff"
  151. }
  152. }
  153. }
  154. This boot-time tracing also supports ftrace kernel parameters via boot
  155. config.
  156. For example, following kernel parameters::
  157. trace_options=sym-addr trace_event=initcall:* tp_printk trace_buf_size=1M ftrace=function ftrace_filter="vfs*"
  158. This can be written in boot config like below::
  159. kernel {
  160. trace_options = sym-addr
  161. trace_event = "initcall:*"
  162. tp_printk
  163. trace_buf_size = 1M
  164. ftrace = function
  165. ftrace_filter = "vfs*"
  166. }
  167. Note that parameters start with "kernel" prefix instead of "ftrace".