linux-kernel.vger.kernel.org archive mirror
 help / color / mirror / Atom feed
From: Steven Rostedt <rostedt@goodmis.org>
To: linux-kernel@vger.kernel.org
Cc: Ingo Molnar <mingo@kernel.org>,
	Andrew Morton <akpm@linux-foundation.org>,
	Masami Hiramatsu <mhiramat@kernel.org>
Subject: [for-next][PATCH 25/26] Documentation: tracing: Add boot-time tracing document
Date: Tue, 14 Jan 2020 16:03:41 -0500	[thread overview]
Message-ID: <20200114210339.338772772@goodmis.org> (raw)
In-Reply-To: <20200114210316.450821675@goodmis.org>

From: Masami Hiramatsu <mhiramat@kernel.org>

Add a documentation about boot-time tracing options in
boot config.

Link: http://lkml.kernel.org/r/157867246028.17873.8047384554383977870.stgit@devnote2

Signed-off-by: Masami Hiramatsu <mhiramat@kernel.org>
Signed-off-by: Steven Rostedt (VMware) <rostedt@goodmis.org>
---
 Documentation/admin-guide/bootconfig.rst |   2 +
 Documentation/trace/boottime-trace.rst   | 184 +++++++++++++++++++++++
 Documentation/trace/index.rst            |   1 +
 3 files changed, 187 insertions(+)
 create mode 100644 Documentation/trace/boottime-trace.rst

diff --git a/Documentation/admin-guide/bootconfig.rst b/Documentation/admin-guide/bootconfig.rst
index f7475df2a718..c8f7cd4cf44e 100644
--- a/Documentation/admin-guide/bootconfig.rst
+++ b/Documentation/admin-guide/bootconfig.rst
@@ -1,5 +1,7 @@
 .. SPDX-License-Identifier: GPL-2.0
 
+.. _bootconfig:
+
 ==================
 Boot Configuration
 ==================
