linux-fsdevel.vger.kernel.org archive mirror
 help / color / mirror / Atom feed
From: Masami Hiramatsu <mhiramat@kernel.org>
To: Steven Rostedt <rostedt@goodmis.org>,
	Frank Rowand <frowand.list@gmail.com>
Cc: Ingo Molnar <mingo@redhat.com>,
	Namhyung Kim <namhyung@kernel.org>, Tim Bird <Tim.Bird@sony.com>,
	Jiri Olsa <jolsa@redhat.com>,
	Arnaldo Carvalho de Melo <acme@kernel.org>,
	Tom Zanussi <tom.zanussi@linux.intel.com>,
	Rob Herring <robh+dt@kernel.org>,
	Andrew Morton <akpm@linux-foundation.org>,
	Thomas Gleixner <tglx@linutronix.de>,
	Greg Kroah-Hartman <gregkh@linuxfoundation.org>,
	Alexey Dobriyan <adobriyan@gmail.com>,
	Jonathan Corbet <corbet@lwn.net>,
	Linus Torvalds <torvalds@linux-foundation.org>,
	linux-doc@vger.kernel.org, linux-fsdevel@vger.kernel.org,
	linux-kernel@vger.kernel.org
Subject: [RFC PATCH v3 19/19] Documentation: tracing: Add boot-time tracing document
Date: Mon, 26 Aug 2019 12:19:23 +0900	[thread overview]
Message-ID: <156678956359.21459.7183859111623533121.stgit@devnote2> (raw)
In-Reply-To: <156678933823.21459.4100380582025186209.stgit@devnote2>

Add a documentation about boot-time tracing options for
SKC file.

Signed-off-by: Masami Hiramatsu <mhiramat@kernel.org>
---
 Documentation/trace/boottime-trace.rst |  185 ++++++++++++++++++++++++++++++++
 1 file changed, 185 insertions(+)
 create mode 100644 Documentation/trace/boottime-trace.rst

diff --git a/Documentation/trace/boottime-trace.rst b/Documentation/trace/boottime-trace.rst
new file mode 100644
index 000000000000..fc074afd014e
--- /dev/null
+++ b/Documentation/trace/boottime-trace.rst
@@ -0,0 +1,185 @@
+.. 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 supplemental kernel cmdline (SKC) to describe tracing
+feature programming.
+
+Options in Supplemental Kernel Cmdline
+======================================
+
+Here is the list of available options list for boot time tracing in
+supplemental kenrel cmdline file [1]_. All options are under "ftrace."
+prefix to isolate from other subsystems.
+
+.. [1] See Documentation/admin-guide/skc.rst for details.
+
+Ftrace Global Options
+---------------------
+
+These options are only for global ftrace node since these are globally
+applied.
+
+ftrace.tp_printk;
+   Output trace-event data on printk buffer too.
+
+ftrace.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.
+
+ftrace.traceoff_on_warning;
+   Stop tracing if WARN_ON() occurs.
+
+ftrace.fgraph.filters = FILTER[, FILTER2...];
+   Add fgraph tracing function filters.
+
+ftrace.fgraph.notraces = FILTER[, FILTER2...];
+   Add fgraph non tracing function filters.
+
+ftrace.fgraph.max_depth = MAX_DEPTH;
+   Set MAX_DEPTH to maximum depth of fgraph tracer.
+
+
+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.]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 SKC 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 in module alpha, and others tracing module beta,
+you can write as below.
+
+::
+
+  ftrace.instance {
+        foo {
+                tracer = "function";
+                ftrace-filters = "*:mod:alpha";
+        }
+        bar {
+                tracer = "function";
+                ftrace-filters = "*:mod:beta";
+        }
+  }
+
+The instance node also accepts event nodes so that each instance
+can customize its event tracing.
+
+This boot-time trace also supports ftrace kernel parameters.
+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 SKC like below.
+
+::
+
+  ftrace {
+        options = sym-addr;
+        events = "initcall:*";
+        tp-printk;
+        buffer-size = 1MB;
+        ftrace-filters = "vfs*";
+  }
+
+However, since the initialization timing is different, if you need
+to trace very early boot, please use normal kernel parameters.


      parent reply	other threads:[~2019-08-26  3:19 UTC|newest]

Thread overview: 22+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2019-08-26  3:15 [RFC PATCH v3 00/19] tracing: skc: Boot-time tracing and Supplemental Kernel Cmdline Masami Hiramatsu
2019-08-26  3:15 ` [RFC PATCH v3 01/19] skc: Add supplemental kernel cmdline support Masami Hiramatsu
2019-08-26 13:27   ` Rob Herring
2019-08-27  2:37     ` Masami Hiramatsu
2019-08-26  3:16 ` [RFC PATCH v3 02/19] skc: Add /proc/sup_cmdline to show SKC key-value list Masami Hiramatsu
2019-08-26  3:16 ` [RFC PATCH v3 03/19] skc: Add a boot setup routine from cmdline Masami Hiramatsu
2019-08-26  3:16 ` [RFC PATCH v3 04/19] Documentation: skc: Add a doc for supplemental kernel cmdline Masami Hiramatsu
2019-08-26  3:16 ` [RFC PATCH v3 05/19] tracing: Apply soft-disabled and filter to tracepoints printk Masami Hiramatsu
2019-08-26  3:16 ` [RFC PATCH v3 06/19] tracing: kprobes: Output kprobe event to printk buffer Masami Hiramatsu
2019-08-26  3:17 ` [RFC PATCH v3 07/19] tracing: Expose EXPORT_SYMBOL_GPL symbol Masami Hiramatsu
2019-08-26  3:17 ` [RFC PATCH v3 08/19] tracing: kprobes: Register to dynevent earlier stage Masami Hiramatsu
2019-08-26  3:17 ` [RFC PATCH v3 09/19] tracing: Accept different type for synthetic event fields Masami Hiramatsu
2019-08-26  3:17 ` [RFC PATCH v3 10/19] tracing: Add NULL trace-array check in print_synth_event() Masami Hiramatsu
2019-08-26  3:17 ` [RFC PATCH v3 11/19] tracing/boot: Add boot-time tracing by supplemental kernel cmdline Masami Hiramatsu
2019-08-26  3:18 ` [RFC PATCH v3 12/19] tracing/boot: Add per-event settings Masami Hiramatsu
2019-08-26  3:18 ` [RFC PATCH v3 13/19] tracing/boot Add kprobe event support Masami Hiramatsu
2019-08-26  3:18 ` [RFC PATCH v3 14/19] tracing/boot: Add synthetic " Masami Hiramatsu
2019-08-26  3:18 ` [RFC PATCH v3 15/19] tracing/boot: Add instance node support Masami Hiramatsu
2019-08-26  3:18 ` [RFC PATCH v3 16/19] tracing/boot: Add cpu_mask option support Masami Hiramatsu
2019-08-26  3:18 ` [RFC PATCH v3 17/19] tracing/boot: Add function tracer filter options Masami Hiramatsu
2019-08-26  3:19 ` [RFC PATCH v3 18/19] tracing/boot: Add function-graph tracer options Masami Hiramatsu
2019-08-26  3:19 ` Masami Hiramatsu [this message]

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=156678956359.21459.7183859111623533121.stgit@devnote2 \
    --to=mhiramat@kernel.org \
    --cc=Tim.Bird@sony.com \
    --cc=acme@kernel.org \
    --cc=adobriyan@gmail.com \
    --cc=akpm@linux-foundation.org \
    --cc=corbet@lwn.net \
    --cc=frowand.list@gmail.com \
    --cc=gregkh@linuxfoundation.org \
    --cc=jolsa@redhat.com \
    --cc=linux-doc@vger.kernel.org \
    --cc=linux-fsdevel@vger.kernel.org \
    --cc=linux-kernel@vger.kernel.org \
    --cc=mingo@redhat.com \
    --cc=namhyung@kernel.org \
    --cc=robh+dt@kernel.org \
    --cc=rostedt@goodmis.org \
    --cc=tglx@linutronix.de \
    --cc=tom.zanussi@linux.intel.com \
    --cc=torvalds@linux-foundation.org \
    --subject='Re: [RFC PATCH v3 19/19] 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
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).