diff --git a/Documentation/trace/boottime-trace.rst b/Documentation/trace/boottime-trace.rst
new file mode 100644
index 000000000000..1d10fdebf1b2
--- /dev/null
+++ b/Documentation/trace/boottime-trace.rst
@@ -0,0 +1,184 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=================
+Boot-time tracing
+=================
+
+:Author: Masami Hiramatsu <mhiramat@kernel.org>
+
+Overview
+========
+
+Boot-time tracing allows users to trace boot-time process including
+device initialization with full features of ftrace including per-event
+filter and actions, histograms, kprobe-events and synthetic-events,
+and trace instances.
+Since kernel cmdline is not enough to control these complex features,
+this uses bootconfig file to describe tracing feature programming.
+
+Options in the Boot Config
+==========================
+
+Here is the list of available options list for boot time tracing in
+boot config file [1]_. All options are under "ftrace." or "kernel."
+refix. See kernel parameters for the options which starts
+with "kernel." prefix [2]_.
+
+.. [1] See :ref:`Documentation/admin-guide/bootconfig.rst <bootconfig>`
+.. [2] See :ref:`Documentation/admin-guide/kernel-parameters.rst <kernelparameters>`
+
+Ftrace Global Options
+---------------------
+
+Ftrace global options have "kernel." prefix in boot config, which means
+these options are passed as a part of kernel legacy command line.
+
+kernel.tp_printk
+   Output trace-event data on printk buffer too.
+
+kernel.dump_on_oops [= MODE]
+   Dump ftrace on Oops. If MODE = 1 or omitted, dump trace buffer
+   on all CPUs. If MODE = 2, dump a buffer on a CPU which kicks Oops.
+
+kernel.traceoff_on_warning
+   Stop tracing if WARN_ON() occurs.
+
+kernel.fgraph_max_depth = MAX_DEPTH
+   Set MAX_DEPTH to maximum depth of fgraph tracer.
+
+kernel.fgraph_filters = FILTER[, FILTER2...]
+   Add fgraph tracing function filters.
+
+kernel.fgraph_notraces = FILTER[, FILTER2...]
+   Add fgraph non tracing function filters.
+
+
+Ftrace Per-instance Options
+---------------------------
+
+These options can be used for each instance including global ftrace node.
+
+ftrace.[instance.INSTANCE.]options = OPT1[, OPT2[...]]
+   Enable given ftrace options.
+
+ftrace.[instance.INSTANCE.]trace_clock = CLOCK
+   Set given CLOCK to ftrace's trace_clock.
+
+ftrace.[instance.INSTANCE.]buffer_size = SIZE
+   Configure ftrace buffer size to SIZE. You can use "KB" or "MB"
+   for that SIZE.
+
+ftrace.[instance.INSTANCE.]alloc_snapshot
+   Allocate snapshot buffer.
+
+ftrace.[instance.INSTANCE.]cpumask = CPUMASK
+   Set CPUMASK as trace cpu-mask.
+
+ftrace.[instance.INSTANCE.]events = EVENT[, EVENT2[...]]
+   Enable given events on boot. You can use a wild card in EVENT.
+
+ftrace.[instance.INSTANCE.]tracer = TRACER
+   Set TRACER to current tracer on boot. (e.g. function)
+
+ftrace.[instance.INSTANCE.]ftrace.filters
+   This will take an array of tracing function filter rules
+
+ftrace.[instance.INSTANCE.]ftrace.notraces
+   This will take an array of NON-tracing function filter rules
+
+
+Ftrace Per-Event Options
+------------------------
+
+These options are setting per-event options.
+
+ftrace.[instance.INSTANCE.]event.GROUP.EVENT.enable
+   Enables GROUP:EVENT tracing.
+
+ftrace.[instance.INSTANCE.]event.GROUP.EVENT.filter = FILTER
+   Set FILTER rule to the GROUP:EVENT.
+
+ftrace.[instance.INSTANCE.]event.GROUP.EVENT.actions = ACTION[, ACTION2[...]]
+   Set ACTIONs to the GROUP:EVENT.
+
+ftrace.[instance.INSTANCE.]event.kprobes.EVENT.probes = PROBE[, PROBE2[...]]
+   Defines new kprobe event based on PROBEs. It is able to define
+   multiple probes on one event, but those must have same type of
+   arguments. This option is available only for the event which
+   group name is "kprobes".
+
+ftrace.[instance.INSTANCE.]event.synthetic.EVENT.fields = FIELD[, FIELD2[...]]
+   Defines new synthetic event with FIELDs. Each field should be
+   "type varname".
+
+Note that kprobe and synthetic event definitions can be written under
+instance node, but those are also visible from other instances. So please
+take care for event name conflict.
+
+
+Examples
+========
+
+For example, to add filter and actions for each event, define kprobe
+events, and synthetic events with histogram, write a boot config like
+below::
+
+  ftrace.event {
+        task.task_newtask {
+                filter = "pid < 128"
+                enable
+        }
+        kprobes.vfs_read {
+                probes = "vfs_read $arg1 $arg2"
+                filter = "common_pid < 200"
+                enable
+        }
+        synthetic.initcall_latency {
+                fields = "unsigned long func", "u64 lat"
+                actions = "hist:keys=func.sym,lat:vals=lat:sort=lat"
+        }
+        initcall.initcall_start {
+                actions = "hist:keys=func:ts0=common_timestamp.usecs"
+        }
+        initcall.initcall_finish {
+                actions = "hist:keys=func:lat=common_timestamp.usecs-$ts0:onmatch(initcall.initcall_start).initcall_latency(func,$lat)"
+        }
+  }
+
+Also, boottime tracing supports "instance" node, which allows us to run
+several tracers for different purpose at once. For example, one tracer
+is for tracing functions start with "user\_", and others tracing "kernel\_"
+functions, you can write boot config as below::
+
+  ftrace.instance {
+        foo {
+                tracer = "function"
+                ftrace.filters = "user_*"
+        }
+        bar {
+                tracer = "function"
+                ftrace.filters = "kernel_*"
+        }
+  }
+
+The instance node also accepts event nodes so that each instance
+can customize its event tracing.
+
+This boot-time tracing also supports ftrace kernel parameters via boot
+config.
+For example, following kernel parameters::
+
+ trace_options=sym-addr trace_event=initcall:* tp_printk trace_buf_size=1M ftrace=function ftrace_filter="vfs*"
+
+This can be written in boot config like below::
+
+  kernel {
+        trace_options = sym-addr
+        trace_event = "initcall:*"
+        tp_printk
+        trace_buf_size = 1M
+        ftrace = function
+        ftrace_filter = "vfs*"
+  }
+
+Note that parameters start with "kernel" prefix instead of "ftrace".
diff --git a/Documentation/trace/index.rst b/Documentation/trace/index.rst
index 04acd277c5f6..fa9e1c730f6a 100644
--- a/Documentation/trace/index.rst
+++ b/Documentation/trace/index.rst
@@ -19,6 +19,7 @@ Linux Tracing Technologies
    events-msr
    mmiotrace
    histogram
+   boottime-trace
    hwlat_detector
    intel_th
    stm
-- 
2.24.1



  parent reply	other threads:[~2020-01-14 21:04 UTC|newest]

Thread overview: 65+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2020-01-14 21:03 [for-next][PATCH 00/26] tracing: Updates for 5.6 Steven Rostedt
2020-01-14 21:03 ` [for-next][PATCH 01/26] perf: Make struct ring_buffer less ambiguous Steven Rostedt
2020-01-14 21:03 ` [for-next][PATCH 02/26] tracing: Rename trace_buffer to array_buffer Steven Rostedt
2020-01-14 21:03 ` [for-next][PATCH 03/26] tracing: Make struct ring_buffer less ambiguous Steven Rostedt
2020-01-14 21:03 ` [for-next][PATCH 04/26] bootconfig: Add Extra Boot Config support Steven Rostedt
2020-02-06 11:54   ` Borislav Petkov
2020-02-06 14:41     ` Masami Hiramatsu
2020-02-06 17:20       ` Geert Uytterhoeven
2020-02-07  0:30         ` Masami Hiramatsu
2020-02-07  8:49           ` Geert Uytterhoeven
2020-02-07 13:17             ` Masami Hiramatsu
2020-02-07 14:28               ` [PATCH] bootconfig: Allocate xbc_nodes array dynamically Masami Hiramatsu
2020-02-06 17:58       ` [for-next][PATCH 04/26] bootconfig: Add Extra Boot Config support Borislav Petkov
2020-02-06 18:10         ` Randy Dunlap
2020-02-06 22:39           ` Steven Rostedt
2020-02-06 22:51             ` Borislav Petkov
2020-02-07  8:59             ` Geert Uytterhoeven
2020-02-07  2:46         ` Masami Hiramatsu
2020-02-07 11:41           ` Borislav Petkov
2020-02-07 15:06             ` Masami Hiramatsu
2020-02-10 11:25               ` Borislav Petkov
2020-02-10 15:10                 ` Masami Hiramatsu
2020-02-10 17:40                   ` Borislav Petkov
2020-02-11  2:02                     ` Masami Hiramatsu
2020-02-18 13:27                       ` Borislav Petkov
2020-02-18 17:57                         ` Steven Rostedt
2020-02-18 19:38                           ` Borislav Petkov
2020-02-19  2:26                             ` Masami Hiramatsu
2020-02-19  2:26                           ` Masami Hiramatsu
2020-02-19  2:26                         ` Masami Hiramatsu
2020-02-11  9:25                     ` Geert Uytterhoeven
2020-01-14 21:03 ` [for-next][PATCH 05/26] bootconfig: Load boot config from the tail of initrd Steven Rostedt
2020-01-14 21:03 ` [for-next][PATCH 06/26] tools: bootconfig: Add bootconfig command Steven Rostedt
2020-02-07 13:02   ` Michael Ellerman
2020-02-07 13:39     ` Masami Hiramatsu
2020-02-07 13:55     ` [PATCH] tools/bootconfig: Fix wrong __VA_ARGS__ usage Masami Hiramatsu
2020-02-08 11:10       ` Michael Ellerman
2020-02-09  4:09         ` Masami Hiramatsu
2020-02-09 13:05         ` [PATCH] tools/bootconfig: Suppress non-error messages Masami Hiramatsu
2020-02-10  2:06           ` Michael Ellerman
2020-02-10  7:18             ` Masami Hiramatsu
2020-02-10  9:50               ` Michael Ellerman
2020-02-10  9:50       ` [PATCH] tools/bootconfig: Fix wrong __VA_ARGS__ usage Michael Ellerman
2020-02-10 17:07         ` Steven Rostedt
2020-01-14 21:03 ` [for-next][PATCH 07/26] tools: bootconfig: Add bootconfig test script Steven Rostedt
2020-01-14 21:03 ` [for-next][PATCH 08/26] proc: bootconfig: Add /proc/bootconfig to show boot config list Steven Rostedt
2020-01-14 21:03 ` [for-next][PATCH 09/26] init/main.c: Alloc initcall_command_line in do_initcall() and free it Steven Rostedt
2020-01-14 21:03 ` [for-next][PATCH 10/26] bootconfig: init: Allow admin to use bootconfig for kernel command line Steven Rostedt
2020-01-14 21:03 ` [for-next][PATCH 11/26] bootconfig: init: Allow admin to use bootconfig for init " Steven Rostedt
2020-01-14 21:03 ` [for-next][PATCH 12/26] Documentation: bootconfig: Add a doc for extended boot config Steven Rostedt
2020-01-14 21:03 ` [for-next][PATCH 13/26] tracing: Apply soft-disabled and filter to tracepoints printk Steven Rostedt
2020-01-14 21:03 ` [for-next][PATCH 14/26] tracing: kprobes: Output kprobe event to printk buffer Steven Rostedt
2020-01-14 21:03 ` [for-next][PATCH 15/26] tracing: kprobes: Register to dynevent earlier stage Steven Rostedt
2020-01-14 21:03 ` [for-next][PATCH 16/26] tracing: Accept different type for synthetic event fields Steven Rostedt
2020-01-14 21:03 ` [for-next][PATCH 17/26] tracing: Add NULL trace-array check in print_synth_event() Steven Rostedt
2020-01-14 21:03 ` [for-next][PATCH 18/26] tracing/boot: Add boot-time tracing Steven Rostedt
2020-01-14 21:03 ` [for-next][PATCH 19/26] tracing/boot: Add per-event settings Steven Rostedt
2020-01-14 21:03 ` [for-next][PATCH 20/26] tracing/boot Add kprobe event support Steven Rostedt
2020-01-14 21:03 ` [for-next][PATCH 21/26] tracing/boot: Add synthetic " Steven Rostedt
2020-01-14 21:03 ` [for-next][PATCH 22/26] tracing/boot: Add instance node support Steven Rostedt
2020-01-14 21:03 ` [for-next][PATCH 23/26] tracing/boot: Add cpu_mask option support Steven Rostedt
2020-01-14 21:03 ` [for-next][PATCH 24/26] tracing/boot: Add function tracer filter options Steven Rostedt
2020-01-14 21:03 ` Steven Rostedt [this message]
2020-01-14 21:03 ` [for-next][PATCH 26/26] tracing: trigger: Replace unneeded RCU-list traversals Steven Rostedt
2020-01-14 22:11   ` Steven Rostedt

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20200114210339.338772772@goodmis.org \
    --to=rostedt@goodmis.org \
    --cc=akpm@linux-foundation.org \
    --cc=linux-kernel@vger.kernel.org \
    --cc=mhiramat@kernel.org \
    --cc=mingo@kernel.org \
    --subject='Re: [for-next][PATCH 25/26] Documentation: tracing: Add boot-time tracing document' \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

This is a public inbox, see mirroring instructions
on how to clone and mirror all data and code used for this inbox