diff options
Diffstat (limited to 'Documentation')
45 files changed, 5839 insertions, 0 deletions
diff --git a/Documentation/.gitignore b/Documentation/.gitignore new file mode 100644 index 00000000..8a38b2ea --- /dev/null +++ b/Documentation/.gitignore @@ -0,0 +1,3 @@ +*.[1-9] +*.m +*.html diff --git a/Documentation/Makefile b/Documentation/Makefile new file mode 100644 index 00000000..ec364916 --- /dev/null +++ b/Documentation/Makefile @@ -0,0 +1,101 @@ +# SPDX-License-Identifier: GPL-2.0 + +doc_dir:=$(src)/Documentation + +export doc_dir + +SUBDIR += trace-cmd +SUBDIR += libtracecmd + +.PHONY: $(SUBDIR) + +DOCDIR = $(src)/Documentation +ASCIIDOC=asciidoc +ASCIIDOC_CONF = $(DOCDIR)/asciidoc.conf +ASCIIDOC_EXTRA = --unsafe -f $(ASCIIDOC_CONF) +ASCIIDOC_HTML = xhtml11 +MANPAGE_XSL = $(DOCDIR)/manpage-normal.xsl +XMLTO_EXTRA = +INSTALL?=install +RM ?= rm -f + +ASCIIDOC_INSTALLED := $(shell command -v $(ASCIIDOC) 2> /dev/null) +ifndef ASCIIDOC_INSTALLED + missing_tools += $(ASCIIDOC) +endif + +XMLTO=xmlto +XMLTO_INSTALLED := $(shell command -v $(XMLTO) 2> /dev/null) +ifndef XMLTO_INSTALLED + missing_tools += $(XMLTO) +endif + +# +# For asciidoc ... +# -7.1.2, no extra settings are needed. +# 8.0-, set ASCIIDOC8. +# + +# +# For docbook-xsl ... +# -1.68.1, set ASCIIDOC_NO_ROFF? (based on changelog from 1.73.0) +# 1.69.0, no extra settings are needed? +# 1.69.1-1.71.0, set DOCBOOK_SUPPRESS_SP? +# 1.71.1, no extra settings are needed? +# 1.72.0, set DOCBOOK_XSL_172. +# 1.73.0-, set ASCIIDOC_NO_ROFF +# + +# +# If you had been using DOCBOOK_XSL_172 in an attempt to get rid +# of 'the ".ft C" problem' in your generated manpages, and you +# instead ended up with weird characters around callouts, try +# using ASCIIDOC_NO_ROFF instead (it works fine with ASCIIDOC8). +# + +ifdef ASCIIDOC8 +ASCIIDOC_EXTRA += -a asciidoc7compatible +endif +ifdef DOCBOOK_XSL_172 +ASCIIDOC_EXTRA += -a libtracecmd-asciidoc-no-roff +MANPAGE_XSL = $(DOCDIR)/manpage-1.72.xsl +else + ifdef ASCIIDOC_NO_ROFF + # docbook-xsl after 1.72 needs the regular XSL, but will not + # pass-thru raw roff codes from asciidoc.conf, so turn them off. + ASCIIDOC_EXTRA += -a libtracecmd-asciidoc-no-roff + endif +endif +ifdef MAN_BOLD_LITERAL +XMLTO_EXTRA += -m $(DOCDIR)/manpage-bold-literal.xsl +endif +ifdef DOCBOOK_SUPPRESS_SP +XMLTO_EXTRA += -m $(DOCDIR)/manpage-suppress-sp.xsl +endif + +ifdef USE_ASCIIDOCTOR +ASCIIDOC = asciidoctor +ASCIIDOC_EXTRA = -a compat-mode +ASCIIDOC_EXTRA += -I. -rasciidoctor-extensions +ASCIIDOC_HTML = xhtml5 +endif + +ifneq ($(findstring $(MAKEFLAGS),w),w) +PRINT_DIR = --no-print-directory +else # "make -w" +NO_SUBDIR = : +endif + +export ASCIIDOC ASCIIDOC_CONF ASCIIDOC_EXTRA ASCIIDOC_HTML +export MANPAGE_XSL +export XMLTO XMLTO_INSTALLED XMLTO_EXTRA +export missing_tools +export RM + +all: $(SUBDIR) +clean: $(SUBDIR) +install: $(SUBDIR) + +$(SUBDIR): + make -C $@ $(MAKECMDGOALS) + diff --git a/Documentation/README.PythonPlugin b/Documentation/README.PythonPlugin new file mode 100644 index 00000000..3de05647 --- /dev/null +++ b/Documentation/README.PythonPlugin @@ -0,0 +1,127 @@ + PYTHON PLUGIN DOCUMENTATION +============================= + +With the python plugin (make python-plugin) you can now +write plugins in python. The API exported by the python +plugin itself (written in C) allows you to access most +information about a record from python. + +To write a python plugin, put a new .py file into a new +~/.trace-cmd/python/ directory. + +The most basic python plugin is this: + +--- %< --- +def register(pevent): + pass +--- >% --- + +which obviously does nothing at all. + +To register a callback, use the pevent.register_event_handler +function: + +--- %< --- +import tracecmd + +def my_event_handler(trace_seq, event): + pass + +def register(pevent): + pevent.register_event_handler("subsys", "event_name", + my_event_handler) +--- >% --- + + +There are four object types that you get, described below. + + tracecmd.PEvent +----------------- + +This is the class of the 'pevent' object above, +you get one of those via your register callback. +It has one method and one property: + * register_event_handler() - example above, to register + an event handler function + * file_endian - either '<' or '>' indicating + which endianness the file has, + to be used with struct.unpack() + + tracecmd.TraceSeq +------------------- + +This is the class of the 'trace_seq' parameter to your callback +function. It has only one method, puts(), to put data into the +buffer. Formatting must be done in python. + + tracecmd.Event +---------------------- + +This is the class of the 'event' parameter to your callback +function. Note that it doesn't just contain the format, but +also the event data. As such, you can do much with this, and +this is what you'll usually use. Each instance of this allows +access to record items via the dict protocol, and you can get +the items via its keys() methods. So for example, your +callback could be + +--- %< --- +def my_callback(trace_seq, event): + for fieldname in event.keys(): + field = event[fieldname] +--- >% --- + +Each field returned from the dict protocol is an instance of +the next (and last) class: + + tracecmd.Field +---------------------- + +This is an instance of a field, including its data. It affords +numerous use cases and is what you'll be using most. + + * If this is an integer field, i.e. 1, 2, 4 or 8 bytes long, + you can convert it to the number contained, according to + the file's endianness, by simply casting it to a long: + + field = event['myint'] + value = long(field) + + * You can access the field's data, as field.data, and if the + data is really a "__data_loc" type that will be resolved + automatically. (If you don't know what this means, don't + worry about it and just use field.data) + + +This is it. It's pretty simple. A fully-featured plugin could +look like this: + +--- %< --- +def my_event_handler(trace_seq, event): + trace_seq.puts("myev: %u", long(event['myfield'])) + +def register(pevent): + pevent.register_event_handler("subsys", "event_name", + my_event_handler) +--- >% --- + + + Tips and tricks +----------------- + +Be familiar with the struct module and use it, always +checking endianness and potentially using pevent.file_endian. + + +If you need access to pevent in your callbacks, simply +pass it in yourself: + +--- %< --- +def my_event_handler(pevent, trace_seq, event): + pass + +def register(pevent): + pevent.register_event_handler("subsys", "event_name", + lambda *args: my_event_handler(pevent, *args) + ) +--- >% --- diff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf new file mode 100644 index 00000000..c15aa13b --- /dev/null +++ b/Documentation/asciidoc.conf @@ -0,0 +1,120 @@ +## linktep: macro +# +# Usage: linktep:command[manpage-section] +# +# Note, {0} is the manpage section, while {target} is the command. +# +# Show TEP link as: <command>(<section>); if section is defined, else just show +# the command. + +[macros] +(?su)[\\]?(?P<name>linktep):(?P<target>\S*?)\[(?P<attrlist>.*?)\]= + +[attributes] +asterisk=* +plus=+ +caret=^ +startsb=[ +endsb=] +tilde=~ + +ifdef::backend-docbook[] +[linktep-inlinemacro] +{0%{target}} +{0#<citerefentry>} +{0#<refentrytitle>{target}</refentrytitle><manvolnum>{0}</manvolnum>} +{0#</citerefentry>} +endif::backend-docbook[] + +ifdef::backend-docbook[] +ifndef::tep-asciidoc-no-roff[] +# "unbreak" docbook-xsl v1.68 for manpages. v1.69 works with or without this. +# v1.72 breaks with this because it replaces dots not in roff requests. +[listingblock] +<example><title>{title}</title> +<literallayout> +ifdef::doctype-manpage[] + .ft C +endif::doctype-manpage[] +| +ifdef::doctype-manpage[] + .ft +endif::doctype-manpage[] +</literallayout> +{title#}</example> +endif::tep-asciidoc-no-roff[] + +ifdef::tep-asciidoc-no-roff[] +ifdef::doctype-manpage[] +# The following two small workarounds insert a simple paragraph after screen +[listingblock] +<example><title>{title}</title> +<literallayout> +| +</literallayout><simpara></simpara> +{title#}</example> + +[verseblock] +<formalpara{id? id="{id}"}><title>{title}</title><para> +{title%}<literallayout{id? id="{id}"}> +{title#}<literallayout> +| +</literallayout> +{title#}</para></formalpara> +{title%}<simpara></simpara> +endif::doctype-manpage[] +endif::tep-asciidoc-no-roff[] +endif::backend-docbook[] + +ifdef::doctype-manpage[] +ifdef::backend-docbook[] +[header] +template::[header-declarations] +<refentry> +<refmeta> +<refentrytitle>{mantitle}</refentrytitle> +<manvolnum>{manvolnum}</manvolnum> +<refmiscinfo class="source">libtracefs</refmiscinfo> +<refmiscinfo class="version">{libtracefs_version}</refmiscinfo> +<refmiscinfo class="manual">libtracefs Manual</refmiscinfo> +</refmeta> +<refnamediv> + <refname>{manname1}</refname> + <refname>{manname2}</refname> + <refname>{manname3}</refname> + <refname>{manname4}</refname> + <refname>{manname5}</refname> + <refname>{manname6}</refname> + <refname>{manname7}</refname> + <refname>{manname8}</refname> + <refname>{manname9}</refname> + <refname>{manname10}</refname> + <refname>{manname11}</refname> + <refname>{manname12}</refname> + <refname>{manname13}</refname> + <refname>{manname14}</refname> + <refname>{manname15}</refname> + <refname>{manname16}</refname> + <refname>{manname17}</refname> + <refname>{manname18}</refname> + <refname>{manname19}</refname> + <refname>{manname20}</refname> + <refname>{manname21}</refname> + <refname>{manname22}</refname> + <refname>{manname23}</refname> + <refname>{manname24}</refname> + <refname>{manname25}</refname> + <refname>{manname26}</refname> + <refname>{manname27}</refname> + <refname>{manname28}</refname> + <refname>{manname29}</refname> + <refname>{manname30}</refname> + <refpurpose>{manpurpose}</refpurpose> +</refnamediv> +endif::backend-docbook[] +endif::doctype-manpage[] + +ifdef::backend-xhtml11[] +[linktep-inlinemacro] +<a href="{target}.html">{target}{0?({0})}</a> +endif::backend-xhtml11[] diff --git a/Documentation/libtracecmd/Makefile b/Documentation/libtracecmd/Makefile new file mode 100644 index 00000000..48334525 --- /dev/null +++ b/Documentation/libtracecmd/Makefile @@ -0,0 +1,112 @@ +# SPDX-License-Identifier: GPL-2.0 + +# Include the utils +include $(src)/scripts/utils.mk + +# This Makefile and manpage XSL files were taken from libtracefs +# and modified for libtracecmd + +MAN3_TXT= \ + $(wildcard libtracecmd-*.txt) \ + libtracecmd.txt + +MAN_TXT = $(MAN3_TXT) +_MAN_XML=$(patsubst %.txt,%.xml,$(MAN_TXT)) +_MAN_HTML=$(patsubst %.txt,%.html,$(MAN_TXT)) +_DOC_MAN3=$(patsubst %.txt,%.m,$(MAN3_TXT)) + +MAN_XML=$(addprefix $(OUTPUT),$(_MAN_XML)) +MAN_HTML=$(addprefix $(OUTPUT),$(_MAN_HTML)) +DOC_MAN3=$(addprefix $(OUTPUT),$(_DOC_MAN3)) + +# Make the path relative to DESTDIR, not prefix +ifndef DESTDIR +prefix?=$(HOME) +endif +bindir?=$(prefix)/bin +htmldir?=$(prefix)/share/doc/libtracecmd-doc +pdfdir?=$(prefix)/share/doc/libtracecmd-doc +mandir?=$(prefix)/share/man +man3dir=$(mandir)/man3 + +ifdef USE_ASCIIDOCTOR +ASCIIDOC_EXTRA += -a mansource="libtracecmd" -a manmanual="libtracecmd Manual" +endif + +all: check-man-tools html man + +man: man3 +man3: $(DOC_MAN3) + +html: $(MAN_HTML) + +$(MAN_HTML) $(DOC_MAN3): $(ASCIIDOC_CONF) + +install: check-man-tools install-man install-html + +check-man-tools: +ifdef missing_tools + $(error "You need to install $(missing_tools) for man pages") +endif + +install-%.3: $(OUTPUT)%.3 + $(Q)$(call do_install_docs,$<,$(man3dir),644); + +do-install-man: man $(addprefix install-,$(wildcard $(OUTPUT)*.3)) + +install-man: man + $(Q)$(MAKE) -C . do-install-man + +install-%.txt: $(OUTPUT)%.html + $(Q)$(call do_install_docs,$<,$(htmldir),644); + +do-install-html: html $(addprefix install-,$(wildcard *.txt)) + +install-html: html do-install-html + +uninstall: uninstall-man uninstall-html + +uninstall-man: + $(Q)$(RM) $(addprefix $(DESTDIR)$(man3dir)/,$(DOC_MAN3)) + +uninstall-html: + $(Q)$(RM) $(addprefix $(DESTDIR)$(htmldir)/,$(MAN_HTML)) + +ifdef missing_tools + DO_INSTALL_MAN = $(warning Please install $(missing_tools) to have the man pages installed) +else + DO_INSTALL_MAN = do-install-man +endif + +CLEAN_FILES = \ + $(MAN_XML) $(addsuffix +,$(MAN_XML)) \ + $(MAN_HTML) $(addsuffix +,$(MAN_HTML)) \ + $(DOC_MAN3) *.3 *.m + +clean: + $(Q) $(RM) $(CLEAN_FILES) + +ifdef USE_ASCIIDOCTOR +$(OUTPUT)%.m : $(OUTPUT)%.txt + $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \ + $(ASCIIDOC) -b manpage -d manpage \ + $(ASCIIDOC_EXTRA) -alibtracecmd_version=$(LIBTRACECMD_VERSION) -o $@+ $< && \ + mv $@+ $@ +endif + +$(OUTPUT)%.m : $(OUTPUT)%.xml + $(QUIET_XMLTO)$(RM) $@ && \ + $(XMLTO) -o $(OUTPUT). -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $<; \ + touch $@ + +$(OUTPUT)%.xml : %.txt + $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \ + $(ASCIIDOC) -b docbook -d manpage \ + $(ASCIIDOC_EXTRA) -alibtracecmd_version=$(LIBTRACECMD_VERSION) -o $@+ $< && \ + mv $@+ $@ + +$(MAN_HTML): $(OUTPUT)%.html : %.txt + $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \ + $(ASCIIDOC) -b $(ASCIIDOC_HTML) -d manpage \ + $(ASCIIDOC_EXTRA) -alibtracecmd_version=$(LIBTRACECMD_VERSION) -o $@+ $< && \ + mv $@+ $@ diff --git a/Documentation/libtracecmd/libtracecmd-files.txt b/Documentation/libtracecmd/libtracecmd-files.txt new file mode 100644 index 00000000..2de5d6df --- /dev/null +++ b/Documentation/libtracecmd/libtracecmd-files.txt @@ -0,0 +1,169 @@ +libtracecmd(3) +============= + +NAME +---- +tracecmd_open, tracecmd_open_fd, tracecmd_open_head, tracecmd_init_data, +tracecmd_close - Open and close a trace file. + +SYNOPSIS +-------- +[verse] +-- +*#include <trace-cmd.h>* + +struct tracecmd_input pass:[*]*tracecmd_open*(const char pass:[*]_file_, int _flags_); +struct tracecmd_input pass:[*]*tracecmd_open_fd*(int _fd_, int _flags_); +struct tracecmd_input pass:[*]*tracecmd_open_head*(const char pass:[*]_file_, int _flags_); +int *tracecmd_init_data*(struct tracecmd_input pass:[*]_handle_); +void *tracecmd_close*(struct tracecmd_input pass:[*]_handle_); +-- + +DESCRIPTION +----------- +This set of APIs can be used to open and close a trace file recorded by +_trace-cmd(1)_ and containing tracing information from ftrace, the official +Linux kernel tracer. The opened file is represented by a _tracecmd_input_ +structure, all other library APIs that work with the file require a pointer +to the structure. The APIs for opening a trace file have a _flag_ input +parameter, which controls how the file will be opened and parsed. The _flag_ +is a combination of these options: + + TRACECMD_FL_LOAD_NO_PLUGINS - Do not load any plugins + TRACECMD_FL_LOAD_NO_SYSTEM_PLUGINS - Do not load system wide plugins, load only "local only" + plugins from user's home directory. + +The _tracecmd_open()_ function opens a given trace _file_, parses the +metadata headers from the file, allocates and initializes а _tracecmd_input_ +handler structure representing the file. It also initializes the handler +for reading trace data from the file. The returned handler is ready to be +used with _tracecmd_read__ APIs. + +The _tracecmd_open_fd()_ function does the same as _tracecmd_open()_, but +works with a file descriptor to a trace file, opened for reading. + +The _tracecmd_open_head()_ function is the same as _tracecmd_open()_, but +does not initialize the handler for reading trace data. It reads and parses +the metadata headers only. The _tracecmd_init_data()_ should be used before +using the _tracecmd_read__ APIs. + +The _tracecmd_init_data()_ function initializes a _handle_, allocated with +_tracecmd_open_head()_, for reading trace data from the file associated with +it. This API must be called before any of the _tracecmd_read__ APIs. + +The _tracecmd_close()_ function frees a _handle_, pointer to tracecmd_input +structure, previously allocated with _tracecmd_open()_, _tracecmd_open_fd()_ +or _tracecmd_open_head()_ APIs. + +RETURN VALUE +------------ +The _tracecmd_open()_, _tracecmd_open_fd()_ and _tracecmd_open_head()_ +functions return a pointer to tracecmd_input structure or NULL in case of +an error. The returned structure must be free with _tracecmd_close()_. +Note that if _tracecmd_open_fd()_ is used to allocate a tracecmd_input handler, +when _tracecmd_close()_ is called to close it, that fd will be closed also. + +The _tracecmd_init_data()_ function returns -1 in case of an error or +0 otherwise. + +EXAMPLE +------- +[source,c] +-- +The are two different use patterns for opening and reading trace data from +a trace file, which can be used depending on the use case. + +1. Open and initialise the trace file in а single step: + +#include <trace-cmd.h> +... +struct tracecmd_input *handle = tracecmd_open("trace.dat"); + if (!handle) { + /* Failed to open trace.dat file */ + } +... + /* Read tracing data from the file, using the handle */ +... + tracecmd_close(handle); +... +int fd; + fd = = open("trace.dat", O_RDONLY); + if (fd < 0) { + /* Failed to open trace file for reading */ + } + handle = tracecmd_open_fd(fd); + if (!handle) { + close(fd); + /* Failed to initialise handler for reading the trace file */ + } +... + /* Read tracing data from the file, using the handle */ +... + tracecmd_close(handle); +... + +2. Open and initialise the trace file in two steps. This allows to perform +some processing based on metadata, read from the file, before initialising +the trace data for reading. Example for such use case is when opening multiple +trace files recorded in a same trace session. In that case timestamps of all +trace events must be adjusted based on the information from the file's metadata +and before reading the trace data. + +#include <trace-cmd.h> +... +struct tracecmd_input *handle = tracecmd_open_head("trace.dat"); + if (!handle) { + /* Failed to open trace.dat file */ + } +... + /* do some processing, before initialising the trace data for reading */ +... + if (tracecmd_init_data(handle) < 0) { + /* Failed to initialize hadle for reading the trace data */ + } +... + /* Read tracing data from the file, using the handle */ +... + tracecmd_close(handle); +... +-- +FILES +----- +[verse] +-- +*trace-cmd.h* + Header file to include in order to have access to the library APIs. +*-ltracecmd* + Linker switch to add when building a program that uses the library. +-- + +SEE ALSO +-------- +_libtracefs(3)_, +_libtraceevent(3)_, +_trace-cmd(1)_ +_trace-cmd.dat(5)_ + +AUTHOR +------ +[verse] +-- +*Steven Rostedt* <rostedt@goodmis.org> +*Tzvetomir Stoyanov* <tz.stoyanov@gmail.com> +-- +REPORTING BUGS +-------------- +Report bugs to <linux-trace-devel@vger.kernel.org> + +LICENSE +------- +libtracecmd is Free Software licensed under the GNU LGPL 2.1 + +RESOURCES +--------- +https://git.kernel.org/pub/scm/utils/trace-cmd/trace-cmd.git/ + +COPYING +------- +Copyright \(C) 2020 VMware, Inc. Free use of this software is granted under +the terms of the GNU Public License (GPL). diff --git a/Documentation/libtracecmd/libtracecmd-instances.txt b/Documentation/libtracecmd/libtracecmd-instances.txt new file mode 100644 index 00000000..df8fdc4e --- /dev/null +++ b/Documentation/libtracecmd/libtracecmd-instances.txt @@ -0,0 +1,129 @@ +libtracecmd(3) +============= + +NAME +---- +tracecmd_buffer_instances, tracecmd_buffer_instance_name, tracecmd_buffer_instance_handle +- Read tracing instances from a trace file. + +SYNOPSIS +-------- +[verse] +-- +*#include <trace-cmd.h>* + +int *tracecmd_buffer_instances*(struct tracecmd_input pass:[*]_handle_); +const char pass:[*]*tracecmd_buffer_instance_name*(struct tracecmd_input pass:[*]_handle_, int _indx_); +struct tracecmd_input pass:[*]*tracecmd_buffer_instance_handle*(struct tracecmd_input pass:[*]_handle_, int _indx_); +-- + +DESCRIPTION +----------- +This set of APIs can be used to get information and read tracing data +from tracing instances stored in a trace file. + +The _tracecmd_buffer_instances()_ function gets the number of tracing +instances recorded in a trace file. The top instance is not counted. +The _handle_ is a tracecmd_input handler returned by +_tracecmd_open_head()_. + +The _tracecmd_buffer_instance_name()_ function gets the name of the +tracing instance with given index _indx_, recorded in a trace file. +The _indx_ is a number in the interval [0 .. count-1], where count +is the number returned by _tracecmd_buffer_instances()_. The _handle_ +is a tracecmd_input handler returned by _tracecmd_open_head()_. + +The _tracecmd_buffer_instance_handle()_ allocates and initializes a +tracecmd_input handle, associated with trace instance with index +_indx_ from a trace file. The _handle_ is a tracecmd_input handler +returned by _tracecmd_open_head()_. The _indx_ is a number in the +interval [0 .. count-1], where count is the number returned by +_tracecmd_buffer_instances()_. + +RETURN VALUE +------------ +The _tracecmd_buffer_instances()_ function returns the number of tracing +instances recorded in a trace file. + +The _tracecmd_buffer_instance_name()_ function returns a string, the name +of a tracing instance, or NULL in case of an error The string must *not* +be freed. + +The _tracecmd_buffer_instance_handle()_ function returns a pointer to +newly allocated tracecmd_input handler or NULL in case if an error. The +returned handler must be closed by _tracecmd_close()(3)_ + +EXAMPLE +------- +[source,c] +-- +#include <trace-cmd.h> +... +struct tracecmd_input *handle = tracecmd_open_head("trace.dat"); + if (!handle) { + /* Failed to open trace.dat file */ + } +... +int num = tracecmd_buffer_instances(handle); + + while(num) { + struct tracecmd_input *h; + char *name; + + name = tracecmd_buffer_instance_name(handle, num); + if (!name) { + /* Failed to get name of instance num */ + } + h = tracecmd_buffer_instance_handle(handle, num); + if (!h) { + /* Failed to initialize handler for instance num */ + } + + ... + tracecmd_close(h); + num--; + } +... + tracecmd_close(handle); + +-- +FILES +----- +[verse] +-- +*trace-cmd.h* + Header file to include in order to have access to the library APIs. +*-ltracecmd* + Linker switch to add when building a program that uses the library. +-- + +SEE ALSO +-------- +_libtracefs(3)_, +_libtraceevent(3)_, +_trace-cmd(1)_ +_trace-cmd.dat(5)_ + +AUTHOR +------ +[verse] +-- +*Steven Rostedt* <rostedt@goodmis.org> +*Tzvetomir Stoyanov* <tz.stoyanov@gmail.com> +-- +REPORTING BUGS +-------------- +Report bugs to <linux-trace-devel@vger.kernel.org> + +LICENSE +------- +libtracecmd is Free Software licensed under the GNU LGPL 2.1 + +RESOURCES +--------- +https://git.kernel.org/pub/scm/utils/trace-cmd/trace-cmd.git/ + +COPYING +------- +Copyright \(C) 2020 VMware, Inc. Free use of this software is granted under +the terms of the GNU Public License (GPL). diff --git a/Documentation/libtracecmd/libtracecmd-log.txt b/Documentation/libtracecmd/libtracecmd-log.txt new file mode 100644 index 00000000..de5c2776 --- /dev/null +++ b/Documentation/libtracecmd/libtracecmd-log.txt @@ -0,0 +1,78 @@ +libtracecmd(3) +============= + +NAME +---- +tracecmd_set_loglevel - Set log level of the library + +SYNOPSIS +-------- +[verse] +-- +*#include <trace-cmd.h>* + +int *tracecmd_set_loglevel*(enum tep_loglevel _level_); +-- + +DESCRIPTION +----------- +The _tracecmd_set_loglevel()_ function sets the level of the library logs that will be printed on +the console. See _libtraceevent(3)_ for detailed desciription of the log levels. Setting the log +level to specific value means that logs from the previous levels will be printed too. For example +_TEP_LOG_WARNING_ will print any logs with severity _TEP_LOG_WARNING_, _TEP_LOG_ERROR_ and +_TEP_LOG_CRITICAL_. The default log level is _TEP_LOG_CRITICAL_. When a new level is set, it is +also propagated to the libtracefs and libtraceevent. + +EXAMPLE +------- +[source,c] +-- +#include <trace-cmd.h> +... +tracecmd_set_loglevel(TEP_LOG_ALL); +... +/* call libtracecmd, libtracefs or libtraceevent APIs and observe any logs they produce */ +... +tracecmd_set_loglevel(TEP_LOG_CRITICAL); +-- + +FILES +----- +[verse] +-- +*trace-cmd.h* + Header file to include in order to have access to the library APIs. +*-ltracecmd* + Linker switch to add when building a program that uses the library. +-- + +SEE ALSO +-------- +_libtracefs(3)_, +_libtraceevent(3)_, +_trace-cmd(1)_ +_trace-cmd.dat(5)_ + +AUTHOR +------ +[verse] +-- +*Steven Rostedt* <rostedt@goodmis.org> +*Tzvetomir Stoyanov* <tz.stoyanov@gmail.com> +-- +REPORTING BUGS +-------------- +Report bugs to <linux-trace-devel@vger.kernel.org> + +LICENSE +------- +libtracecmd is Free Software licensed under the GNU LGPL 2.1 + +RESOURCES +--------- +https://git.kernel.org/pub/scm/utils/trace-cmd/trace-cmd.git/ + +COPYING +------- +Copyright \(C) 2021 VMware, Inc. Free use of this software is granted under +the terms of the GNU Public License (GPL). diff --git a/Documentation/libtracecmd/libtracecmd-peer.txt b/Documentation/libtracecmd/libtracecmd-peer.txt new file mode 100644 index 00000000..2e3232c6 --- /dev/null +++ b/Documentation/libtracecmd/libtracecmd-peer.txt @@ -0,0 +1,137 @@ +libtracecmd(3) +============= + +NAME +---- +tracecmd_get_traceid, tracecmd_get_guest_cpumap - Manage trace session with multiple trace peers, +recorded in multiple trace files. + +SYNOPSIS +-------- +[verse] +-- +*#include <trace-cmd.h>* + +unsigned long long *tracecmd_get_traceid*(struct tracecmd_input pass:[*]_handle_); +int *tracecmd_get_guest_cpumap*(struct tracecmd_input pass:[*]_handle_, unsigned long long _trace_id_, const char pass:[*]pass:[*]_name_, int pass:[*]_vcpu_count_, const int pass:[*]pass:[*]_cpu_pid_); +-- + +DESCRIPTION +----------- +This set of APIs can be used to manage a trace session with multiple trace +peers, for example, tracing both a host and one or more guest virtual machines. +The trace data of each peer from the session is recorded in separate trace files. +Information about peers from the session is stored in the metadata of each +trace file. These APIs use that information to extract and synchronize +the trace data. + +The _tracecmd_get_traceid()_ function returns the trace ID stored in +the trace file metadata associated with _handle_. Each peer from a trace +session has an ID unique for that peer and that trace session only. +This ID is used to match multiple trace files recorded in a same trace +session. + +The _tracecmd_get_guest_cpumap()_ function gets the mapping of guest +virtual CPUs (VCPU) to the host process that represents those VCPUs and is +stored in the metadata of the trace file associated with _handle_. This +information is gathered during a host-guest trace session and is stored +in the host trace file. The _trace_id_ parameter is the trace ID of the guest +in this particular trace session. If a guest with that ID was part of that +session, its VCPU to host process mapping is in the host trace file and the +information is returned in _name_, _vcpu_count_ and _cpu_pid_ parameters. +The _name_ parameter contains the name of the guest, the _vcpu_count_ contains +the count of VCPUs of that guest and the _cpu_pid_ array contains the VCPU to +host process mapping. The array is of size _vcpu_count_ where the index is VCPU +and the value is the process ID (PID) of the host process, running that VCPU. +The _name_, _vcpu_count_ and _cpu_pid_ values must *not* be freed. + +RETURN VALUE +------------ +The _tracecmd_get_traceid()_ function returns a 64 bit trace ID. + +The _tracecmd_get_guest_cpumap()_ function returns -1 in case of +an error or 0 otherwise. If 0 is returned, then the _name_, _vcpu_count_ +and _cpu_pid_ parameters contain the requested information. + +EXAMPLE +------- +[source,c] +-- +#include <trace-cmd.h> +... +struct tracecmd_input *host = tracecmd_open("trace.dat"); + if (!host) { + /* Failed to open host trace file */ + } + +struct tracecmd_input *guest1 = tracecmd_open_head("trace-Guest1.dat"); + if (!guest1) { + /* Failed to open guest1 trace file */ + } +struct tracecmd_input *guest2 = tracecmd_open_head("trace-Guest2.dat"); + if (!guest2) { + /* Failed to open guest2 trace file */ + } + +unsigned long long guest_id_1 = tracecmd_get_traceid(guest1); +unsigned long long guest_id_2 = tracecmd_get_traceid(guest2); +int *cpu_pid_1, *cpu_pid_2; +int vcount_1, vcount_2; +char *name_1, *name_2; + + if (!tracecmd_get_guest_cpumap(host, guest_id_1, &name_1, &vcount_1, &cpu_pid_1)) { + /* The Host and a guest1 with name_1 are part of the same trace session. + * Got guest1 VCPU to host PID mapping. + */ + } + if (!tracecmd_get_guest_cpumap(host, guest_id_2, &name_2, &vcount_2, &cpu_pid_2)) { + /* The Host and a guest2 with name_2 are part of the same trace session. + * Got guest2 VCPU to host PID mapping. + */ + } +... + tracecmd_close(guest1); + tracecmd_close(guest2); + tracecmd_close(handle); + +-- +FILES +----- +[verse] +-- +*trace-cmd.h* + Header file to include in order to have access to the library APIs. +*-ltracecmd* + Linker switch to add when building a program that uses the library. +-- + +SEE ALSO +-------- +_libtracefs(3)_, +_libtraceevent(3)_, +_trace-cmd(1)_ +_trace-cmd.dat(5)_ + +AUTHOR +------ +[verse] +-- +*Steven Rostedt* <rostedt@goodmis.org> +*Tzvetomir Stoyanov* <tz.stoyanov@gmail.com> +-- +REPORTING BUGS +-------------- +Report bugs to <linux-trace-devel@vger.kernel.org> + +LICENSE +------- +libtracecmd is Free Software licensed under the GNU LGPL 2.1 + +RESOURCES +--------- +https://git.kernel.org/pub/scm/utils/trace-cmd/trace-cmd.git/ + +COPYING +------- +Copyright \(C) 2020 VMware, Inc. Free use of this software is granted under +the terms of the GNU Public License (GPL). diff --git a/Documentation/libtracecmd/libtracecmd-record.txt b/Documentation/libtracecmd/libtracecmd-record.txt new file mode 100644 index 00000000..aa1a4a66 --- /dev/null +++ b/Documentation/libtracecmd/libtracecmd-record.txt @@ -0,0 +1,138 @@ +libtracecmd(3) +============= + +NAME +---- +tracecmd_read_cpu_first, tracecmd_read_data, tracecmd_read_at, +tracecmd_free_record, tracecmd_get_tep - Read recorded events from a trace file. + +SYNOPSIS +-------- +[verse] +-- +*#include <trace-cmd.h>* + +struct tep_record pass:[*]*tracecmd_read_cpu_first*(struct tracecmd_input pass:[*]_handle_, int _cpu_); +struct tep_record pass:[*]*tracecmd_read_data*(struct tracecmd_input pass:[*]_handle_, int _cpu_); +struct tep_record pass:[*]*tracecmd_read_at*(struct tracecmd_input pass:[*]_handle_, unsigned long long _offset_, int pass:[*]_cpu_); +void *tracecmd_free_record*(struct tep_record pass:[*]_record_); +struct tep_handle pass:[*]*tracecmd_get_tep*(struct tracecmd_input pass:[*]_handle_); +-- + +DESCRIPTION +----------- +This set of APIs can be used to read tracing data from a trace file opened +with _tracecmd_open()(3)_, _tracecmd_open_fd()(3)_ or _tracecmd_open_head()(3)_. + +The _tracecmd_read_cpu_first()_ function reads the first trace record +for a given _cpu_ from a trace file associated with _handle_. The returned +record must be freed with _tracecmd_free_record()_. + +The _tracecmd_read_data()_ function reads the next trace record for +a given _cpu_ from a trace file associated with _handle_ and increments +the read location pointer, so that the next call to _tracecmd_read_data()_ +will not read the same record again. The returned record must be freed +with _tracecmd_free_record()_. + +The _tracecmd_read_at()_ function reads a trace record from a specific +_offset_ within the file associated with _handle_. The CPU on which the +recorded event occurred is stored in the _cpu_. The function does not +change the current read location pointer. The returned record must be +freed with _tracecmd_free_record()_. + +The _tracecmd_free_record()_ function frees a _record_ returned by any +of the _tracecmd_read__ APIs. + +The _tracecmd_get_tep()_ function returns a tep context for a given +_handle_. + +RETURN VALUE +------------ +The _tracecmd_read_cpu_first()_, _tracecmd_read_data()_ and +_tracecmd_read_at()_ functions return a pointer to struct tep_record or +NULL in case of an error.The returned record must be freed with +_tracecmd_free_record()_. + +The _tracecmd_get_tep()_ function returns a pointer to tep context or +NULL if there is no tep context for the given _handle_. The returned +tep pointer must *not* be freed. + +EXAMPLE +------- +[source,c] +-- +#include <trace-cmd.h> +... +struct tracecmd_input *handle = tracecmd_open("trace.dat"); + if (!handle) { + /* Failed to open trace.dat file */ + } +... +unsigned long long offset = 0; +struct tep_record *rec; +int cpu = 0; + rec = tracecmd_read_cpu_first(handle, cpu); + while (rec) { + ... + if ( /* some interesting record noticed */) { + /* store the offset of the interesting record */ + offset = rec->offset; + } + ... + tracecmd_free_record(rec); + rec = tracecmd_read_data(handle, cpu); + } + ... + if (offset) { + rec = tracecmd_read_at(handle, offset, &cpu); + if (rec) { + /* Got record at offset on cpu */ + ... + tracecmd_free_record(rec); + } + } + +... + tracecmd_close(hadle); + +-- +FILES +----- +[verse] +-- +*trace-cmd.h* + Header file to include in order to have access to the library APIs. +*-ltracecmd* + Linker switch to add when building a program that uses the library. +-- + +SEE ALSO +-------- +_libtracefs(3)_, +_libtraceevent(3)_, +_trace-cmd(1)_ +_trace-cmd.dat(5)_ + +AUTHOR +------ +[verse] +-- +*Steven Rostedt* <rostedt@goodmis.org> +*Tzvetomir Stoyanov* <tz.stoyanov@gmail.com> +-- +REPORTING BUGS +-------------- +Report bugs to <linux-trace-devel@vger.kernel.org> + +LICENSE +------- +libtracecmd is Free Software licensed under the GNU LGPL 2.1 + +RESOURCES +--------- +https://git.kernel.org/pub/scm/utils/trace-cmd/trace-cmd.git/ + +COPYING +------- +Copyright \(C) 2020 VMware, Inc. Free use of this software is granted under +the terms of the GNU Public License (GPL). diff --git a/Documentation/libtracecmd/libtracecmd.txt b/Documentation/libtracecmd/libtracecmd.txt new file mode 100644 index 00000000..dc528ce0 --- /dev/null +++ b/Documentation/libtracecmd/libtracecmd.txt @@ -0,0 +1,86 @@ +libtracecmd(3) +============= + +NAME +---- +libtracecmd - trace-cmd library APIs + +SYNOPSIS +-------- +[verse] +-- +*#include <trace-cmd.h>* + +Open and close trace file: + struct tracecmd_input pass:[*]*tracecmd_open*(const char pass:[*]_file_, int _flags_); + struct tracecmd_input pass:[*]*tracecmd_open_fd*(int _fd_, int _flags_); + struct tracecmd_input pass:[*]*tracecmd_open_head*(const char pass:[*]_file_, int _flags_); + void *tracecmd_close*(struct tracecmd_input pass:[*]_handle_); + +Read tracing records from a trace file: + int *tracecmd_init_data*(struct tracecmd_input pass:[*]_handle_); + struct tep_record pass:[*]*tracecmd_read_cpu_first*(struct tracecmd_input pass:[*]_handle_, int _cpu_); + struct tep_record pass:[*]*tracecmd_read_data*(struct tracecmd_input pass:[*]_handle_, int _cpu_); + struct tep_record pass:[*]*tracecmd_read_at*(struct tracecmd_input pass:[*]_handle_, unsigned long long _offset_, int pass:[*]_cpu_); + void *tracecmd_free_record*(struct tep_record pass:[*]_record_); + struct tep_handle pass:[*]*tracecmd_get_tep*(struct tracecmd_input pass:[*]_handle_); + +Read tracing instances from a trace file: + int *tracecmd_buffer_instances*(struct tracecmd_input pass:[*]_handle_); + const char pass:[*]*tracecmd_buffer_instance_name*(struct tracecmd_input pass:[*]_handle_, int _indx_); + struct tracecmd_input pass:[*]*tracecmd_buffer_instance_handle*(struct tracecmd_input pass:[*]_handle_, int _indx_); + +Get traceing peer information from a trace file: + unsigned long long *tracecmd_get_traceid*(struct tracecmd_input pass:[*]_handle_); + int *tracecmd_get_guest_cpumap*(struct tracecmd_input pass:[*]_handle_, unsigned long long _trace_id_, const char pass:[*]pass:[*]_name_, int pass:[*]_vcpu_count_, const int pass:[*]pass:[*]_cpu_pid_); + +Control library logs: + int *tracecmd_set_loglevel*(enum tep_loglevel _level_); +-- + +DESCRIPTION +----------- +The libtracecmd(3) library provides APIs to read, parse and write +_trace-cmd.dat(5)_ files, recorded with _trace-cmd(1)_ application and containing +tracing information from ftrace, the official Linux kernel tracer. + +FILES +----- +[verse] +-- +*trace-cmd.h* + Header file to include in order to have access to the library APIs. +*-ltracecmd* + Linker switch to add when building a program that uses the library. +-- + +SEE ALSO +-------- +_libtraceevent(3)_ +_libtracefs(3)_ +_trace-cmd(1)_ +_trace-cmd.dat(5)_ + +AUTHOR +------ +[verse] +-- +*Steven Rostedt* <rostedt@goodmis.org> +*Tzvetomir Stoyanov* <tz.stoyanov@gmail.com> +-- +REPORTING BUGS +-------------- +Report bugs to <linux-trace-devel@vger.kernel.org> + +LICENSE +------- +libtracecmd is Free Software licensed under the GNU LGPL 2.1 + +RESOURCES +--------- +https://git.kernel.org/pub/scm/utils/trace-cmd/trace-cmd.git/ + +COPYING +------- +Copyright \(C) 2020 VMware, Inc. Free use of this software is granted under +the terms of the GNU Public License (GPL). diff --git a/Documentation/manpage-1.72.xsl b/Documentation/manpage-1.72.xsl new file mode 100644 index 00000000..b4d315cb --- /dev/null +++ b/Documentation/manpage-1.72.xsl @@ -0,0 +1,14 @@ +<!-- manpage-1.72.xsl: + special settings for manpages rendered from asciidoc+docbook + handles peculiarities in docbook-xsl 1.72.0 --> +<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" + version="1.0"> + +<xsl:import href="manpage-base.xsl"/> + +<!-- these are the special values for the roff control characters + needed for docbook-xsl 1.72.0 --> +<xsl:param name="git.docbook.backslash">▓</xsl:param> +<xsl:param name="git.docbook.dot" >⌂</xsl:param> + +</xsl:stylesheet> diff --git a/Documentation/manpage-base.xsl b/Documentation/manpage-base.xsl new file mode 100644 index 00000000..a264fa61 --- /dev/null +++ b/Documentation/manpage-base.xsl @@ -0,0 +1,35 @@ +<!-- manpage-base.xsl: + special formatting for manpages rendered from asciidoc+docbook --> +<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" + version="1.0"> + +<!-- these params silence some output from xmlto --> +<xsl:param name="man.output.quietly" select="1"/> +<xsl:param name="refentry.meta.get.quietly" select="1"/> + +<!-- convert asciidoc callouts to man page format; + git.docbook.backslash and git.docbook.dot params + must be supplied by another XSL file or other means --> +<xsl:template match="co"> + <xsl:value-of select="concat( + $git.docbook.backslash,'fB(', + substring-after(@id,'-'),')', + $git.docbook.backslash,'fR')"/> +</xsl:template> +<xsl:template match="calloutlist"> + <xsl:value-of select="$git.docbook.dot"/> + <xsl:text>sp </xsl:text> + <xsl:apply-templates/> + <xsl:text> </xsl:text> +</xsl:template> +<xsl:template match="callout"> + <xsl:value-of select="concat( + $git.docbook.backslash,'fB', + substring-after(@arearefs,'-'), + '. ',$git.docbook.backslash,'fR')"/> + <xsl:apply-templates/> + <xsl:value-of select="$git.docbook.dot"/> + <xsl:text>br </xsl:text> +</xsl:template> + +</xsl:stylesheet> diff --git a/Documentation/manpage-bold-literal.xsl b/Documentation/manpage-bold-literal.xsl new file mode 100644 index 00000000..608eb5df --- /dev/null +++ b/Documentation/manpage-bold-literal.xsl @@ -0,0 +1,17 @@ +<!-- manpage-bold-literal.xsl: + special formatting for manpages rendered from asciidoc+docbook --> +<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" + version="1.0"> + +<!-- render literal text as bold (instead of plain or monospace); + this makes literal text easier to distinguish in manpages + viewed on a tty --> +<xsl:template match="literal"> + <xsl:value-of select="$git.docbook.backslash"/> + <xsl:text>fB</xsl:text> + <xsl:apply-templates/> + <xsl:value-of select="$git.docbook.backslash"/> + <xsl:text>fR</xsl:text> +</xsl:template> + +</xsl:stylesheet> diff --git a/Documentation/manpage-normal.xsl b/Documentation/manpage-normal.xsl new file mode 100644 index 00000000..a48f5b11 --- /dev/null +++ b/Documentation/manpage-normal.xsl @@ -0,0 +1,13 @@ +<!-- manpage-normal.xsl: + special settings for manpages rendered from asciidoc+docbook + handles anything we want to keep away from docbook-xsl 1.72.0 --> +<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" + version="1.0"> + +<xsl:import href="manpage-base.xsl"/> + +<!-- these are the normal values for the roff control characters --> +<xsl:param name="git.docbook.backslash">\</xsl:param> +<xsl:param name="git.docbook.dot" >.</xsl:param> + +</xsl:stylesheet> diff --git a/Documentation/manpage-suppress-sp.xsl b/Documentation/manpage-suppress-sp.xsl new file mode 100644 index 00000000..a63c7632 --- /dev/null +++ b/Documentation/manpage-suppress-sp.xsl @@ -0,0 +1,21 @@ +<!-- manpage-suppress-sp.xsl: + special settings for manpages rendered from asciidoc+docbook + handles erroneous, inline .sp in manpage output of some + versions of docbook-xsl --> +<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" + version="1.0"> + +<!-- attempt to work around spurious .sp at the tail of the line + that some versions of docbook stylesheets seem to add --> +<xsl:template match="simpara"> + <xsl:variable name="content"> + <xsl:apply-templates/> + </xsl:variable> + <xsl:value-of select="normalize-space($content)"/> + <xsl:if test="not(ancestor::authorblurb) and + not(ancestor::personblurb)"> + <xsl:text> </xsl:text> + </xsl:if> +</xsl:template> + +</xsl:stylesheet> diff --git a/Documentation/trace-cmd/Makefile b/Documentation/trace-cmd/Makefile new file mode 100644 index 00000000..1568af53 --- /dev/null +++ b/Documentation/trace-cmd/Makefile @@ -0,0 +1,132 @@ +# SPDX-License-Identifier: GPL-2.0 + +# Include the utils +include $(src)/scripts/utils.mk + +# This Makefile and manpage XSL files were taken from libtracefs +# and modified for libtracecmd + +MAN1_TXT= \ + $(wildcard trace-cmd*.1.txt) + +MAN5_TXT= \ + $(wildcard trace-cmd*.5.txt) + +MAN_TXT = $(MAN1_TXT) $(MAN5_TXT) +_MAN_XML=$(patsubst %.txt,%.xml,$(MAN_TXT)) +_MAN_HTML=$(patsubst %.txt,%.html,$(MAN_TXT)) +_DOC_MAN1=$(patsubst %.1.txt,%.1,$(MAN1_TXT)) +_DOC_MAN5=$(patsubst %.5.txt,%.5,$(MAN5_TXT)) + +MAN_XML=$(addprefix $(OUTPUT),$(_MAN_XML)) +MAN_HTML=$(addprefix $(OUTPUT),$(_MAN_HTML)) +DOC_MAN1=$(addprefix $(OUTPUT),$(_DOC_MAN1)) +DOC_MAN5=$(addprefix $(OUTPUT),$(_DOC_MAN5)) + +# Make the path relative to DESTDIR, not prefix +ifndef DESTDIR +prefix?=$(HOME) +endif +bindir?=$(prefix)/bin +htmldir?=$(prefix)/share/doc/trace-cmd +pdfdir?=$(prefix)/share/doc/trace-cmd +mandir?=$(prefix)/share/man +man1dir=$(mandir)/man1 +man5dir=$(mandir)/man5 + +ifdef USE_ASCIIDOCTOR +ASCIIDOC_EXTRA += -a mansource="libtracecmd" -a manmanual="libtracecmd Manual" +endif + +all: check-man-tools html man + +man: man1 man5 +man1: $(DOC_MAN1) +man5: $(DOC_MAN5) + +html: $(MAN_HTML) + +$(MAN_HTML) $(DOC_MAN1) $(DOC_MAN5): $(ASCIIDOC_CONF) + +install: check-man-tools install-man install-html + +check-man-tools: +ifdef missing_tools + $(error "You need to install $(missing_tools) for man pages") +endif + +install-%.1: $(OUTPUT)%.1 + $(Q)$(call do_install_docs,$<,$(man1dir),644); + +install-%.5: $(OUTPUT)%.5 + $(Q)$(call do_install_docs,$<,$(man5dir),644); + +do-install-man: man $(addprefix install-,$(wildcard $(OUTPUT)*.1)) \ + $(addprefix install-,$(wildcard $(OUTPUT)*.5)) + +install-man: man + $(Q)$(MAKE) -C . do-install-man + +install-%.txt: $(OUTPUT)%.html + $(Q)$(call do_install_docs,$<,$(htmldir),644); + +do-install-html: html $(addprefix install-,$(wildcard *.txt)) + +install-html: html do-install-html + +uninstall: uninstall-man uninstall-html + +uninstall-man: + $(Q)$(RM) $(addprefix $(DESTDIR)$(man1dir)/,$(DOC_MAN1)) + $(Q)$(RM) $(addprefix $(DESTDIR)$(man5dir)/,$(DOC_MAN5)) + +uninstall-html: + $(Q)$(RM) $(addprefix $(DESTDIR)$(htmldir)/,$(MAN_HTML)) + +ifdef missing_tools + DO_INSTALL_MAN = $(warning Please install $(missing_tools) to have the man pages installed) +else + DO_INSTALL_MAN = do-install-man +endif + +CLEAN_FILES = \ + $(MAN_XML) $(addsuffix +,$(MAN_XML)) \ + $(MAN_HTML) $(addsuffix +,$(MAN_HTML)) \ + $(DOC_MAN1) $(DOC_MAN5) *.1 *.5 + +clean: + $(Q) $(RM) $(CLEAN_FILES) + +ifdef USE_ASCIIDOCTOR +$(OUTPUT)%.1 : $(OUTPUT)%.1.txt + $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \ + $(ASCIIDOC) -b manpage -d manpage \ + $(ASCIIDOC_EXTRA) -atracecmd_version=$(TRACECMD_VERSION) -o $@+ $< && \ + mv $@+ $@ + +$(OUTPUT)%.5 : $(OUTPUT)%.5.txt + $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \ + $(ASCIIDOC) -b manpage -d manpage \ + $(ASCIIDOC_EXTRA) -atracecmd_version=$(TRACECMD_VERSION) -o $@+ $< && \ + mv $@+ $@ +endif + +$(OUTPUT)%.1 : $(OUTPUT)%.1.xml + $(QUIET_XMLTO)$(RM) $@ && \ + $(XMLTO) -o $(OUTPUT). -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $<; \ + +$(OUTPUT)%.5 : $(OUTPUT)%.5.xml + $(QUIET_XMLTO)$(RM) $@ && \ + $(XMLTO) -o $(OUTPUT). -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $<; \ + +$(OUTPUT)%.xml : %.txt + $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \ + $(ASCIIDOC) -b docbook -d manpage \ + $(ASCIIDOC_EXTRA) -atracecmd_version=$(TRACECMD_VERSION) -o $@+ $< && \ + mv $@+ $@ + +$(MAN_HTML): $(OUTPUT)%.html : %.txt + $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \ + $(ASCIIDOC) -b $(ASCIIDOC_HTML) -d manpage \ + $(ASCIIDOC_EXTRA) -atracecmd_version=$(TRACECMD_VERSION) -o $@+ $< && \ + mv $@+ $@ diff --git a/Documentation/trace-cmd/trace-cmd-agent.1.txt b/Documentation/trace-cmd/trace-cmd-agent.1.txt new file mode 100644 index 00000000..f247d41d --- /dev/null +++ b/Documentation/trace-cmd/trace-cmd-agent.1.txt @@ -0,0 +1,62 @@ +TRACE-CMD-AGENT(1) +================== + +NAME +---- +trace-cmd-agent - Run as an agent on a machine (to be controlled by another machine) + +SYNOPSIS +-------- +*trace-cmd agent* ['OPTIONS'] + +DESCRIPTION +----------- +The trace-cmd(1) agent listens over a vsocket (for virtual machines) or a TCP port +for connections to control the tracing of the machine. The agent will then start +tracing on the local machine and pass the data to the controlling connection. + +OPTIONS +------- +*-N* 'client':: + Listen over TCP instead of a vsocket. Must pass in a client host name or IP address + to allow connection to. It will only connect to the specified client. Note, any process + on that client can control the agent. + + *This is a very insecure setting. Only use on a trusted network* + *Only use if the client machine is totally trusted* + +*-p* 'port':: + This option will specify the port to listen to. + +*-D*:: + This options causes trace-cmd agent to go into a daemon mode and run in + the background. + +*--verbose*[='level']:: + Set the log level. Supported log levels are "none", "critical", "error", "warning", + "info", "debug", "all" or their identifiers "0", "1", "2", "3", "4", "5", "6". Setting the log + level to specific value enables all logs from that and all previous levels. + The level will default to "info" if one is not specified. + + Example: enable all critical, error and warning logs + + trace-cmd listen --verbose=warning + +SEE ALSO +-------- +trace-cmd(1), trace-cmd-record(1), trace-cmd-report(1), trace-cmd-start(1), +trace-cmd-stop(1), trace-cmd-extract(1), trace-cmd-reset(1), +trace-cmd-split(1), trace-cmd-list(1) + +AUTHOR +------ +Written by Steven Rostedt, <rostedt@goodmis.org> + +RESOURCES +--------- +https://git.kernel.org/pub/scm/utils/trace-cmd/trace-cmd.git/ + +COPYING +------- +Copyright \(C) 2010 Red Hat, Inc. Free use of this software is granted under +the terms of the GNU Public License (GPL). diff --git a/Documentation/trace-cmd/trace-cmd-check-events.1.txt b/Documentation/trace-cmd/trace-cmd-check-events.1.txt new file mode 100644 index 00000000..debab6c5 --- /dev/null +++ b/Documentation/trace-cmd/trace-cmd-check-events.1.txt @@ -0,0 +1,55 @@ +TRACE-CMD-CHECK_EVENTS(1) +========================= + +NAME +---- +trace-cmd-check-events - parse the event formats on local system + +SYNOPSIS +-------- +*trace-cmd check-events* ['OPTIONS'] + +DESCRIPTION +----------- +The trace-cmd(1) check-events parses format strings for all the events on the +local system. It returns whether all the format strings can be parsed +correctly. It will load plugins unless specified otherwise. + +This is useful to check for any trace event format strings which may contain +some internal kernel function references which cannot be decoded outside of +the kernel. This may mean that either the unparsed format strings of the trace +events need to be changed or that a plugin needs to be created to parse them. + +OPTIONS +------- +*-N* - Don't load plugins + +*--verbose*[='level']:: + Set the log level. Supported log levels are "none", "critical", "error", "warning", + "info", "debug", "all" or their identifiers "0", "1", "2", "3", "4", "5", "6". Setting the log + level to specific value enables all logs from that and all previous levels. + The level will default to "info" if one is not specified. + + Example: enable all critical, error and warning logs + + trace-cmd check-events --verbose=warning + +SEE ALSO +-------- +trace-cmd(1), trace-cmd-record(1), trace-cmd-report(1), trace-cmd-stop(1), +trace-cmd-extract(1), trace-cmd-reset(1), trace-cmd-split(1), +trace-cmd-list(1), trace-cmd-listen(1), trace-cmd-start(1) + +AUTHOR +------ +Written by Vaibhav Nagarnaik, <vnagarnaik@google.com> + +RESOURCES +--------- +https://git.kernel.org/pub/scm/utils/trace-cmd/trace-cmd.git/ + +COPYING +------- +Copyright \(C) 2011 Google, Inc. Free use of this software is granted under +the terms of the GNU Public License (GPL). + diff --git a/Documentation/trace-cmd/trace-cmd-clear.1.txt b/Documentation/trace-cmd/trace-cmd-clear.1.txt new file mode 100644 index 00000000..74236960 --- /dev/null +++ b/Documentation/trace-cmd/trace-cmd-clear.1.txt @@ -0,0 +1,51 @@ +TRACE-CMD-CLEAR(1) +================= + +NAME +---- +trace-cmd-clear - clear the Ftrace buffer. + +SYNOPSIS +-------- +*trace-cmd clear* ['OPTIONS'] + +DESCRIPTION +----------- +The *trace-cmd(1) clear* clears the content of the Ftrace ring buffer. + +OPTIONS +------- +*-B* 'buffer-name':: + If the kernel supports multiple buffers, this will clear only the given + buffer. It does not affect any other buffers. This may be used multiple + times to specify different buffers. The top level buffer will not be + clearded if this option is given. + +*-a*:: + Clear all existing buffers, including the top level one. + +SEE ALSO +-------- +trace-cmd(1), trace-cmd-record(1), trace-cmd-report(1), trace-cmd-start(1), +trace-cmd-extract(1), trace-cmd-reset(1), trace-cmd-split(1), +trace-cmd-list(1), trace-cmd-listen(1) + +AUTHOR +------ +[verse] +-- +*Steven Rostedt* <rostedt@goodmis.org>, author of *trace-cmd*. +*Tzvetomir Stoyanov* <tz.stoyanov@gmail.com>, author of this man page. +-- +REPORTING BUGS +-------------- +Report bugs to <linux-trace-devel@vger.kernel.org> + +LICENSE +------- +trace-cmd is Free Software licensed under the terms of the +GNU Public License (GPL). + +RESOURCES +--------- +https://git.kernel.org/pub/scm/utils/trace-cmd/trace-cmd.git/
\ No newline at end of file diff --git a/Documentation/trace-cmd/trace-cmd-convert.1.txt b/Documentation/trace-cmd/trace-cmd-convert.1.txt new file mode 100644 index 00000000..7c13cf3d --- /dev/null +++ b/Documentation/trace-cmd/trace-cmd-convert.1.txt @@ -0,0 +1,65 @@ +TRACE-CMD-CONVERT(1) +=================== + +NAME +---- +trace-cmd-convert - convert trace files + +SYNOPSIS +-------- +*trace-cmd convert* ['OPTIONS'] ['output-file'] + +DESCRIPTION +----------- +The trace-cmd(1) convert command converts trace file. It reads the input file and copies the data +into an output file. The output file may be in different format, depending on the command line +arguments. + +OPTIONS +------- +*-i* 'input-file':: + By default, trace-cmd convert will read the file 'trace.dat'. But the *-i* + option open up the given 'input-file' instead. + +*-o* 'out-file':: + The name of the output file, this parameter is mandatory. Note, the output file may also be + specified as the last item on the command line. + +*--file-version*:: + Desired version of the output file. Supported versions are 6 or 7. + +*--compression*:: + Compression of the trace output file, one of these strings can be passed: + + 'any' - auto select the best available compression algorithm + + 'none' - do not compress the trace file + + 'name' - the name of the desired compression algorithms. Available algorithms can be listed with + trace-cmd list -c + +*--help*:: + Print usage information. + +EXAMPLES +-------- + +# trace-cmd convert --compression any trace_compress.dat + +SEE ALSO +-------- +trace-cmd(1), trace-cmd.dat(1) + +AUTHOR +------ +*Steven Rostedt* <rostedt@goodmis.org>, author of *trace-cmd*. +*Tzvetomir Stoyanov* <tz.stoyanov@gmail.com>, author of this man page. + +RESOURCES +--------- +https://git.kernel.org/pub/scm/utils/trace-cmd/trace-cmd.git/ + +COPYING +------- +Copyright \(C) 2021 VMware. Free use of this software is granted under +the terms of the GNU Public License (GPL). diff --git a/Documentation/trace-cmd/trace-cmd-dump.1.txt b/Documentation/trace-cmd/trace-cmd-dump.1.txt new file mode 100644 index 00000000..9c95244b --- /dev/null +++ b/Documentation/trace-cmd/trace-cmd-dump.1.txt @@ -0,0 +1,142 @@ +TRACE-CMD-DUMP(1) +=================== + +NAME +---- +trace-cmd-dump - show a meta data from a trace file, created by trace-cmd record + +SYNOPSIS +-------- +*trace-cmd dump* ['OPTIONS'] ['input-file'] + +DESCRIPTION +----------- +The trace-cmd(1) dump command will display the meta data from a trace file +created by trace-cmd record. + +OPTIONS +------- +*-i* 'input-file':: + By default, trace-cmd dump will read the file 'trace.dat'. But the *-i* + option open up the given 'input-file' instead. Note, the input file may + also be specified as the last item on the command line. +*-v*, *--validate*:: + Check if the input file is a valid trace file, created by trace-cmd. +*--summary*:: + Print a meta data summary - initial format and a short description of each + file section. This is the default action, if no arguments are specified. +*--head-page*:: + Print the header page information, stored in the file. +*--head-event*:: + Print the event header information, stored in the file. +*--ftrace-events*:: + Print formats of ftrace specific events. +*--systems*:: + Print information of event systems, stored in the file - name and number of + events for each system. +*--events*:: + Print formats of all events, stored in the file. +*--kallsyms*:: + Print information of the mapping of function addresses to the function names. +*--printk*:: + Print trace_printk() format strings, stored in the file. +*--cmd-lines*:: + Print mapping a PID to a process name. +*--options*:: + Print all options, stored in the file. +*--flyrecord*:: + Print the offset and the size of tracing data per each CPU. +*--clock*:: + Print the trace clock, used for timestamp of the tracing events, stored in the file. +*--all*:: + Print all meta data from the file. +*--help*:: + Print usage information. +*--verbose*[='level']:: + Set the log level. Supported log levels are "none", "critical", "error", "warning", + "info", "debug", "all" or their identifiers "0", "1", "2", "3", "4", "5", "6". Setting the log + level to specific value enables all logs from that and all previous levels. + The level will default to "info" if one is not specified. + + Example: enable all critical, error and warning logs + + trace-cmd report --verbose=warning + +EXAMPLES +-------- + +# trace-cmd dump --summary -i trace.dat + + Tracing meta data in file trace.dat: + [Initial format] + 6 [Version] + 0 [Little endian] + 8 [Bytes in a long] + 4096 [Page size, bytes] + [Header info, 205 bytes] + [Header event, 205 bytes] + [Ftrace format, 15 events] + [Events format, 2 systems] + [Kallsyms, 7144493 bytes] + [Trace printk, 2131 bytes] + [Saved command lines, 117 bytes] + 8 [CPUs with tracing data] + [12 options] + [Flyrecord tracing data] +------------------------------------------ + +# trace-cmd dump --flyrecord -i trace.dat + [Flyrecord tracing data] + 7176192 0 [offset, size of cpu 0] + 7176192 0 [offset, size of cpu 1] + 7176192 0 [offset, size of cpu 2] + 7176192 4096 [offset, size of cpu 3] + 7180288 4096 [offset, size of cpu 4] + 7184384 0 [offset, size of cpu 5] + 7184384 0 [offset, size of cpu 6] + 7184384 0 [offset, size of cpu 7] +------------------------------------------ + +# trace-cmd dump --summary --systems -i trace.dat + + Tracing meta data in file trace.dat: + [Initial format] + 6 [Version] + 0 [Little endian] + 8 [Bytes in a long] + 4096 [Page size, bytes] + [Header info, 205 bytes] + [Header event, 205 bytes] + [Ftrace format, 15 events] + [Events format, 3 systems] + sched 23 [system, events] + irq 5 [system, events] + kvm 70 [system, events] + [Kallsyms, 7144493 bytes] + [Trace printk, 2131 bytes] + [Saved command lines, 157 bytes] + 8 [CPUs with tracing data] + [11 options] + [Flyrecord tracing data] +------------------------------------------ + +# trace-cmd dump --summary --systems -i trace.dat +File trace.dat is a valid trace-cmd file +------------------------------------------ +SEE ALSO +-------- +trace-cmd(1), trace-cmd.dat(1) + +AUTHOR +------ +*Steven Rostedt* <rostedt@goodmis.org>, author of *trace-cmd*. +*Tzvetomir Stoyanov* <tz.stoyanov@gmail.com>, author of this man page. + +RESOURCES +--------- +https://git.kernel.org/pub/scm/utils/trace-cmd/trace-cmd.git/ + +COPYING +------- +Copyright \(C) 2010 Red Hat, Inc. Free use of this software is granted under +the terms of the GNU Public License (GPL). diff --git a/Documentation/trace-cmd/trace-cmd-extract.1.txt b/Documentation/trace-cmd/trace-cmd-extract.1.txt new file mode 100644 index 00000000..776da6e1 --- /dev/null +++ b/Documentation/trace-cmd/trace-cmd-extract.1.txt @@ -0,0 +1,98 @@ +TRACE-CMD-EXTRACT(1) +==================== + +NAME +---- +trace-cmd-extract - extract out the data from the Ftrace Linux tracer. + +SYNOPSIS +-------- +*trace-cmd extract ['OPTIONS']* + +DESCRIPTION +----------- +The trace-cmd(1) extract is usually used after 'trace-cmd-start(1)' and +'trace-cmd-stop(1)'. It can be used after the Ftrace tracer has been started +manually through the Ftrace pseudo file system. + +The extract command creates a trace.dat file that can be used by +'trace-cmd-report(1)' to read from. It reads the kernel internal ring buffer +to produce the trace.dat file. + +OPTIONS +------- +*-p* 'plugin':: + Although *extract* does not start any traces, some of the plugins require + just reading the output in ASCII format. These are the latency tracers, + since the latency tracers have a separate internal buffer. The plugin + option is therefore only necessary for the 'wakeup', 'wakeup-rt', + 'irqsoff', 'preemptoff' and 'preemptirqsoff' plugins. + + With out this option, the extract command will extract from the internal + Ftrace buffers. + +*-O* 'option':: + If a latency tracer is being extracted, and the *-p* option is used, then + there are some Ftrace options that can change the format. This will update + those options before extracting. To see the list of options see + 'trace-cmd-list'. To enable an option, write its name, to disable the + option append the characters 'no' to it. For example: 'noprint-parent' + will disable the 'print-parent' option that prints the parent function in + printing a function event. + +*-o* 'outputfile':: + By default, the extract command will create a 'trace.dat' file. This + option will change where the file is written to. + +*-s*:: + Extract from the snapshot buffer (if the kernel supports it). + +*--date*:: + This is the same as the trace-cmd-record(1) --date option, but it + does cause the extract routine to disable all tracing. That is, + the end of the extract will perform something similar to trace-cmd-reset(1). + +*-B* 'buffer-name':: + If the kernel supports multiple buffers, this will extract the trace for + only the given buffer. It does not affect any other buffer. This may be + used multiple times to specify different buffers. When this option is + used, the top level instance will not be extracted unless *-t* is given. + +*-a*:: + Extract all existing buffer instances. When this option is used, the + top level instance will not be extracted unless *-t* is given. + +*-t*:: + Extracts the top level instance buffer. Without the *-B* or *-a* option + this is the same as the default. But if *-B* or *-a* is used, this is + required if the top level instance buffer should also be extracted. + +*--verbose*[='level']:: + Set the log level. Supported log levels are "none", "critical", "error", "warning", + "info", "debug", "all" or their identifiers "0", "1", "2", "3", "4", "5", "6". Setting the log + level to specific value enables all logs from that and all previous levels. + The level will default to "info" if one is not specified. + + Example: enable all critical, error and warning logs + + trace-cmd extract --verbose=warning + +SEE ALSO +-------- +trace-cmd(1), trace-cmd-record(1), trace-cmd-report(1), trace-cmd-start(1), +trace-cmd-stop(1), trace-cmd-reset(1), trace-cmd-split(1), +trace-cmd-list(1), trace-cmd-listen(1) + +AUTHOR +------ +Written by Steven Rostedt, <rostedt@goodmis.org> + +RESOURCES +--------- +https://git.kernel.org/pub/scm/utils/trace-cmd/trace-cmd.git/ + +COPYING +------- +Copyright \(C) 2010 Red Hat, Inc. Free use of this software is granted under +the terms of the GNU Public License (GPL). + diff --git a/Documentation/trace-cmd/trace-cmd-hist.1.txt b/Documentation/trace-cmd/trace-cmd-hist.1.txt new file mode 100644 index 00000000..169f8d7b --- /dev/null +++ b/Documentation/trace-cmd/trace-cmd-hist.1.txt @@ -0,0 +1,50 @@ +TRACE-CMD-HIST(1) +================= + +NAME +---- +trace-cmd-hist - show histogram of events in trace.dat file + +SYNOPSIS +-------- +*trace-cmd hist* ['OPTIONS']['input-file'] + +DESCRIPTION +----------- +The trace-cmd(1) hist displays a histogram form from the trace.dat file. +Instead of showing the events as they were ordered, it creates a histogram +that can be displayed per task or for all tasks where the most common +events appear first. It uses the function tracer and call stacks that it +finds to try to put together a call graph of the events. + +OPTIONS +------- +*-i* 'input-file':: + By default, trace-cmd hist will read the file 'trace.dat'. But the *-i* + option open up the given 'input-file' instead. Note, the input file may + also be specified as the last item on the command line. + +*-P*:: + To compact all events and show the call graphs by ignoring tasks + and different PIDs, add the *-P* to do so. Instead of showing the + task name, it will group all chains together and show "<all pids>". + +SEE ALSO +-------- +trace-cmd(1), trace-cmd-record(1), trace-cmd-report(1), trace-cmd-start(1), +trace-cmd-stop(1), trace-cmd-extract(1), trace-cmd-reset(1), +trace-cmd-split(1), trace-cmd-listen(1) + +AUTHOR +------ +Written by Steven Rostedt, <rostedt@goodmis.org> + +RESOURCES +--------- +https://git.kernel.org/pub/scm/utils/trace-cmd/trace-cmd.git/ + +COPYING +------- +Copyright \(C) 2010 Red Hat, Inc. Free use of this software is granted under +the terms of the GNU Public License (GPL). + diff --git a/Documentation/trace-cmd/trace-cmd-list.1.txt b/Documentation/trace-cmd/trace-cmd-list.1.txt new file mode 100644 index 00000000..b77e3460 --- /dev/null +++ b/Documentation/trace-cmd/trace-cmd-list.1.txt @@ -0,0 +1,95 @@ +TRACE-CMD-LIST(1) +================= + +NAME +---- +trace-cmd-list - list available plugins, events or options for Ftrace. + +SYNOPSIS +-------- +*trace-cmd list* ['OPTIONS'] + +DESCRIPTION +----------- +The trace-cmd(1) list displays the available plugins, events or Ftrace options +that are configured on the current machine. If no option is given, then it +lists all plugins, event systems, events and Ftrace options to standard output. + +OPTIONS +------- +*-e* ['regex']:: + This option will list the available events that are enabled on the + local system. + + It takes an optional argument that uses 'regcomp(3)' expressions to seach. + + trace-cmd list -e '^sys.*' + +*-F*:: + Used with *-e* 'regex' to show the fields of the event. + +*--full*:: + Used with *-F* which will show the "print fmt" of the event along with the fields. + +*-l*:: + Used with *-e* 'regex' to show those events filters. + +*-R*:: + Used with *-e* 'regex' to show those events triggers. + +*-s*:: + This option will list the available event systems. + +*-t*:: + This option will list the available tracers that are enabled on the + local system. + +*-p*:: + Same as *-t* and only for legacy purposes. + +*-o*:: + This option will list the available Ftrace options that are configured on + the local system. + +*-f* ['regex']:: + This option will list the available filter functions. These are the list of + functions on the system that you can trace, or filter on. + It takes an optional argument that uses 'regcomp(3)' expressions to seach. + + trace-cmd list -f '^sched.*' + +*-P*:: + List the plugin files that get loaded on trace-cmd report. + +*-O*:: + List plugin options that can be used by trace-cmd report *-O* option. + +*-B*:: + List defined buffer instances (sub buffers). + +*-C*:: + List defined clocks that can be used with trace-cmd record -C. + The one in brackets ([]) is the active clock. + +*-c*:: + List the available trace file compression algorithms. + +SEE ALSO +-------- +trace-cmd(1), trace-cmd-record(1), trace-cmd-report(1), trace-cmd-start(1), +trace-cmd-stop(1), trace-cmd-extract(1), trace-cmd-reset(1), +trace-cmd-split(1), trace-cmd-listen(1) + +AUTHOR +------ +Written by Steven Rostedt, <rostedt@goodmis.org> + +RESOURCES +--------- +https://git.kernel.org/pub/scm/utils/trace-cmd/trace-cmd.git/ + +COPYING +------- +Copyright \(C) 2010 Red Hat, Inc. Free use of this software is granted under +the terms of the GNU Public License (GPL). + diff --git a/Documentation/trace-cmd/trace-cmd-listen.1.txt b/Documentation/trace-cmd/trace-cmd-listen.1.txt new file mode 100644 index 00000000..7c6093ba --- /dev/null +++ b/Documentation/trace-cmd/trace-cmd-listen.1.txt @@ -0,0 +1,71 @@ +TRACE-CMD-LISTEN(1) +=================== + +NAME +---- +trace-cmd-listen - listen for incoming connection to record tracing. + +SYNOPSIS +-------- +*trace-cmd listen* -p 'port' ['OPTIONS'] + +DESCRIPTION +----------- +The trace-cmd(1) listen sets up a port to listen to waiting for connections +from other hosts that run 'trace-cmd-record(1)' with the *-N* option. When a +connection is made, and the remote host sends data, it will create a file +called 'trace.HOST:PORT.dat'. Where HOST is the name of the remote host, and +PORT is the port that the remote host used to connect with. + +OPTIONS +------- +*-p* 'port':: + This option will specify the port to listen to. + +*-D*:: + This options causes trace-cmd listen to go into a daemon mode and run in + the background. + +*-V*:: + Listen on a vsocket instead. This is useful for tracing between host and + guest VMs. + +*-d* 'dir':: + This option specifies a directory to write the data files into. + +*-o* 'filename':: + This option overrides the default 'trace' in the 'trace.HOST:PORT.dat' that + is created when a remote host connects. + +*-l* 'filename':: + This option writes the output messages to a log file instead of standard output. + +*--verbose*[='level']:: + Set the log level. Supported log levels are "none", "critical", "error", "warning", + "info", "debug", "all" or their identifiers "0", "1", "2", "3", "4", "5", "6". Setting the log + level to specific value enables all logs from that and all previous levels. + The level will default to "info" if one is not specified. + + Example: enable all critical, error and warning logs + + trace-cmd listen --verbose=warning + +SEE ALSO +-------- +trace-cmd(1), trace-cmd-record(1), trace-cmd-report(1), trace-cmd-start(1), +trace-cmd-stop(1), trace-cmd-extract(1), trace-cmd-reset(1), +trace-cmd-split(1), trace-cmd-list(1) + +AUTHOR +------ +Written by Steven Rostedt, <rostedt@goodmis.org> + +RESOURCES +--------- +https://git.kernel.org/pub/scm/utils/trace-cmd/trace-cmd.git/ + +COPYING +------- +Copyright \(C) 2010 Red Hat, Inc. Free use of this software is granted under +the terms of the GNU Public License (GPL). + diff --git a/Documentation/trace-cmd/trace-cmd-mem.1.txt b/Documentation/trace-cmd/trace-cmd-mem.1.txt new file mode 100644 index 00000000..90e430b8 --- /dev/null +++ b/Documentation/trace-cmd/trace-cmd-mem.1.txt @@ -0,0 +1,74 @@ +TRACE-CMD-MEM(1) +================ + +NAME +---- +trace-cmd-mem - show memory usage of certain kmem events + +SYNOPSIS +-------- +*trace-cmd mem* ['OPTIONS']['input-file'] + +DESCRIPTION +----------- +The trace-cmd(1) mem requires a trace-cmd record that enabled the following +events: + + kmalloc + kmalloc_node + kfree + kmem_cache_alloc + kmem_cache_alloc_node + kmem_cache_alloc_free + +It then reads the amount requested and the ammount freed as well as the +functions that called the allocation. It then reports the final amount +of bytes requested and allocated, along with the total amount allocated +and requested, as well as the max allocation and requested during the run. +It reports the amount of wasted bytes (allocated - requested) that was +not freed, as well as the max wasted amount during the run. The list is +sorted by descending order of wasted bytes after the run. + + Function Waste Alloc req TotAlloc TotReq MaxAlloc MaxReq MaxWaste + -------- ----- ----- --- -------- ------ -------- ------ -------- + rb_allocate_cpu_buffer 768 2304 1536 2304 1536 2304 1536 768 + alloc_pipe_info 400 1152 752 1152 752 1152 752 400 + instance_mkdir 252 544 292 544 292 544 292 252 + __d_alloc 215 1086560 1086345 1087208 1086993 1086560 1086345 215 + get_empty_filp 72 2304 2232 4864 4712 4864 4712 152 + mm_alloc 40 960 920 960 920 960 920 40 + prepare_creds 32 192 160 1728 1440 1728 1440 288 + tracing_buffers_open 8 32 24 32 24 32 24 8 + do_brk 0 0 0 368 368 368 368 0 + journal_add_journal_head 0 6048 6048 6048 6048 6048 6048 0 + journal_start 0 0 0 1224 1224 48 48 0 + __rb_allocate_pages 0 3289856 3289856 3289856 3289856 3289856 3289856 0 + anon_vma_alloc 0 0 0 936 936 864 864 0 + [...] + +OPTIONS +------- +*-i* 'input-file':: + By default, trace-cmd hist will read the file 'trace.dat'. But the *-i* + option open up the given 'input-file' instead. Note, the input file may + also be specified as the last item on the command line. + +SEE ALSO +-------- +trace-cmd(1), trace-cmd-record(1), trace-cmd-report(1), trace-cmd-start(1), +trace-cmd-stop(1), trace-cmd-extract(1), trace-cmd-reset(1), trace-cmd-hist(1), +trace-cmd-split(1), trace-cmd-listen(1) + +AUTHOR +------ +Written by Steven Rostedt, <rostedt@goodmis.org> + +RESOURCES +--------- +https://git.kernel.org/pub/scm/utils/trace-cmd/trace-cmd.git/ + +COPYING +------- +Copyright \(C) 2013 Red Hat, Inc. Free use of this software is granted under +the terms of the GNU Public License (GPL). + diff --git a/Documentation/trace-cmd/trace-cmd-options.1.txt b/Documentation/trace-cmd/trace-cmd-options.1.txt new file mode 100644 index 00000000..bcdf0533 --- /dev/null +++ b/Documentation/trace-cmd/trace-cmd-options.1.txt @@ -0,0 +1,35 @@ +TRACE-CMD-OPTIONS(1) +==================== + +NAME +---- +trace-cmd-options - list available options from trace-cmd plugins + +SYNOPSIS +-------- +*trace-cmd options* + +DESCRIPTION +----------- +The trace-cmd(1) options command will examine all the trace-cmd plugins +that are used by *trace-cmd report(1)* and list them. + +SEE ALSO +-------- +trace-cmd(1), trace-cmd-record(1), trace-cmd-start(1), trace-cmd-stop(1), +trace-cmd-extract(1), trace-cmd-reset(1), trace-cmd-split(1), +trace-cmd-list(1), trace-cmd-listen(1) + +AUTHOR +------ +Written by Steven Rostedt, <rostedt@goodmis.org> + +RESOURCES +--------- +https://git.kernel.org/pub/scm/utils/trace-cmd/trace-cmd.git/ + +COPYING +------- +Copyright \(C) 2011 Red Hat, Inc. Free use of this software is granted under +the terms of the GNU Public License (GPL). + diff --git a/Documentation/trace-cmd/trace-cmd-profile.1.txt b/Documentation/trace-cmd/trace-cmd-profile.1.txt new file mode 100644 index 00000000..078ae9e0 --- /dev/null +++ b/Documentation/trace-cmd/trace-cmd-profile.1.txt @@ -0,0 +1,686 @@ +TRACE-CMD-PROFILE(1) +==================== + +NAME +---- +trace-cmd-profile - profile tasks running live + +SYNOPSIS +-------- +*trace-cmd profile ['OPTIONS']* ['command'] + +DESCRIPTION +----------- +The trace-cmd(1) profile will start tracing just like trace-cmd-record(1), +with the *--profile* option, except that it does not write to a file, +but instead, it will read the events as they happen and will update the accounting +of the events. When the trace is finished, it will report the results just like +trace-cmd-report(1) would do with its *--profile* option. In other words, +the profile command does the work of trace-cmd record --profile, and trace-cmd +report --profile without having to record the data to disk, in between. + +The advantage of using the profile command is that the profiling can be done +over a long period of time where recording all events would take up too much +disk space. + +This will enable several events as well as the function graph tracer +with a depth of one (if the kernel supports it). This is to show where +tasks enter and exit the kernel and how long they were in the kernel. + +To disable calling function graph, use the *-p* option to enable another +tracer. To not enable any tracer, use *-p nop*. + +All timings are currently in nanoseconds. + +OPTIONS +------- +These are the same as trace-cmd-record(1) with the *--profile* option. + +*-p* 'tracer':: + Set a tracer plugin to run instead of function graph tracing set to + depth of 1. To not run any tracer, use *-p nop*. + +*-S*:: + Only enable the tracer or events speficied on the command line. + With this option, the function_graph tracer is not enabled, nor are + any events (like sched_switch), unless they are specifically specified + on the command line (i.e. -p function -e sched_switch -e sched_wakeup) + +*-G*:: + Set interrupt (soft and hard) events as global (associated to CPU + instead of tasks). + +*-o* 'file':: + Write the output of the profile to 'file'. This supersedes *--stderr* + +*-H* 'event-hooks':: + Add custom event matching to connect any two events together. Format is: + [<start_system>:]<start_event>,<start_match>[,<start_pid>]/ + [<end_system>:]<end_event>,<end_match>[,<flags>] + + The start_system:start_event (start_system is optional), is the event that + starts the timing. + + start_match is the field in the start event that is to match with the + end_match in the end event. + + start_pid is optional, as matches are attached to the tasks that run + the events, if another field should be used to find that task, then + it is specified with start_pid. + + end_system:end_event is the event that ends the timing (end_system is + optional). + + end_match is the field in end_match that wil match the start event field + start_match. + + flags are optional and can be the following (case insensitive): + + p : The two events are pinned to the same CPU (start and end happen + on the same CPU always). + + s : The event should have a stack traced with it (enable stack tracing + for the start event). + + g : The event is global (not associated to a task). start_pid is + not applicable with this flag. + +*--stderr*:: + Redirect the output to stderr. The output of the command being executed + is not changed. This allows watching the command execute and saving the + output of the profile to another file. + +*--verbose*[='level']:: + Set the log level. Supported log levels are "none", "critical", "error", "warning", + "info", "debug", "all" or their identifiers "0", "1", "2", "3", "4", "5", "6". Setting the log + level to specific value enables all logs from that and all previous levels. + The level will default to "info" if one is not specified. + + Example: enable all critical, error and warning logs + + trace-cmd profile --verbose=warning + +EXAMPLES +-------- + + --- +# trace-cmd profile -F sleep 1 + [..] +task: sleep-1121 + Event: sched_switch:R (2) Total: 234559 Avg: 117279 Max: 129886 Min:104673 + | + + ftrace_raw_event_sched_switch (0xffffffff8109f310) + 100% (2) time:234559 max:129886 min:104673 avg:117279 + __schedule (0xffffffff816c1e81) + preempt_schedule (0xffffffff816c236e) + ___preempt_schedule (0xffffffff81351a59) + | + + unmap_single_vma (0xffffffff81198c05) + | 55% (1) time:129886 max:129886 min:0 avg:129886 + | stop_one_cpu (0xffffffff8110909a) + | sched_exec (0xffffffff810a119b) + | do_execveat_common.isra.31 (0xffffffff811de528) + | do_execve (0xffffffff811dea8c) + | SyS_execve (0xffffffff811ded1e) + | return_to_handler (0xffffffff816c8458) + | stub_execve (0xffffffff816c6929) + | + + unmap_single_vma (0xffffffff81198c05) + 45% (1) time:104673 max:104673 min:0 avg:104673 + unmap_vmas (0xffffffff81199174) + exit_mmap (0xffffffff811a1f5b) + mmput (0xffffffff8107699a) + flush_old_exec (0xffffffff811ddb75) + load_elf_binary (0xffffffff812287df) + search_binary_handler (0xffffffff811dd3e0) + do_execveat_common.isra.31 (0xffffffff811de8bd) + do_execve (0xffffffff811dea8c) + SyS_execve (0xffffffff811ded1e) + return_to_handler (0xffffffff816c8458) + stub_execve (0xffffffff816c6929) + + + + + Event: sched_switch:S (1) Total: 1000513242 Avg: 1000513242 Max: 1000513242 Min:1000513242 + | + + ftrace_raw_event_sched_switch (0xffffffff8109f310) + 100% (1) time:1000513242 max:1000513242 min:0 avg:1000513242 + __schedule (0xffffffff816c1e81) + schedule (0xffffffff816c23b9) + do_nanosleep (0xffffffff816c4f1c) + hrtimer_nanosleep (0xffffffff810dcd86) + SyS_nanosleep (0xffffffff810dcea6) + return_to_handler (0xffffffff816c8458) + tracesys_phase2 (0xffffffff816c65b0) + + + + Event: sched_wakeup:1121 (1) Total: 43405 Avg: 43405 Max: 43405 Min:43405 + | + + ftrace_raw_event_sched_wakeup_template (0xffffffff8109d960) + 100% (1) time:43405 max:43405 min:0 avg:43405 + ttwu_do_wakeup (0xffffffff810a01a2) + ttwu_do_activate.constprop.122 (0xffffffff810a0236) + try_to_wake_up (0xffffffff810a3ec3) + wake_up_process (0xffffffff810a4057) + hrtimer_wakeup (0xffffffff810db772) + __run_hrtimer (0xffffffff810dbd91) + hrtimer_interrupt (0xffffffff810dc6b7) + local_apic_timer_interrupt (0xffffffff810363e7) + smp_trace_apic_timer_interrupt (0xffffffff816c8c6a) + trace_apic_timer_interrupt (0xffffffff816c725a) + finish_task_switch (0xffffffff8109c3a4) + __schedule (0xffffffff816c1e01) + schedule (0xffffffff816c23b9) + ring_buffer_wait (0xffffffff811323a3) + wait_on_pipe (0xffffffff81133d93) + tracing_buffers_splice_read (0xffffffff811350b0) + do_splice_to (0xffffffff8120476f) + SyS_splice (0xffffffff81206c1f) + tracesys_phase2 (0xffffffff816c65b0) + + + Event: func: sys_nanosleep() (1) Total: 1000598016 Avg: 1000598016 Max: 1000598016 Min:1000598016 + Event: func: sys_munmap() (1) Total: 14300 Avg: 14300 Max: 14300 Min:14300 + Event: func: sys_arch_prctl() (1) Total: 571 Avg: 571 Max: 571 Min:571 + Event: func: sys_mprotect() (4) Total: 14382 Avg: 3595 Max: 7196 Min:2190 + Event: func: SyS_read() (1) Total: 2640 Avg: 2640 Max: 2640 Min:2640 + Event: func: sys_close() (5) Total: 4001 Avg: 800 Max: 1252 Min:414 + Event: func: sys_newfstat() (3) Total: 11684 Avg: 3894 Max: 10206 Min:636 + Event: func: SyS_open() (3) Total: 23615 Avg: 7871 Max: 10535 Min:4743 + Event: func: sys_access() (1) Total: 5924 Avg: 5924 Max: 5924 Min:5924 + Event: func: SyS_mmap() (8) Total: 39153 Avg: 4894 Max: 12354 Min:1518 + Event: func: smp_trace_apic_timer_interrupt() (1) Total: 10298 Avg: 10298 Max: 10298 Min:10298 + Event: func: SyS_brk() (4) Total: 2407 Avg: 601 Max: 1564 Min:206 + Event: func: do_notify_resume() (2) Total: 4095 Avg: 2047 Max: 2521 Min:1574 + Event: func: sys_execve() (5) Total: 1625251 Avg: 325050 Max: 1605698 Min:3570 + | + + ftrace_raw_event_sched_wakeup_template (0xffffffff8109d960) + 100% (1) time:1605698 max:1605698 min:0 avg:1605698 + ttwu_do_wakeup (0xffffffff810a01a2) + ttwu_do_activate.constprop.122 (0xffffffff810a0236) + try_to_wake_up (0xffffffff810a3ec3) + wake_up_process (0xffffffff810a4057) + cpu_stop_queue_work (0xffffffff81108df8) + stop_one_cpu (0xffffffff8110909a) + sched_exec (0xffffffff810a119b) + do_execveat_common.isra.31 (0xffffffff811de528) + do_execve (0xffffffff811dea8c) + SyS_execve (0xffffffff811ded1e) + return_to_handler (0xffffffff816c8458) + stub_execve (0xffffffff816c6929) + stub_execve (0xffffffff816c6929) + + + Event: func: syscall_trace_enter_phase2() (38) Total: 21544 Avg: 566 Max: 1066 Min:329 + Event: func: syscall_trace_enter_phase1() (38) Total: 9202 Avg: 242 Max: 376 Min:150 + Event: func: __do_page_fault() (53) Total: 257672 Avg: 4861 Max: 27745 Min:458 + | + + ftrace_raw_event_sched_wakeup_template (0xffffffff8109d960) + 100% (1) time:27745 max:27745 min:0 avg:27745 + ttwu_do_wakeup (0xffffffff810a01a2) + ttwu_do_activate.constprop.122 (0xffffffff810a0236) + try_to_wake_up (0xffffffff810a3ec3) + default_wake_function (0xffffffff810a4002) + autoremove_wake_function (0xffffffff810b50fd) + __wake_up_common (0xffffffff810b4958) + __wake_up (0xffffffff810b4cb8) + rb_wake_up_waiters (0xffffffff8112f126) + irq_work_run_list (0xffffffff81157d0f) + irq_work_run (0xffffffff81157d5e) + smp_trace_irq_work_interrupt (0xffffffff810082fc) + trace_irq_work_interrupt (0xffffffff816c7aaa) + return_to_handler (0xffffffff816c8458) + trace_do_page_fault (0xffffffff810478b2) + trace_page_fault (0xffffffff816c7dd2) + + + Event: func: syscall_trace_leave() (38) Total: 26145 Avg: 688 Max: 1264 Min:381 + Event: func: __sb_end_write() (1) Total: 373 Avg: 373 Max: 373 Min:373 + Event: func: fsnotify() (1) Total: 598 Avg: 598 Max: 598 Min:598 + Event: func: __fsnotify_parent() (1) Total: 286 Avg: 286 Max: 286 Min:286 + Event: func: mutex_unlock() (2) Total: 39636 Avg: 19818 Max: 39413 Min:223 + Event: func: smp_trace_irq_work_interrupt() (6) Total: 236459 Avg: 39409 Max: 100671 Min:634 + | + + ftrace_raw_event_sched_wakeup_template (0xffffffff8109d960) + 100% (4) time:234348 max:100671 min:38745 avg:58587 + ttwu_do_wakeup (0xffffffff810a01a2) + ttwu_do_activate.constprop.122 (0xffffffff810a0236) + try_to_wake_up (0xffffffff810a3ec3) + default_wake_function (0xffffffff810a4002) + autoremove_wake_function (0xffffffff810b50fd) + __wake_up_common (0xffffffff810b4958) + __wake_up (0xffffffff810b4cb8) + rb_wake_up_waiters (0xffffffff8112f126) + irq_work_run_list (0xffffffff81157d0f) + irq_work_run (0xffffffff81157d5e) + smp_trace_irq_work_interrupt (0xffffffff810082fc) + return_to_handler (0xffffffff816c8458) + trace_irq_work_interrupt (0xffffffff816c7aaa) + | + + ftrace_return_to_handler (0xffffffff81140840) + | 84% (3) time:197396 max:100671 min:38745 avg:65798 + | return_to_handler (0xffffffff816c846d) + | trace_page_fault (0xffffffff816c7dd2) + | + + ftrace_return_to_handler (0xffffffff81140840) + 16% (1) time:36952 max:36952 min:0 avg:36952 + ftrace_graph_caller (0xffffffff816c8428) + mutex_unlock (0xffffffff816c3f75) + rb_simple_write (0xffffffff81133142) + vfs_write (0xffffffff811d7727) + SyS_write (0xffffffff811d7acf) + tracesys_phase2 (0xffffffff816c65b0) + + + + + Event: sys_enter:35 (1) Total: 1000599765 Avg: 1000599765 Max: 1000599765 Min:1000599765 + Event: sys_enter:11 (1) Total: 55025 Avg: 55025 Max: 55025 Min:55025 + Event: sys_enter:158 (1) Total: 1584 Avg: 1584 Max: 1584 Min:1584 + Event: sys_enter:10 (4) Total: 18359 Avg: 4589 Max: 8764 Min:2933 + Event: sys_enter:0 (1) Total: 4223 Avg: 4223 Max: 4223 Min:4223 + Event: sys_enter:3 (5) Total: 9948 Avg: 1989 Max: 2606 Min:1203 + Event: sys_enter:5 (3) Total: 15530 Avg: 5176 Max: 11840 Min:1405 + Event: sys_enter:2 (3) Total: 28002 Avg: 9334 Max: 12035 Min:5656 + Event: sys_enter:21 (1) Total: 7814 Avg: 7814 Max: 7814 Min:7814 + Event: sys_enter:9 (8) Total: 49583 Avg: 6197 Max: 14137 Min:2362 + Event: sys_enter:12 (4) Total: 108493 Avg: 27123 Max: 104079 Min:922 + Event: sys_enter:59 (5) Total: 1631608 Avg: 326321 Max: 1607529 Min:4563 + Event: page_fault_user:0x398d86b630 (1) + Event: page_fault_user:0x398d844de0 (1) + Event: page_fault_user:0x398d8d9020 (1) + Event: page_fault_user:0x1d37008 (1) + Event: page_fault_user:0x7f0b89e91074 (1) + Event: page_fault_user:0x7f0b89d98ed0 (1) + Event: page_fault_user:0x7f0b89ec8950 (1) + Event: page_fault_user:0x7f0b89d83644 (1) + Event: page_fault_user:0x7f0b89d622a8 (1) + Event: page_fault_user:0x7f0b89d5a560 (1) + Event: page_fault_user:0x7f0b89d34010 (1) + Event: page_fault_user:0x1d36008 (1) + Event: page_fault_user:0x398d900510 (1) + Event: page_fault_user:0x398dbb3ae8 (1) + Event: page_fault_user:0x398d87f490 (1) + Event: page_fault_user:0x398d8eb660 (1) + Event: page_fault_user:0x398d8bd730 (1) + Event: page_fault_user:0x398d9625d9 (1) + Event: page_fault_user:0x398d931810 (1) + Event: page_fault_user:0x398dbb7114 (1) + Event: page_fault_user:0x398d837610 (1) + Event: page_fault_user:0x398d89e860 (1) + Event: page_fault_user:0x398d8f23b0 (1) + Event: page_fault_user:0x398dbb4510 (1) + Event: page_fault_user:0x398dbad6f0 (1) + Event: page_fault_user:0x398dbb1018 (1) + Event: page_fault_user:0x398d977b37 (1) + Event: page_fault_user:0x398d92eb60 (1) + Event: page_fault_user:0x398d8abff0 (1) + Event: page_fault_user:0x398dbb0d30 (1) + Event: page_fault_user:0x398dbb6c24 (1) + Event: page_fault_user:0x398d821c50 (1) + Event: page_fault_user:0x398dbb6c20 (1) + Event: page_fault_user:0x398d886350 (1) + Event: page_fault_user:0x7f0b90125000 (1) + Event: page_fault_user:0x7f0b90124740 (1) + Event: page_fault_user:0x7f0b90126000 (1) + Event: page_fault_user:0x398d816230 (1) + Event: page_fault_user:0x398d8002b8 (1) + Event: page_fault_user:0x398dbb0b40 (1) + Event: page_fault_user:0x398dbb2880 (1) + Event: page_fault_user:0x7f0b90141cc6 (1) + Event: page_fault_user:0x7f0b9013b85c (1) + Event: page_fault_user:0x7f0b90127000 (1) + Event: page_fault_user:0x606e70 (1) + Event: page_fault_user:0x7f0b90144010 (1) + Event: page_fault_user:0x7fffcb31b038 (1) + Event: page_fault_user:0x606da8 (1) + Event: page_fault_user:0x400040 (1) + Event: page_fault_user:0x398d222218 (1) + Event: page_fault_user:0x398d015120 (1) + Event: page_fault_user:0x398d220ce8 (1) + Event: page_fault_user:0x398d220b80 (1) + Event: page_fault_user:0x7fffcb2fcff8 (1) + Event: page_fault_user:0x398d001590 (1) + Event: page_fault_user:0x398d838490 (1) + Event: softirq_raise:RCU (3) Total: 252931 Avg: 84310 Max: 243288 Min:4639 + Event: softirq_raise:SCHED (2) Total: 241249 Avg: 120624 Max: 239076 Min:2173 + | + + ftrace_raw_event_sched_wakeup_template (0xffffffff8109d960) + 100% (1) time:239076 max:239076 min:0 avg:239076 + ttwu_do_wakeup (0xffffffff810a01a2) + ttwu_do_activate.constprop.122 (0xffffffff810a0236) + try_to_wake_up (0xffffffff810a3ec3) + default_wake_function (0xffffffff810a4002) + autoremove_wake_function (0xffffffff810b50fd) + __wake_up_common (0xffffffff810b4958) + __wake_up (0xffffffff810b4cb8) + rb_wake_up_waiters (0xffffffff8112f126) + irq_work_run_list (0xffffffff81157d0f) + irq_work_run (0xffffffff81157d5e) + smp_trace_irq_work_interrupt (0xffffffff810082fc) + trace_irq_work_interrupt (0xffffffff816c7aaa) + irq_exit (0xffffffff8107dd66) + smp_trace_apic_timer_interrupt (0xffffffff816c8c7a) + trace_apic_timer_interrupt (0xffffffff816c725a) + prepare_ftrace_return (0xffffffff8103d4fd) + ftrace_graph_caller (0xffffffff816c8428) + mem_cgroup_begin_page_stat (0xffffffff811cfd25) + page_remove_rmap (0xffffffff811a4fc5) + stub_execve (0xffffffff816c6929) + unmap_single_vma (0xffffffff81198b1c) + unmap_vmas (0xffffffff81199174) + exit_mmap (0xffffffff811a1f5b) + mmput (0xffffffff8107699a) + flush_old_exec (0xffffffff811ddb75) + load_elf_binary (0xffffffff812287df) + search_binary_handler (0xffffffff811dd3e0) + do_execveat_common.isra.31 (0xffffffff811de8bd) + do_execve (0xffffffff811dea8c) + SyS_execve (0xffffffff811ded1e) + return_to_handler (0xffffffff816c8458) + + + Event: softirq_raise:HI (3) Total: 72472 Avg: 24157 Max: 64186 Min:3430 + Event: softirq_entry:RCU (2) Total: 3191 Avg: 1595 Max: 1788 Min:1403 + | + + ftrace_raw_event_sched_wakeup_template (0xffffffff8109d960) + 100% (1) time:1788 max:1788 min:0 avg:1788 + ttwu_do_wakeup (0xffffffff810a01a2) + ttwu_do_activate.constprop.122 (0xffffffff810a0236) + try_to_wake_up (0xffffffff810a3ec3) + default_wake_function (0xffffffff810a4002) + autoremove_wake_function (0xffffffff810b50fd) + __wake_up_common (0xffffffff810b4958) + __wake_up (0xffffffff810b4cb8) + rb_wake_up_waiters (0xffffffff8112f126) + irq_work_run_list (0xffffffff81157d0f) + irq_work_run (0xffffffff81157d5e) + smp_trace_irq_work_interrupt (0xffffffff810082fc) + trace_irq_work_interrupt (0xffffffff816c7aaa) + irq_work_queue (0xffffffff81157e95) + ring_buffer_unlock_commit (0xffffffff8113039f) + __buffer_unlock_commit (0xffffffff811367d5) + trace_buffer_unlock_commit (0xffffffff811376a2) + ftrace_event_buffer_commit (0xffffffff81146d5f) + ftrace_raw_event_sched_process_exec (0xffffffff8109c511) + do_execveat_common.isra.31 (0xffffffff811de9a3) + do_execve (0xffffffff811dea8c) + SyS_execve (0xffffffff811ded1e) + return_to_handler (0xffffffff816c8458) + stub_execve (0xffffffff816c6929) + + + Event: softirq_entry:SCHED (2) Total: 2289 Avg: 1144 Max: 1350 Min:939 + Event: softirq_entry:HI (3) Total: 180146 Avg: 60048 Max: 178969 Min:499 + | + + ftrace_raw_event_sched_wakeup_template (0xffffffff8109d960) + 100% (1) time:178969 max:178969 min:0 avg:178969 + ttwu_do_wakeup (0xffffffff810a01a2) + ttwu_do_activate.constprop.122 (0xffffffff810a0236) + try_to_wake_up (0xffffffff810a3ec3) + wake_up_process (0xffffffff810a4057) + wake_up_worker (0xffffffff8108de74) + insert_work (0xffffffff8108fca6) + __queue_work (0xffffffff8108fe12) + delayed_work_timer_fn (0xffffffff81090088) + call_timer_fn (0xffffffff810d8f89) + run_timer_softirq (0xffffffff810da8a1) + __do_softirq (0xffffffff8107d8fa) + irq_exit (0xffffffff8107dd66) + smp_trace_apic_timer_interrupt (0xffffffff816c8c7a) + trace_apic_timer_interrupt (0xffffffff816c725a) + prepare_ftrace_return (0xffffffff8103d4fd) + ftrace_graph_caller (0xffffffff816c8428) + mem_cgroup_begin_page_stat (0xffffffff811cfd25) + page_remove_rmap (0xffffffff811a4fc5) + stub_execve (0xffffffff816c6929) + unmap_single_vma (0xffffffff81198b1c) + unmap_vmas (0xffffffff81199174) + exit_mmap (0xffffffff811a1f5b) + mmput (0xffffffff8107699a) + flush_old_exec (0xffffffff811ddb75) + load_elf_binary (0xffffffff812287df) + search_binary_handler (0xffffffff811dd3e0) + do_execveat_common.isra.31 (0xffffffff811de8bd) + do_execve (0xffffffff811dea8c) + SyS_execve (0xffffffff811ded1e) + return_to_handler (0xffffffff816c8458) + --- + +The above uses *-F* to follow the sleep task. It filters only on events +that pertain to sleep. Note, in order to follow forks, you need to also +include the *-c* flag. + +Other tasks will appear in the profile as well if events reference more +than one task (like sched_switch and sched_wakeup do. The "prev_pid" and +"next_pid" of sched_switch, and the "common_pid" and "pid" of sched_wakeup). + +Stack traces are attached to events that are related to them. + +Taking a look at the above output: + + Event: sched_switch:R (2) Total: 234559 Avg: 117279 Max: 129886 Min:104673 + +This shows that task was preempted (it's in the running 'R' state). +It was preempted twice '(2)' for a total of 234,559 nanoseconds, with a average +preempt time of 117,279 ns, and maximum of 128,886 ns and minimum of 104,673 ns. + +The tree shows where it was preempted: + + + | + + ftrace_raw_event_sched_switch (0xffffffff8109f310) + 100% (2) time:234559 max:129886 min:104673 avg:117279 + __schedule (0xffffffff816c1e81) + preempt_schedule (0xffffffff816c236e) + ___preempt_schedule (0xffffffff81351a59) + | + + unmap_single_vma (0xffffffff81198c05) + | 55% (1) time:129886 max:129886 min:0 avg:129886 + | stop_one_cpu (0xffffffff8110909a) + | sched_exec (0xffffffff810a119b) + | do_execveat_common.isra.31 (0xffffffff811de528) + | do_execve (0xffffffff811dea8c) + | SyS_execve (0xffffffff811ded1e) + | return_to_handler (0xffffffff816c8458) + | stub_execve (0xffffffff816c6929) + | + + unmap_single_vma (0xffffffff81198c05) + 45% (1) time:104673 max:104673 min:0 avg:104673 + unmap_vmas (0xffffffff81199174) + exit_mmap (0xffffffff811a1f5b) + mmput (0xffffffff8107699a) + flush_old_exec (0xffffffff811ddb75) + load_elf_binary (0xffffffff812287df) + search_binary_handler (0xffffffff811dd3e0) + do_execveat_common.isra.31 (0xffffffff811de8bd) + do_execve (0xffffffff811dea8c) + SyS_execve (0xffffffff811ded1e) + return_to_handler (0xffffffff816c8458) + stub_execve (0xffffffff816c6929) + + + Event: sched_switch:S (1) Total: 1000513242 Avg: 1000513242 Max: 1000513242 Min:10005132 + +This shows that the task was scheduled out in the INTERRUPTIBLE state once +for a total of 1,000,513,242 ns (~1s), which makes sense as the task was a +"sleep 1". + +After the schedule events, the function events are shown. By default the +profiler will use the function graph tracer if the depth setting is supported +by the kernel. It will set the depth to one which will only trace the first +function that enters the kernel. It will also record the amount of time +it was in the kernel. + + Event: func: sys_nanosleep() (1) Total: 1000598016 Avg: 1000598016 Max: 1000598016 Min:1000598016 + Event: func: sys_munmap() (1) Total: 14300 Avg: 14300 Max: 14300 Min:14300 + Event: func: sys_arch_prctl() (1) Total: 571 Avg: 571 Max: 571 Min:571 + Event: func: sys_mprotect() (4) Total: 14382 Avg: 3595 Max: 7196 Min:2190 + Event: func: SyS_read() (1) Total: 2640 Avg: 2640 Max: 2640 Min:2640 + Event: func: sys_close() (5) Total: 4001 Avg: 800 Max: 1252 Min:414 + Event: func: sys_newfstat() (3) Total: 11684 Avg: 3894 Max: 10206 Min:636 + Event: func: SyS_open() (3) Total: 23615 Avg: 7871 Max: 10535 Min:4743 + Event: func: sys_access() (1) Total: 5924 Avg: 5924 Max: 5924 Min:5924 + Event: func: SyS_mmap() (8) Total: 39153 Avg: 4894 Max: 12354 Min:1518 + Event: func: smp_trace_apic_timer_interrupt() (1) Total: 10298 Avg: 10298 Max: 10298 Min:10298 + Event: func: SyS_brk() (4) Total: 2407 Avg: 601 Max: 1564 Min:206 + Event: func: do_notify_resume() (2) Total: 4095 Avg: 2047 Max: 2521 Min:1574 + Event: func: sys_execve() (5) Total: 1625251 Avg: 325050 Max: 1605698 Min:3570 + + +Count of times the event was hit is always in parenthesis '(5)'. + +The function graph trace may produce too much overhead as it is still +triggering (just not tracing) on all functions. To limit functions just to +system calls (not interrupts), add the following option: + + -l 'sys_*' -l 'SyS_*' + +To disable function graph tracing totally, use: + + -p nop + +To use function tracing instead (note, this will not record timings, but just +the count of times a function is hit): + + -p function + + +Following the functions are the events that are recorded. + + + Event: sys_enter:35 (1) Total: 1000599765 Avg: 1000599765 Max: 1000599765 Min:1000599765 + Event: sys_enter:11 (1) Total: 55025 Avg: 55025 Max: 55025 Min:55025 + Event: sys_enter:158 (1) Total: 1584 Avg: 1584 Max: 1584 Min:1584 + Event: sys_enter:10 (4) Total: 18359 Avg: 4589 Max: 8764 Min:2933 + Event: sys_enter:0 (1) Total: 4223 Avg: 4223 Max: 4223 Min:4223 + Event: sys_enter:3 (5) Total: 9948 Avg: 1989 Max: 2606 Min:1203 + Event: sys_enter:5 (3) Total: 15530 Avg: 5176 Max: 11840 Min:1405 + Event: sys_enter:2 (3) Total: 28002 Avg: 9334 Max: 12035 Min:5656 + Event: sys_enter:21 (1) Total: 7814 Avg: 7814 Max: 7814 Min:7814 + Event: sys_enter:9 (8) Total: 49583 Avg: 6197 Max: 14137 Min:2362 + Event: sys_enter:12 (4) Total: 108493 Avg: 27123 Max: 104079 Min:922 + Event: sys_enter:59 (5) Total: 1631608 Avg: 326321 Max: 1607529 Min:4563 + +These are the raw system call events, with the raw system call ID after +the "sys_enter:" For example, "59" is execve(2). Why did it execute 5 times? +Looking at a strace of this run, we can see: + + execve("/usr/lib64/ccache/sleep", ["sleep", "1"], [/* 27 vars */] <unfinished ...> + <... execve resumed> ) = -1 ENOENT (No such file or directory) + execve("/usr/local/sbin/sleep", ["sleep", "1"], [/* 27 vars */] <unfinished ...> + <... execve resumed> ) = -1 ENOENT (No such file or directory) + execve("/usr/local/bin/sleep", ["sleep", "1"], [/* 27 vars */] <unfinished ...> + <... execve resumed> ) = -1 ENOENT (No such file or directory) + execve("/usr/sbin/sleep", ["sleep", "1"], [/* 27 vars */] <unfinished ...> + <... execve resumed> ) = -1 ENOENT (No such file or directory) + execve("/usr/bin/sleep", ["sleep", "1"], [/* 27 vars */] <unfinished ...> + <... execve resumed> ) = 0 + +It attempted to execve the "sleep" command for each path in $PATH until it found +one. + +The page_fault_user events show what userspace address took a page fault. + + Event: softirq_raise:RCU (3) Total: 252931 Avg: 84310 Max: 243288 Min:4639 + Event: softirq_raise:SCHED (2) Total: 241249 Avg: 120624 Max: 239076 Min:2173 + | + + ftrace_raw_event_sched_wakeup_template (0xffffffff8109d960) + 100% (1) time:239076 max:239076 min:0 avg:239076 + ttwu_do_wakeup (0xffffffff810a01a2) + ttwu_do_activate.constprop.122 (0xffffffff810a0236) + try_to_wake_up (0xffffffff810a3ec3) + default_wake_function (0xffffffff810a4002) + autoremove_wake_function (0xffffffff810b50fd) + __wake_up_common (0xffffffff810b4958) + __wake_up (0xffffffff810b4cb8) + rb_wake_up_waiters (0xffffffff8112f126) + irq_work_run_list (0xffffffff81157d0f) + irq_work_run (0xffffffff81157d5e) + smp_trace_irq_work_interrupt (0xffffffff810082fc) + trace_irq_work_interrupt (0xffffffff816c7aaa) + irq_exit (0xffffffff8107dd66) + +The timings for the softirq_raise events measure the time it took from the raised +softirq to the time it executed. + +The timings for the softirq_entry events measure the time the softirq took to +execute. + +The stack traces for the softirqs (and possibly other events) are used when +an event has a stack attached to it. This can happen if the profile ran +more stacks than just the sched events, or when events are dropped and +stacks + + +To have full control of what gets traced, use the *-S* option that will have +trace-cmd not enable any events or the function_graph tracer. Only the events +listed on the command line are shown. + +If only the time of kmalloc is needed to be seen, and where it was recorded, +using the *-S* option and enabling function_graph and stack tracing for just +the function needed will give the profile of only that function. + + --- +# trace-cmd profile -S -p function_graph -l '*kmalloc*' -l '*kmalloc*:stacktrace' sleep 1 +task: sshd-11786 + Event: func: __kmalloc_reserve.isra.59() (2) Total: 149684 Avg: 74842 Max: 75598 Min:74086 + | + + __alloc_skb (0xffffffff815a8917) + | 67% (2) time:149684 max:75598 min:74086 avg:74842 + | __kmalloc_node_track_caller (0xffffffff811c6635) + | __kmalloc_reserve.isra.59 (0xffffffff815a84ac) + | return_to_handler (0xffffffff816c8458) + | sk_stream_alloc_skb (0xffffffff81604ea1) + | tcp_sendmsg (0xffffffff8160592c) + | inet_sendmsg (0xffffffff8162fed1) + | sock_aio_write (0xffffffff8159f9fc) + | do_sync_write (0xffffffff811d694a) + | vfs_write (0xffffffff811d7825) + | SyS_write (0xffffffff811d7adf) + | system_call_fastpath (0xffffffff816c63d2) + | + + __alloc_skb (0xffffffff815a8917) + 33% (1) time:74086 max:74086 min:74086 avg:74086 + __alloc_skb (0xffffffff815a8917) + sk_stream_alloc_skb (0xffffffff81604ea1) + tcp_sendmsg (0xffffffff8160592c) + inet_sendmsg (0xffffffff8162fed1) + sock_aio_write (0xffffffff8159f9fc) + do_sync_write (0xffffffff811d694a) + vfs_write (0xffffffff811d7825) + SyS_write (0xffffffff811d7adf) + system_call_fastpath (0xffffffff816c63d2) + [..] +--- + +To watch the command run but save the output of the profile to a file +use --stderr, and redirect stderr to a file + +# trace-cmd profile --stderr cyclictest -p 80 -n -t1 2> profile.out + +Or simple use *-o* + +# trace-cmd profile -o profile.out cyclictest -p 80 -n -t1 + +SEE ALSO +-------- +trace-cmd(1), trace-cmd-record(1), trace-cmd-report(1), trace-cmd-start(1), +trace-cmd-stop(1), trace-cmd-reset(1), trace-cmd-split(1), +trace-cmd-list(1), trace-cmd-listen(1) + +AUTHOR +------ +Written by Steven Rostedt, <rostedt@goodmis.org> + +RESOURCES +--------- +https://git.kernel.org/pub/scm/utils/trace-cmd/trace-cmd.git/ + +COPYING +------- +Copyright \(C) 2014 Red Hat, Inc. Free use of this software is granted under +the terms of the GNU Public License (GPL). + diff --git a/Documentation/trace-cmd/trace-cmd-record.1.txt b/Documentation/trace-cmd/trace-cmd-record.1.txt new file mode 100644 index 00000000..6b8e3b4a --- /dev/null +++ b/Documentation/trace-cmd/trace-cmd-record.1.txt @@ -0,0 +1,519 @@ +TRACE-CMD-RECORD(1) +=================== + +NAME +---- +trace-cmd-record - record a trace from the Ftrace Linux internal tracer + +SYNOPSIS +-------- +*trace-cmd record* ['OPTIONS'] ['command'] + +DESCRIPTION +----------- +The trace-cmd(1) record command will set up the Ftrace Linux kernel tracer to +record the specified plugins or events that happen while the 'command' +executes. If no command is given, then it will record until the user hits +Ctrl-C. + +The record command of trace-cmd will set up the Ftrace tracer to start tracing +the various events or plugins that are given on the command line. It will then +create a number of tracing processes (one per CPU) that will start recording +from the kernel ring buffer straight into temporary files. When the command is +complete (or Ctrl-C is hit) all the files will be combined into a trace.dat +file that can later be read (see trace-cmd-report(1)). + +OPTIONS +------- +*-p* 'tracer':: + Specify a tracer. Tracers usually do more than just trace an event. + Common tracers are: *function*, *function_graph*, *preemptirqsoff*, + *irqsoff*, *preemptoff* and *wakeup*. A tracer must be supported by the + running kernel. To see a list of available tracers, see trace-cmd-list(1). + +*-e* 'event':: + Specify an event to trace. Various static trace points have been added to + the Linux kernel. They are grouped by subsystem where you can enable all + events of a given subsystem or specify specific events to be enabled. The + 'event' is of the format "subsystem:event-name". You can also just specify + the subsystem without the ':event-name' or the event-name without the + "subsystem:". Using "-e sched_switch" will enable the "sched_switch" event + where as, "-e sched" will enable all events under the "sched" subsystem. + + The 'event' can also contain glob expressions. That is, "*stat*" will + select all events (or subsystems) that have the characters "stat" in their + names. + + The keyword 'all' can be used to enable all events. + +*-a*:: + Every event that is being recorded has its output format file saved + in the output file to be able to display it later. But if other + events are enabled in the trace without trace-cmd's knowledge, the + formats of those events will not be recorded and trace-cmd report will + not be able to display them. If this is the case, then specify the + *-a* option and the format for all events in the system will be saved. + +*-T*:: + Enable a stacktrace on each event. For example: + + <idle>-0 [003] 58549.289091: sched_switch: kworker/0:1:0 [120] R ==> trace-cmd:2603 [120] + <idle>-0 [003] 58549.289092: kernel_stack: <stack trace> +=> schedule (ffffffff814b260e) +=> cpu_idle (ffffffff8100a38c) +=> start_secondary (ffffffff814ab828) + +*--func-stack*:: + Enable a stack trace on all functions. Note this is only applicable + for the "function" plugin tracer, and will only take effect if the + -l option is used and succeeds in limiting functions. If the function + tracer is not filtered, and the stack trace is enabled, you can live + lock the machine. + +*-f* 'filter':: + Specify a filter for the previous event. This must come after a *-e*. This + will filter what events get recorded based on the content of the event. + Filtering is passed to the kernel directly so what filtering is allowed + may depend on what version of the kernel you have. Basically, it will + let you use C notation to check if an event should be processed or not. + +---------------------------------------- + ==, >=, <=, >, <, &, |, && and || +---------------------------------------- + + The above are usually safe to use to compare fields. + +*--no-filter*:: + Do not filter out the trace-cmd threads. By default, the threads are + filtered out to not be traced by events. This option will have the trace-cmd + threads also be traced. + +*-R* 'trigger':: + Specify a trigger for the previous event. This must come after a *-e*. + This will add a given trigger to the given event. To only enable the trigger + and not the event itself, then place the event after the *-v* option. + + See Documentation/trace/events.txt in the Linux kernel source for more + information on triggers. + +*-v*:: + This will cause all events specified after it on the command line to not + be traced. This is useful for selecting a subsystem to be traced but to + leave out various events. For Example: "-e sched -v -e "\*stat\*"" will + enable all events in the sched subsystem except those that have "stat" in + their names. + + Note: the *-v* option was taken from the way grep(1) inverts the following + matches. + +*-F*:: + This will filter only the executable that is given on the command line. If + no command is given, then it will filter itself (pretty pointless). + Using *-F* will let you trace only events that are caused by the given + command. + +*-P* 'pid':: + Similar to *-F* but lets you specify a process ID to trace. + +*-c*:: + Used with either *-F* (or *-P* if kernel supports it) to trace the process' + children too. + +*--user*:: + Execute the specified *command* as given user. + +*-C* 'clock':: + Set the trace clock to "clock". + + Use trace-cmd(1) list -C to see what clocks are available. + +*-o* 'output-file':: + By default, trace-cmd report will create a 'trace.dat' file. You can + specify a different file to write to with the *-o* option. + +*-l* 'function-name':: + This will limit the 'function' and 'function_graph' tracers to only trace + the given function name. More than one *-l* may be specified on the + command line to trace more than one function. This supports both full + regex(3) parsing, or basic glob parsing. If the filter has only alphanumeric, + '_', '*', '?' and '.' characters, then it will be parsed as a basic glob. + to force it to be a regex, prefix the filter with '^' or append it with '$' + and it will then be parsed as a regex. + +*-g* 'function-name':: + This option is for the function_graph plugin. It will graph the given + function. That is, it will only trace the function and all functions that + it calls. You can have more than one *-g* on the command line. + +*-n* 'function-name':: + This has the opposite effect of *-l*. The function given with the *-n* + option will not be traced. This takes precedence, that is, if you include + the same function for both *-n* and *-l*, it will not be traced. + +*-d*:: + Some tracer plugins enable the function tracer by default. Like the + latency tracers. This option prevents the function tracer from being + enabled at start up. + +*-D*:: + The option *-d* will try to use the function-trace option to disable the + function tracer (if available), otherwise it defaults to the proc file: + /proc/sys/kernel/ftrace_enabled, but will not touch it if the function-trace + option is available. The *-D* option will disable both the ftrace_enabled + proc file as well as the function-trace option if it exists. + + Note, this disable function tracing for all users, which includes users + outside of ftrace tracers (stack_tracer, perf, etc). + +*-O* 'option':: + Ftrace has various options that can be enabled or disabled. This allows + you to set them. Appending the text 'no' to an option disables it. + For example: "-O nograph-time" will disable the "graph-time" Ftrace + option. + +*-s* 'interval':: + The processes that trace-cmd creates to record from the ring buffer need + to wake up to do the recording. Setting the 'interval' to zero will cause + the processes to wakeup every time new data is written into the buffer. + But since Ftrace is recording kernel activity, the act of this processes + going back to sleep may cause new events into the ring buffer which will + wake the process back up. This will needlessly add extra data into the + ring buffer. + + The 'interval' metric is microseconds. The default is set to 1000 (1 ms). + This is the time each recording process will sleep before waking up to + record any new data that was written to the ring buffer. + +*-r* 'priority':: + The priority to run the capture threads at. In a busy system the trace + capturing threads may be staved and events can be lost. This increases + the priority of those threads to the real time (FIFO) priority. + But use this option with care, it can also change the behaviour of + the system being traced. + +*-b* 'size':: + This sets the ring buffer size to 'size' kilobytes. Because the Ftrace + ring buffer is per CPU, this size is the size of each per CPU ring buffer + inside the kernel. Using "-b 10000" on a machine with 4 CPUs will make + Ftrace have a total buffer size of 40 Megs. + +*-B* 'buffer-name':: + If the kernel supports multiple buffers, this will add a buffer with + the given name. If the buffer name already exists, that buffer is just + reset and will not be deleted at the end of record execution. If the + buffer is created, it will be removed at the end of execution (unless + the *-k* is set, or 'start' command was used). + + After a buffer name is stated, all events added after that will be + associated with that buffer. If no buffer is specified, or an event + is specified before a buffer name, it will be associated with the + main (toplevel) buffer. + + trace-cmd record -e sched -B block -e block -B time -e timer sleep 1 + + The above is will enable all sched events in the main buffer. It will + then create a 'block' buffer instance and enable all block events within + that buffer. A 'time' buffer instance is created and all timer events + will be enabled for that event. + +*-m* 'size':: + The max size in kilobytes that a per cpu buffer should be. Note, due + to rounding to page size, the number may not be totally correct. + Also, this is performed by switching between two buffers that are half + the given size thus the output may not be of the given size even if + much more was written. + + Use this to prevent running out of diskspace for long runs. + +*-M* 'cpumask':: + Set the cpumask for to trace. It only affects the last buffer instance + given. If supplied before any buffer instance, then it affects the + main buffer. The value supplied must be a hex number. + + trace-cmd record -p function -M c -B events13 -e all -M 5 + + If the -M is left out, then the mask stays the same. To enable all + CPUs, pass in a value of '-1'. + +*-k*:: + By default, when trace-cmd is finished tracing, it will reset the buffers + and disable all the tracing that it enabled. This option keeps trace-cmd + from disabling the tracer and reseting the buffer. This option is useful for + debugging trace-cmd. + + Note: usually trace-cmd will set the "tracing_on" file back to what it + was before it was called. This option will leave that file set to zero. + +*-i*:: + By default, if an event is listed that trace-cmd does not find, it + will exit with an error. This option will just ignore events that are + listed on the command line but are not found on the system. + +*-N* 'host:port':: + If another machine is running "trace-cmd listen", this option is used to + have the data sent to that machine with UDP packets. Instead of writing + to an output file, the data is sent off to a remote box. This is ideal for + embedded machines with little storage, or having a single machine that + will keep all the data in a single repository. + + Note: This option is not supported with latency tracer plugins: + wakeup, wakeup_rt, irqsoff, preemptoff and preemptirqsoff + +*-V* 'cid:port':: + If recording on a guest VM and the host is running *trace-cmd listen* with + the *-V* option as well, or if this is recording on the host, and a guest + in running *trace-cmd listen* with the *-V* option, then connect to the + listener (the same as connecting with the *-N* option via the network). + This has the same limitations as the *-N* option above with respect to + latency tracer plugins. + +*-t*:: + This option is used with *-N*, when there's a need to send the live data + with TCP packets instead of UDP. Although TCP is not nearly as fast as + sending the UDP packets, but it may be needed if the network is not that + reliable, the amount of data is not that intensive, and a guarantee is + needed that all traced information is transfered successfully. + +*-q* | *--quiet*:: + For use with recording an application. Suppresses normal output + (except for errors) to allow only the application's output to be displayed. + +*--date*:: + With the *--date* option, "trace-cmd" will write timestamps into the + trace buffer after it has finished recording. It will then map the + timestamp to gettimeofday which will allow wall time output from the + timestamps reading the created 'trace.dat' file. + +*--max-graph-depth* 'depth':: + Set the maximum depth the function_graph tracer will trace into a function. + A value of one will only show where userspace enters the kernel but not any + functions called in the kernel. The default is zero, which means no limit. + +*--cmdlines-size* 'size':: + Set the number of entries the kernel tracing file "saved_cmdlines" can + contain. This file is a circular buffer which stores the mapping between + cmdlines and PIDs. If full, it leads to unresolved cmdlines ("<...>") within + the trace. The kernel default value is 128. + +*--module* 'module':: + Filter a module's name in function tracing. It is equivalent to adding + ':mod:module' after all other functions being filtered. If no other function + filter is listed, then all modules functions will be filtered in the filter. + + '--module snd' is equivalent to '-l :mod:snd' + + '--module snd -l "*jack*"' is equivalent to '-l "*jack*:mod:snd"' + + '--module snd -n "*"' is equivalent to '-n :mod:snd' + +*--proc-map*:: + Save the traced process address map into the trace.dat file. The traced + processes can be specified using the option *-P*, or as a given 'command'. + +*--profile*:: + With the *--profile* option, "trace-cmd" will enable tracing that can + be used with trace-cmd-report(1) --profile option. If a tracer *-p* is + not set, and function graph depth is supported by the kernel, then + the function_graph tracer will be enabled with a depth of one (only + show where userspace enters into the kernel). It will also enable + various tracepoints with stack tracing such that the report can show + where tasks have been blocked for the longest time. + + See trace-cmd-profile(1) for more details and examples. + +*-G*:: + Set interrupt (soft and hard) events as global (associated to CPU + instead of tasks). Only works for --profile. + +*-H* 'event-hooks':: + Add custom event matching to connect any two events together. When not + used with *--profile*, it will save the parameter and this will be + used by trace-cmd report --profile, too. That is: + + trace-cmd record -H hrtimer_expire_entry,hrtimer/hrtimer_expire_exit,hrtimer,sp + trace-cmd report --profile + + Will profile hrtimer_expire_entry and hrtimer_expire_ext times. + + See trace-cmd-profile(1) for format. + +*-S*:: (for --profile only) + Only enable the tracer or events speficied on the command line. + With this option, the function_graph tracer is not enabled, nor are + any events (like sched_switch), unless they are specifically specified + on the command line (i.e. -p function -e sched_switch -e sched_wakeup) + +*--ts-offset offset*:: + Add an offset for the timestamp in the trace.dat file. This will add a + offset option into the trace.dat file such that a trace-cmd report will + offset all the timestamps of the events by the given offset. The offset + is in raw units. That is, if the event timestamps are in nanoseconds + the offset will also be in nanoseconds even if the displayed units are + in microseconds. + +*--tsync-interval*:: + Set the loop interval, in ms, for timestamps synchronization with guests: + If a negative number is specified, timestamps synchronization is disabled + If 0 is specified, no loop is performed - timestamps offset is calculated only twice," + at the beginning and at the end of the trace. + Timestamps synchronization with guests works only if there is support for VSOCK.\n" + +*--tsc2nsec*:: + Convert the current clock to nanoseconds, using tsc multiplier and shift from the Linux + kernel's perf interface. This option does not change the trace clock, just assumes that + the tsc multiplier and shift are applicable for the selected clock. You may use the + "-C tsc2nsec" clock, if not sure what clock to select. +*--stderr*:: + Have output go to stderr instead of stdout, but the output of the command + executed will not be changed. This is useful if you want to monitor the + output of the command being executed, but not see the output from trace-cmd. + +*--poll*:: + Waiting for data to be available on the trace ring-buffers may trigger + IPIs. This might generate unacceptable trace noise when tracing low latency + or real time systems. The poll option forces trace-cmd to use O_NONBLOCK. + Traces are extracted by busy waiting, which will hog the CPUs, so only use + when really needed. + +*--name*:: + Give a specific name for the current agent being processed. Used after *-A* to + give the guest being traced a name. Useful when using the vsocket ID instead of + a name of the guest. + +*--verbose*[='level']:: + Set the log level. Supported log levels are "none", "critical", "error", "warning", + "info", "debug", "all" or their identifiers "0", "1", "2", "3", "4", "5", "6". Setting the log + level to specific value enables all logs from that and all previous levels. + The level will default to "info" if one is not specified. + + Example: enable all critical, error and warning logs + + trace-cmd record --verbose=warning + +*--file-version*:: + Desired version of the output file. Supported versions are 6 or 7. + +*--compression*:: + Compression of the trace output file, one of these strings can be passed: + + 'any' - auto select the best available compression algorithm + + 'none' - do not compress the trace file + + 'name' - the name of the desired compression algorithms. Available algorithms can be listed with + trace-cmd list -c + +EXAMPLES +-------- + +The basic way to trace all events: + +------------------------------ + # trace-cmd record -e all ls > /dev/null + # trace-cmd report + trace-cmd-13541 [003] 106260.693809: filemap_fault: address=0x128122 offset=0xce + trace-cmd-13543 [001] 106260.693809: kmalloc: call_site=81128dd4 ptr=0xffff88003dd83800 bytes_req=768 bytes_alloc=1024 gfp_flags=GFP_KERNEL|GFP_ZERO + ls-13545 [002] 106260.693809: kfree: call_site=810a7abb ptr=0x0 + ls-13545 [002] 106260.693818: sys_exit_write: 0x1 + + +------------------------------ + + + +To use the function tracer with sched switch tracing: + +------------------------------ + # trace-cmd record -p function -e sched_switch ls > /dev/null + # trace-cmd report + ls-13587 [002] 106467.860310: function: hrtick_start_fair <-- pick_next_task_fair + ls-13587 [002] 106467.860313: sched_switch: prev_comm=trace-cmd prev_pid=13587 prev_prio=120 prev_state=R ==> next_comm=trace-cmd next_pid=13583 next_prio=120 + trace-cmd-13585 [001] 106467.860314: function: native_set_pte_at <-- __do_fault + trace-cmd-13586 [003] 106467.860314: function: up_read <-- do_page_fault + ls-13587 [002] 106467.860317: function: __phys_addr <-- schedule + trace-cmd-13585 [001] 106467.860318: function: _raw_spin_unlock <-- __do_fault + ls-13587 [002] 106467.860320: function: native_load_sp0 <-- __switch_to + trace-cmd-13586 [003] 106467.860322: function: down_read_trylock <-- do_page_fault + + +------------------------------ + +Here is a nice way to find what interrupts have the highest latency: +------------------------------------------ + # trace-cmd record -p function_graph -e irq_handler_entry -l do_IRQ sleep 10 + # trace-cmd report + <idle>-0 [000] 157412.933969: funcgraph_entry: | do_IRQ() { + <idle>-0 [000] 157412.933974: irq_handler_entry: irq=48 name=eth0 + <idle>-0 [000] 157412.934004: funcgraph_exit: + 36.358 us | } + <idle>-0 [000] 157413.895004: funcgraph_entry: | do_IRQ() { + <idle>-0 [000] 157413.895011: irq_handler_entry: irq=48 name=eth0 + <idle>-0 [000] 157413.895026: funcgraph_exit: + 24.014 us | } + <idle>-0 [000] 157415.891762: funcgraph_entry: | do_IRQ() { + <idle>-0 [000] 157415.891769: irq_handler_entry: irq=48 name=eth0 + <idle>-0 [000] 157415.891784: funcgraph_exit: + 22.928 us | } + <idle>-0 [000] 157415.934869: funcgraph_entry: | do_IRQ() { + <idle>-0 [000] 157415.934874: irq_handler_entry: irq=48 name=eth0 + <idle>-0 [000] 157415.934906: funcgraph_exit: + 37.512 us | } + <idle>-0 [000] 157417.888373: funcgraph_entry: | do_IRQ() { + <idle>-0 [000] 157417.888381: irq_handler_entry: irq=48 name=eth0 + <idle>-0 [000] 157417.888398: funcgraph_exit: + 25.943 us | } + + +------------------------------------------ + +An example of the profile: +------------------------------------------ + # trace-cmd record --profile sleep 1 + # trace-cmd report --profile --comm sleep +task: sleep-21611 + Event: sched_switch:R (1) Total: 99442 Avg: 99442 Max: 99442 Min:99442 + <stack> 1 total:99442 min:99442 max:99442 avg=99442 + => ftrace_raw_event_sched_switch (0xffffffff8105f812) + => __schedule (0xffffffff8150810a) + => preempt_schedule (0xffffffff8150842e) + => ___preempt_schedule (0xffffffff81273354) + => cpu_stop_queue_work (0xffffffff810b03c5) + => stop_one_cpu (0xffffffff810b063b) + => sched_exec (0xffffffff8106136d) + => do_execve_common.isra.27 (0xffffffff81148c89) + => do_execve (0xffffffff811490b0) + => SyS_execve (0xffffffff811492c4) + => return_to_handler (0xffffffff8150e3c8) + => stub_execve (0xffffffff8150c699) + Event: sched_switch:S (1) Total: 1000506680 Avg: 1000506680 Max: 1000506680 Min:1000506680 + <stack> 1 total:1000506680 min:1000506680 max:1000506680 avg=1000506680 + => ftrace_raw_event_sched_switch (0xffffffff8105f812) + => __schedule (0xffffffff8150810a) + => schedule (0xffffffff815084b8) + => do_nanosleep (0xffffffff8150b22c) + => hrtimer_nanosleep (0xffffffff8108d647) + => SyS_nanosleep (0xffffffff8108d72c) + => return_to_handler (0xffffffff8150e3c8) + => tracesys_phase2 (0xffffffff8150c304) + Event: sched_wakeup:21611 (1) Total: 30326 Avg: 30326 Max: 30326 Min:30326 + <stack> 1 total:30326 min:30326 max:30326 avg=30326 + => ftrace_raw_event_sched_wakeup_template (0xffffffff8105f653) + => ttwu_do_wakeup (0xffffffff810606eb) + => ttwu_do_activate.constprop.124 (0xffffffff810607c8) + => try_to_wake_up (0xffffffff8106340a) +------------------------------------------ + +SEE ALSO +-------- +trace-cmd(1), trace-cmd-report(1), trace-cmd-start(1), trace-cmd-stop(1), +trace-cmd-extract(1), trace-cmd-reset(1), trace-cmd-split(1), +trace-cmd-list(1), trace-cmd-listen(1), trace-cmd-profile(1) + +AUTHOR +------ +Written by Steven Rostedt, <rostedt@goodmis.org> + +RESOURCES +--------- +https://git.kernel.org/pub/scm/utils/trace-cmd/trace-cmd.git/ + +COPYING +------- +Copyright \(C) 2010 Red Hat, Inc. Free use of this software is granted under +the terms of the GNU Public License (GPL). + diff --git a/Documentation/trace-cmd/trace-cmd-report.1.txt b/Documentation/trace-cmd/trace-cmd-report.1.txt new file mode 100644 index 00000000..aad8ab51 --- /dev/null +++ b/Documentation/trace-cmd/trace-cmd-report.1.txt @@ -0,0 +1,518 @@ +TRACE-CMD-REPORT(1) +=================== + +NAME +---- +trace-cmd-report - show in ASCII a trace created by trace-cmd record + +SYNOPSIS +-------- +*trace-cmd report* ['OPTIONS'] ['input-file'] + +DESCRIPTION +----------- +The trace-cmd(1) report command will output a human readable report of a trace +created by trace-cmd record. + +OPTIONS +------- +*-i* 'input-file':: + By default, trace-cmd report will read the file 'trace.dat'. But the *-i* + option open up the given 'input-file' instead. Note, the input file may + also be specified as the last item on the command line. + +*-e*:: + This outputs the endianess of the file. trace-cmd report is smart enough + to be able to read big endian files on little endian machines, and vise + versa. + +*-f*:: + This outputs the list of all functions that have been mapped in the trace.dat file. + Note, this list may contain functions that may not appear in the trace, as + it is the list of mappings to translate function addresses into function names. + +*-P*:: + This outputs the list of "trace_printk()" data. The raw trace data points + to static pointers in the kernel. This must be stored in the trace.dat + file. + +*-E*:: + This lists the possible events in the file (but this list is not + necessarily the list of events in the file). + +*--events*:: + This will list the event formats that are stored in the trace.dat file. + +*--event* regex:: + This will print events that match the given regex. If a colon is specified, + then the characters before the colon will be used to match the system and + the characters after the colon will match the event. + + trace-cmd report --event sys:read + + The above will only match events where the system name contains "sys" + and the event name contains "read". + + trace-cmd report --event read + + The above will match all events that contain "read" in its name. Also it + may list all events of a system that contains "read" as well. + +*--check-events*:: + This will parse the event format strings that are stored in the trace.dat + file and return whether the formats can be parsed correctly. It will load + plugins unless *-N* is specified. + +*-t*:: + Print the full timestamp. The timestamps in the data file are usually + recorded to the nanosecond. But the default display of the timestamp + is only to the microsecond. To see the full timestamp, add the *-t* option. + +*-F* 'filter':: + Add a filter to limit what events are displayed. The format of the filter + is: + +------------------------------------------ + <events> ':' <filter> + <events> = SYSTEM'/'EVENT | SYSTEM | EVENT | <events> ',' <events> + <filter> = EVENT_FIELD <op> <value> | <filter> '&&' <filter> | + <filter> '||' <filter> | '(' <filter> ')' | '!' <filter> + <op> = '==' | '!=' | '>=' | '<=' | '>' | '<' | '&' | '|' | '^' | + '+' | '-' | '*' | '/' | '%' + <value> = NUM | STRING | EVENT_FIELD +------------------------------------------ + + SYSTEM is the name of the system to filter on. If the EVENT is left out, + then it applies to all events under the SYSTEM. If only one string is used + without the '/' to deliminate between SYSTEM and EVENT, then the filter + will be applied to all systems and events that match the given string. + + Whitespace is ignored, such that "sched:next_pid==123" is equivalent to + "sched : next_pid == 123". + + STRING is defined with single or double quotes (single quote must end with + single quote, and double with double). Whitespace within quotes are not + ignored. + + The representation of a SYSTEM or EVENT may also be a regular expression + as defined by 'regcomp(3)'. + + The EVENT_FIELD is the name of the field of an event that is being + filtered. If the event does not contain the EVENT_FIELD, that part of the + equation will be considered false. + +------------------------------------------ + -F 'sched : bogus == 1 || common_pid == 2' +------------------------------------------ + + The "bogus == 1" will always evaluate to FALSE because no event has a + field called "bogus", but the "common_pid == 2" will still be evaluated + since all events have the field "common_pid". Any "sched" event that was + traced by the process with the PID of 2 will be shown. + + Note, the EVENT_FIELD is the field name as shown by an events format + (as displayed with *--events*), and not what is found in the output. + If the output shows "ID:foo" but the field that "foo" belongs to was + called "name" in the event format, then "name" must be used in the filter. + The same is true about values. If the value that is displayed is converted + by to a string symbol, the filter checks the original value and not the + value displayed. For example, to filter on all tasks that were in the + running state at a context switch: + +------------------------------------------ + -F 'sched/sched_switch : prev_state==0' +------------------------------------------ + + Although the output displays 'R', having 'prev_stat=="R"' will not work. + + Note: You can also specify 'COMM' as an EVENT_FIELD. This will use the + task name (or comm) of the record to compare. For example, to filter out + all of the "trace-cmd" tasks: + +------------------------------------------ + -F '.*:COMM != "trace-cmd"' +------------------------------------------ + +*-I*:: + Do not print events where the HARDIRQ latency flag is set. + This will filter out most events that are from interrupt context. + Note, it may not filter out function traced functions that are + in interrupt context but were called before the kernel "in interrupt" + flag was set. + +*-S*:: + Do not print events where the SOFTIRQ latency flag is set. + This will filter out most events that are from soft interrupt context. + +*-v*:: + This causes the following filters of *-F* to filter out the matching + events. + +------------------------------------------ + -v -F 'sched/sched_switch : prev_state == 0' +------------------------------------------ + + Will not display any sched_switch events that have a prev_state of 0. + Removing the *-v* will only print out those events. + +*-T*:: + Test the filters of -F. After processing a filter string, the + resulting filter will be displayed for each event. This is useful + for using a filter for more than one event where a field may not + exist in all events. Also it can be used to make sure there are no + misspelled event field names, as they will simply be ignored. + *-T* is ignored if *-F* is not specified. + +*-V*:: + Show verbose messages (see *--verbose* but only for the numbers) + +*-L*:: + This will not load system wide plugins. It loads "local only". That is + what it finds in the ~/.trace-cmd/plugins directory. + +*-N*:: + This will not load any plugins. + +*-n* 'event-re':: + This will cause all events that match the option to ignore any registered + handler (by the plugins) to print the event. The normal event will be printed + instead. The 'event-re' is a regular expression as defined by 'regcomp(3)'. + +*--profile*:: + With the *--profile* option, "trace-cmd report" will process all the events + first, and then output a format showing where tasks have spent their time + in the kernel, as well as where they are blocked the most, and where wake up + latencies are. + + See trace-cmd-profile(1) for more details and examples. + +*-G*:: + Set interrupt (soft and hard) events as global (associated to CPU + instead of tasks). Only works for --profile. + +*-H* 'event-hooks':: + Add custom event matching to connect any two events together. + + See trace-cmd-profile(1) for format. + +*-R*:: + This will show the events in "raw" format. That is, it will ignore the event's + print formatting and just print the contents of each field. + +*-r* 'event-re':: + This will cause all events that match the option to print its raw fields. + The 'event-re' is a regular expression as defined by 'regcomp(3)'. + +*-l*:: + This adds a "latency output" format. Information about interrupts being + disabled, soft irq being disabled, the "need_resched" flag being set, + preempt count, and big kernel lock are all being recorded with every + event. But the default display does not show this information. This option + will set display this information with 6 characters. When one of the + fields is zero or N/A a \'.\' is shown. + +------------------------------------------ + <idle>-0 0d.h1. 106467.859747: function: ktime_get <-- tick_check_idle +------------------------------------------ + + The 0d.h1. denotes this information. The first character is never a '.' + and represents what CPU the trace was recorded on (CPU 0). The 'd' denotes + that interrupts were disabled. The 'h' means that this was called inside + an interrupt handler. The '1' is the preemption disabled (preempt_count) + was set to one. The two '.'s are "need_resched" flag and kernel lock + counter. If the "need_resched" flag is set, then that character would be a + 'N'. + +*-w*:: + If both the 'sched_switch' and 'sched_wakeup' events are enabled, then + this option will report the latency between the time the task was first + woken, and the time it was scheduled in. + +*-q*:: + Quiet non critical warnings. + +*-O*:: + Pass options to the trace-cmd plugins that are loaded. + + -O plugin:var=value + + The 'plugin:' and '=value' are optional. Value may be left off for options + that are boolean. If the 'plugin:' is left off, then any variable that matches + in all plugins will be set. + + Example: -O fgraph:tailprint + +*--cpu* <cpu list>:: + List of CPUs, separated by "," or ":", used for filtering the events. + A range of CPUs can be specified using "cpuX-cpuY" notation, where all CPUs + in the range between cpuX and cpuY will be included in the list. The order + of CPUs in the list must be from lower to greater. + + Example: "--cpu 0,3" - show events from CPUs 0 and 3 + "--cpu 2-4" - show events from CPUs 2, 3 and 4 + +*--cpus*:: + List the CPUs that have data in the trace file then exit. + +*--stat*:: + If the trace.dat file recorded the final stats (outputed at the end of record) + the *--stat* option can be used to retrieve them. + +*--uname*:: + If the trace.dat file recorded uname during the run, this will retrieve that + information. + +*--version*:: + If the trace.dat file recorded the version of the executable used to create + it, report that version. + +*--ts-offset* offset:: + Add (or subtract if negative) an offset for all timestamps of the previous + data file specified with *-i*. This is useful to merge sort multiple trace.dat + files where the difference in the timestamp is known. For example if a trace + is done on a virtual guest, and another trace is done on the host. If the + host timestamp is 1000 units ahead of the guest, the following can be done: + + trace-cmd report -i host.dat --ts-offset -1000 -i guest.dat + + This will subtract 1000 timestamp units from all the host events as it merges + with the guest.dat events. Note, the units is for the raw units recorded in + the trace. If the units are nanoseconds, the addition (or subtraction) from + the offset will be nanoseconds even if the displayed units are microseconds. + +*--ts2secs* HZ:: + Convert the current clock source into a second (nanosecond resolution) + output. When using clocks like x86-tsc, if the frequency is known, + by passing in the clock frequency, this will convert the time to seconds. + + This option affects any trace.dat file given with *-i* proceeding it. + If this option comes before any *-i* option, then that value becomes + the default conversion for all other trace.dat files. If another + --ts2secs option appears after a *-i* trace.dat file, than that option + will override the default value. + + Example: On a 3.4 GHz machine + + trace-cmd record -p function -C x86-tsc + + trace-cmd report --ts2ns 3400000000 + + The report will convert the cycles timestamps into a readable second + display. The default display resolution is microseconds, unless *-t* + is used. + + The value of --ts-offset must still be in the raw timestamp units, even + with this option. The offset will be converted as well. + +*--ts-diff*:: + Show the time differences between events. The difference will appear in + parenthesis just after the timestamp. + +*--ts-check*:: + Make sure no timestamp goes backwards, and if it does, print out a warning + message of the fact. + +*--nodate*:: + Ignore converting the timestamps to the date set by *trace-cmd record*(3) --date option. + +*--raw-ts*:: + Display raw timestamps, without any corrections. + +*--align-ts*:: + Display timestamps aligned to the first event. + +*--verbose*[='level']:: + Set the log level. Supported log levels are "none", "crit", "err", "warn", + "info", "debug", "all" or their identifiers "0", "1", "2", "3", "4", "5", "6". Setting the log + level to specific value enables all logs from that and all previous levels. + The level will default to "info" if one is not specified. + + Example: enable all critical, error and warning logs + + trace-cmd report --verbose=warning + +EXAMPLES +-------- + +Using a trace.dat file that was created with: + +------------------------------------------ + # trace-cmd record -p function -e all sleep 5 + + +------------------------------------------ + +The default report shows: + +------------------------------------------ + # trace-cmd report + trace-cmd-16129 [002] 158126.498411: function: __mutex_unlock_slowpath <-- mutex_unlock + trace-cmd-16131 [000] 158126.498411: kmem_cache_alloc: call_site=811223c5 ptr=0xffff88003ecf2b40 bytes_req=272 bytes_alloc=320 gfp_flags=GFP_KERNEL|GFP_ZERO + trace-cmd-16130 [003] 158126.498411: function: do_splice_to <-- sys_splice + sleep-16133 [001] 158126.498412: function: inotify_inode_queue_event <-- vfs_write + trace-cmd-16129 [002] 158126.498420: lock_release: 0xffff88003f1fa4f8 &sb->s_type->i_mutex_key + trace-cmd-16131 [000] 158126.498421: function: security_file_alloc <-- get_empty_filp + sleep-16133 [001] 158126.498422: function: __fsnotify_parent <-- vfs_write + trace-cmd-16130 [003] 158126.498422: function: rw_verify_area <-- do_splice_to + trace-cmd-16131 [000] 158126.498424: function: cap_file_alloc_security <-- security_file_alloc + trace-cmd-16129 [002] 158126.498425: function: syscall_trace_leave <-- int_check_syscall_exit_work + sleep-16133 [001] 158126.498426: function: inotify_dentry_parent_queue_event <-- vfs_write + trace-cmd-16130 [003] 158126.498426: function: security_file_permission <-- rw_verify_area + trace-cmd-16129 [002] 158126.498428: function: audit_syscall_exit <-- syscall_trace_leave +[...] + + +------------------------------------------ + +To see everything but the function traces: + +------------------------------------------ + # trace-cmd report -v -F 'function' + trace-cmd-16131 [000] 158126.498411: kmem_cache_alloc: call_site=811223c5 ptr=0xffff88003ecf2b40 bytes_req=272 bytes_alloc=320 gfp_flags=GFP_KERNEL|GFP_ZERO + trace-cmd-16129 [002] 158126.498420: lock_release: 0xffff88003f1fa4f8 &sb->s_type->i_mutex_key + trace-cmd-16130 [003] 158126.498436: lock_acquire: 0xffffffff8166bf78 read all_cpu_access_lock + trace-cmd-16131 [000] 158126.498438: lock_acquire: 0xffff88003df5b520 read &fs->lock + trace-cmd-16129 [002] 158126.498446: kfree: call_site=810a7abb ptr=0x0 + trace-cmd-16130 [003] 158126.498448: lock_acquire: 0xffff880002250a80 &per_cpu(cpu_access_lock, cpu) + trace-cmd-16129 [002] 158126.498450: sys_exit_splice: 0xfffffff5 + trace-cmd-16131 [000] 158126.498454: lock_release: 0xffff88003df5b520 &fs->lock + sleep-16133 [001] 158126.498456: kfree: call_site=810a7abb ptr=0x0 + sleep-16133 [001] 158126.498460: sys_exit_write: 0x1 + trace-cmd-16130 [003] 158126.498462: kmalloc: call_site=810bf95b ptr=0xffff88003dedc040 bytes_req=24 bytes_alloc=32 gfp_flags=GFP_KERNEL|GFP_ZERO + + +------------------------------------------ + +To see only the kmalloc calls that were greater than 1000 bytes: + +------------------------------------------ + #trace-cmd report -F 'kmalloc: bytes_req > 1000' + <idle>-0 [000] 158128.126641: kmalloc: call_site=81330635 ptr=0xffff88003c2fd000 bytes_req=2096 bytes_alloc=4096 gfp_flags=GFP_ATOMIC + + +------------------------------------------ + +To see wakeups and sched switches that left the previous task in the running +state: +------------------------------------------ + # trace-cmd report -F 'sched: prev_state == 0 || (success == 1)' + trace-cmd-16132 [002] 158126.499951: sched_wakeup: comm=trace-cmd pid=16129 prio=120 success=1 target_cpu=002 + trace-cmd-16132 [002] 158126.500401: sched_switch: prev_comm=trace-cmd prev_pid=16132 prev_prio=120 prev_state=R ==> next_comm=trace-cmd next_pid=16129 next_prio=120 + <idle>-0 [003] 158126.500585: sched_wakeup: comm=trace-cmd pid=16130 prio=120 success=1 target_cpu=003 + <idle>-0 [003] 158126.501241: sched_switch: prev_comm=swapper prev_pid=0 prev_prio=120 prev_state=R ==> next_comm=trace-cmd next_pid=16130 next_prio=120 + trace-cmd-16132 [000] 158126.502475: sched_wakeup: comm=trace-cmd pid=16131 prio=120 success=1 target_cpu=000 + trace-cmd-16131 [002] 158126.506516: sched_wakeup: comm=trace-cmd pid=16129 prio=120 success=1 target_cpu=002 + <idle>-0 [003] 158126.550110: sched_switch: prev_comm=swapper prev_pid=0 prev_prio=120 prev_state=R ==> next_comm=trace-cmd next_pid=16130 next_prio=120 + trace-cmd-16131 [003] 158126.570243: sched_wakeup: comm=trace-cmd pid=16129 prio=120 success=1 target_cpu=003 + trace-cmd-16130 [002] 158126.618202: sched_switch: prev_comm=trace-cmd prev_pid=16130 prev_prio=120 prev_state=R ==> next_comm=yum-updatesd next_pid=3088 next_prio=1 20 + trace-cmd-16129 [003] 158126.622379: sched_wakeup: comm=trace-cmd pid=16131 prio=120 success=1 target_cpu=003 + trace-cmd-16129 [000] 158126.649287: sched_wakeup: comm=trace-cmd pid=16131 prio=120 success=1 target_cpu=000 + + +------------------------------------------ + +The above needs a little explanation. The filter specifies the "sched" +subsystem, which includes both sched_switch and sched_wakeup events. Any event +that does not have the format field "prev_state" or "success", will evaluate +those expressions as FALSE, and will not produce a match. Using "||" will have +the "prev_state" test happen for the "sched_switch" event and the "success" +test happen for the "sched_wakeup" event. + + +------------------------------------------ + # trace-cmd report -w -F 'sched_switch, sched_wakeup.*' +[...] + trace-cmd-16130 [003] 158131.580616: sched_wakeup: comm=trace-cmd pid=16131 prio=120 success=1 target_cpu=003 + trace-cmd-16129 [000] 158131.581502: sched_switch: prev_comm=trace-cmd prev_pid=16129 prev_prio=120 prev_state=S ==> next_comm=trace-cmd next_pid=16131 next_prio=120 Latency: 885.901 usecs + trace-cmd-16131 [000] 158131.582414: sched_wakeup: comm=trace-cmd pid=16129 prio=120 success=1 target_cpu=000 + trace-cmd-16132 [001] 158131.583219: sched_switch: prev_comm=trace-cmd prev_pid=16132 prev_prio=120 prev_state=S ==> next_comm=trace-cmd next_pid=16129 next_prio=120 Latency: 804.809 usecs + sleep-16133 [002] 158131.584121: sched_wakeup: comm=trace-cmd pid=16120 prio=120 success=1 target_cpu=002 + trace-cmd-16129 [001] 158131.584128: sched_wakeup: comm=trace-cmd pid=16132 prio=120 success=1 target_cpu=001 + sleep-16133 [002] 158131.584275: sched_switch: prev_comm=sleep prev_pid=16133 prev_prio=120 prev_state=R ==> next_comm=trace-cmd next_pid=16120 next_prio=120 Latency: 153.915 usecs + trace-cmd-16130 [003] 158131.585284: sched_switch: prev_comm=trace-cmd prev_pid=16130 prev_prio=120 prev_state=S ==> next_comm=trace-cmd next_pid=16132 next_prio=120 Latency: 1155.677 usecs + +Average wakeup latency: 26626.656 usecs + + +------------------------------------------ + +The above trace produces the wakeup latencies of the tasks. The "sched_switch" +event reports each individual latency after writing the event information. +At the end of the report, the average wakeup latency is reported. + +------------------------------------------ + # trace-cmd report -w -F 'sched_switch, sched_wakeup.*: prio < 100 || next_prio < 100' + <idle>-0 [003] 158131.516753: sched_wakeup: comm=ksoftirqd/3 pid=13 prio=49 success=1 target_cpu=003 + <idle>-0 [003] 158131.516855: sched_switch: prev_comm=swapper prev_pid=0 prev_prio=120 prev_state=R ==> next_comm=ksoftirqd/3 next_pid=13 next_prio=49 Latency: 101.244 usecs + <idle>-0 [003] 158131.533781: sched_wakeup: comm=ksoftirqd/3 pid=13 prio=49 success=1 target_cpu=003 + <idle>-0 [003] 158131.533897: sched_switch: prev_comm=swapper prev_pid=0 prev_prio=120 prev_state=R ==> next_comm=ksoftirqd/3 next_pid=13 next_prio=49 Latency: 115.608 usecs + <idle>-0 [003] 158131.569730: sched_wakeup: comm=ksoftirqd/3 pid=13 prio=49 success=1 target_cpu=003 + <idle>-0 [003] 158131.569851: sched_switch: prev_comm=swapper prev_pid=0 prev_prio=120 prev_state=R ==> next_comm=ksoftirqd/3 next_pid=13 next_prio=49 Latency: 121.024 usecs + +Average wakeup latency: 110.021 usecs + + +------------------------------------------ + +The above version will only show the wakeups and context switches of Real Time +tasks. The 'prio' used inside the kernel starts at 0 for highest priority. +That is 'prio' 0 is equivalent to user space real time priority 99, and +priority 98 is equivalent to user space real time priority 1. +Prios less than 100 represent Real Time tasks. + +An example of the profile: +------------------------------------------ + # trace-cmd record --profile sleep 1 + # trace-cmd report --profile --comm sleep +task: sleep-21611 + Event: sched_switch:R (1) Total: 99442 Avg: 99442 Max: 99442 Min:99442 + <stack> 1 total:99442 min:99442 max:99442 avg=99442 + => ftrace_raw_event_sched_switch (0xffffffff8105f812) + => __schedule (0xffffffff8150810a) + => preempt_schedule (0xffffffff8150842e) + => ___preempt_schedule (0xffffffff81273354) + => cpu_stop_queue_work (0xffffffff810b03c5) + => stop_one_cpu (0xffffffff810b063b) + => sched_exec (0xffffffff8106136d) + => do_execve_common.isra.27 (0xffffffff81148c89) + => do_execve (0xffffffff811490b0) + => SyS_execve (0xffffffff811492c4) + => return_to_handler (0xffffffff8150e3c8) + => stub_execve (0xffffffff8150c699) + Event: sched_switch:S (1) Total: 1000506680 Avg: 1000506680 Max: 1000506680 Min:1000506680 + <stack> 1 total:1000506680 min:1000506680 max:1000506680 avg=1000506680 + => ftrace_raw_event_sched_switch (0xffffffff8105f812) + => __schedule (0xffffffff8150810a) + => schedule (0xffffffff815084b8) + => do_nanosleep (0xffffffff8150b22c) + => hrtimer_nanosleep (0xffffffff8108d647) + => SyS_nanosleep (0xffffffff8108d72c) + => return_to_handler (0xffffffff8150e3c8) + => tracesys_phase2 (0xffffffff8150c304) + Event: sched_wakeup:21611 (1) Total: 30326 Avg: 30326 Max: 30326 Min:30326 + <stack> 1 total:30326 min:30326 max:30326 avg=30326 + => ftrace_raw_event_sched_wakeup_template (0xffffffff8105f653) + => ttwu_do_wakeup (0xffffffff810606eb) + => ttwu_do_activate.constprop.124 (0xffffffff810607c8) + => try_to_wake_up (0xffffffff8106340a) +------------------------------------------ + +SEE ALSO +-------- +trace-cmd(1), trace-cmd-record(1), trace-cmd-start(1), trace-cmd-stop(1), +trace-cmd-extract(1), trace-cmd-reset(1), trace-cmd-split(1), +trace-cmd-list(1), trace-cmd-listen(1), trace-cmd-profile(1) + +AUTHOR +------ +Written by Steven Rostedt, <rostedt@goodmis.org> + +RESOURCES +--------- +https://git.kernel.org/pub/scm/utils/trace-cmd/trace-cmd.git/ + +COPYING +------- +Copyright \(C) 2010 Red Hat, Inc. Free use of this software is granted under +the terms of the GNU Public License (GPL). + diff --git a/Documentation/trace-cmd/trace-cmd-reset.1.txt b/Documentation/trace-cmd/trace-cmd-reset.1.txt new file mode 100644 index 00000000..eee86751 --- /dev/null +++ b/Documentation/trace-cmd/trace-cmd-reset.1.txt @@ -0,0 +1,116 @@ +TRACE-CMD-RESET(1) +================== + +NAME +---- +trace-cmd-reset - turn off all Ftrace tracing to bring back full performance + +SYNOPSIS +-------- +*trace-cmd reset* ['OPTIONS'] + +DESCRIPTION +----------- +The trace-cmd(1) reset command turns off all tracing of Ftrace. This will +bring back the performance of the system before tracing was enabled. This is +necessary since 'trace-cmd-record(1)', 'trace-cmd-stop(1)' and +'trace-cmd-extract(1)' do not disable the tracer, event after the data has +been pulled from the buffers. The rational is that the user may want to +manually enable the tracer with the Ftrace pseudo file system, or examine other +parts of Ftrace to see what trace-cmd did. After the reset command happens, +the data in the ring buffer, and the options that were used are all lost. + +OPTIONS +------- +Please note that the order that options are specified on the command line is +significant. See EXAMPLES. + +*-b* 'buffer_size':: + When the kernel boots, the Ftrace ring buffer is of a minimal size (3 + pages per CPU). The first time the tracer is used, the ring buffer size + expands to what it was set for (default 1.4 Megs per CPU). + + If no more tracing is to be done, this option allows you to shrink the + ring buffer down to free up available memory. + + trace-cmd reset -b 1 + + The buffer instance affected is the one (or ones) specified by the most + recently preceding *-B*, *-t*, or *-a* option: + + When used after *-B*, resizes the buffer instance that precedes it on + the command line. + + When used after *-a*, resizes all buffer instances except the top one. + + When used after *-t* or before any *-B* or *-a*, resizes the top + instance. + +*-B* 'buffer-name':: + If the kernel supports multiple buffers, this will reset the trace for + only the given buffer. It does not affect any other buffer. This may be + used multiple times to specify different buffers. The top level buffer + will not be reset if this option is given (unless the *-t* option is + also supplied). + +*-a*:: + Reset the trace for all existing buffer instances. When this option + is used, the top level instance will not be reset unless *-t* is given. + +*-d*:: + This option deletes the instance buffer(s) specified by the most recently + preceding *-B* or *-a* option. Because the top-level instance buffer + cannot be deleted, it is invalid to use this immediatly following *-t* or + prior to any *-B* or *-a* option on the command line. + +*-t*:: + Resets the top level instance buffer. Without the *-B* or *-a* option + this is the same as the default. But if *-B* or *-a* is used, this is + required if the top level instance buffer should also be reset. + +EXAMPLES +-------- + +Reset tracing for instance-one and set its per-cpu buffer size to 4096kb. +Also deletes instance-two. The top level instance and any other instances +remain unaffected: + + trace-cmd reset -B instance-one -b 4096 -B instance-two -d + +Delete all instance buffers. Top level instance remains unaffected: + + trace-cmd reset -a -d + +Delete all instance buffers and also reset the top instance: + + trace-cmd reset -t -a -d + +Invalid. This command implies an attempt to delete the top instance: + + trace-cmd reset -a -t -d + +Reset the top instance and set its per-cpu buffer size to 1024kb. If any +instance buffers exist, they will be unaffected: + + trace-cmd reset -b 1024 + + +SEE ALSO +-------- +trace-cmd(1), trace-cmd-record(1), trace-cmd-report(1), trace-cmd-start(1), +trace-cmd-stop(1), trace-cmd-extract(1), trace-cmd-split(1), +trace-cmd-list(1), trace-cmd-listen(1) + +AUTHOR +------ +Written by Steven Rostedt, <rostedt@goodmis.org> + +RESOURCES +--------- +https://git.kernel.org/pub/scm/utils/trace-cmd/trace-cmd.git/ + +COPYING +------- +Copyright \(C) 2010 Red Hat, Inc. Free use of this software is granted under +the terms of the GNU Public License (GPL). + diff --git a/Documentation/trace-cmd/trace-cmd-restore.1.txt b/Documentation/trace-cmd/trace-cmd-restore.1.txt new file mode 100644 index 00000000..ebcbb1b6 --- /dev/null +++ b/Documentation/trace-cmd/trace-cmd-restore.1.txt @@ -0,0 +1,105 @@ +TRACE-CMD-RESTORE(1) +==================== + +NAME +---- +trace-cmd-restore - restore a failed trace record + +SYNOPSIS +-------- +*trace-cmd restore* ['OPTIONS'] ['command'] cpu-file [cpu-file ...] + +DESCRIPTION +----------- +The trace-cmd(1) restore command will restore a crashed trace-cmd-record(1) +file. If for some reason a trace-cmd record fails, it will leave a the +per-cpu data files and not create the final trace.dat file. The trace-cmd +restore will append the files to create a working trace.dat file that can +be read with trace-cmd-report(1). + +When trace-cmd record runs, it spawns off a process per CPU and writes +to a per cpu file usually called 'trace.dat.cpuX', where X represents the +CPU number that it is tracing. If the -o option was used in the trace-cmd +record, then the CPU data files will have that name instead of the +'trace.dat' name. If a unexpected crash occurs before the tracing +is finished, then the per CPU files will still exist but there will +not be any trace.dat file to read from. trace-cmd restore will allow you +to create a trace.dat file with the existing data files. + +OPTIONS +------- +*-c*:: + Create a partial trace.dat file from the machine, to be used with + a full trace-cmd restore at another time. This option is useful for + embedded devices. If a server contains the cpu files of a crashed + trace-cmd record (or trace-cmd listen), trace-cmd restore can be + executed on the embedded device with the -c option to get all the + stored information of that embedded device. Then the file created + could be copied to the server to run the trace-cmd restore there + with the cpu files. + + If *-o* is not specified, then the file created will be called + 'trace-partial.dat'. This is because the file is not a full version + of something that trace-cmd-report(1) could use. + +*-t* tracing_dir:: + Used with *-c*, it overrides the location to read the events from. + By default, tracing information is read from the debugfs/tracing + directory. *-t* will use that location instead. This can be useful + if the trace.dat file to create is from another machine. + Just tar -cvf events.tar debugfs/tracing and copy and untar that + file locally, and use that directory instead. + +*-k* kallsyms:: + Used with *-c*, it overrides where to read the kallsyms file from. + By default, /proc/kallsyms is used. *-k* will override the file to + read the kallsyms from. This can be useful if the trace.dat file + to create is from another machine. Just copy the /proc/kallsyms + file locally, and use *-k* to point to that file. + +*-o* output':: + By default, trace-cmd restore will create a 'trace.dat' file + (or 'trace-partial.dat' if *-c* is specified). You can + specify a different file to write to with the *-o* option. + +*-i* input:: + By default, trace-cmd restore will read the information of the + current system to create the initial data stored in the 'trace.dat' + file. If the crash was on another machine, then that machine should + have the trace-cmd restore run with the *-c* option to create the + trace.dat partial file. Then that file can be copied to the current + machine where trace-cmd restore will use *-i* to load that file + instead of reading from the current system. + +EXAMPLES +-------- + +If a crash happened on another box, you could run: + + $ trace-cmd restore -c -o box-partial.dat + +Then on the server that has the cpu files: + + $ trace-cmd restore -i box-partial.dat trace.dat.cpu0 trace.dat.cpu1 + +This would create a trace.dat file for the embedded box. + +SEE ALSO +-------- +trace-cmd(1), trace-cmd-record(1), trace-cmd-report(1), trace-cmd-start(1), +trace-cmd-stop(1), trace-cmd-extract(1), trace-cmd-reset(1), trace-cmd-split(1), +trace-cmd-list(1), trace-cmd-listen(1) + +AUTHOR +------ +Written by Steven Rostedt, <rostedt@goodmis.org> + +RESOURCES +--------- +https://git.kernel.org/pub/scm/utils/trace-cmd/trace-cmd.git/ + +COPYING +------- +Copyright \(C) 2010 Red Hat, Inc. Free use of this software is granted under +the terms of the GNU Public License (GPL). + diff --git a/Documentation/trace-cmd/trace-cmd-set.1.txt b/Documentation/trace-cmd/trace-cmd-set.1.txt new file mode 100644 index 00000000..a182d191 --- /dev/null +++ b/Documentation/trace-cmd/trace-cmd-set.1.txt @@ -0,0 +1,273 @@ +TRACE-CMD-SET(1) +================ + +NAME +---- +trace-cmd-set - set a configuration parameter of the Ftrace Linux internal tracer + +SYNOPSIS +-------- +*trace-cmd set* ['OPTIONS'] ['command'] + +DESCRIPTION +----------- +The trace-cmd(1) set command will set a configuration parameter of the Ftrace +Linux kernel tracer. The specified *command* will be run after the ftrace state +is set. The configured ftrace state can be restored to default +using the trace-cmd-reset(1) command. + +OPTIONS +------- +*-p* 'tracer':: + Specify a tracer. Tracers usually do more than just trace an event. + Common tracers are: *function*, *function_graph*, *preemptirqsoff*, + *irqsoff*, *preemptoff* and *wakeup*. A tracer must be supported by the + running kernel. To see a list of available tracers, see trace-cmd-list(1). + +*-e* 'event':: + Specify an event to trace. Various static trace points have been added to + the Linux kernel. They are grouped by subsystem where you can enable all + events of a given subsystem or specify specific events to be enabled. The + 'event' is of the format "subsystem:event-name". You can also just specify + the subsystem without the ':event-name' or the event-name without the + "subsystem:". Using "-e sched_switch" will enable the "sched_switch" event + where as, "-e sched" will enable all events under the "sched" subsystem. + + The 'event' can also contain glob expressions. That is, "*stat*" will + select all events (or subsystems) that have the characters "stat" in their + names. + + The keyword 'all' can be used to enable all events. + +*-T*:: + Enable a stacktrace on each event. For example: + + <idle>-0 [003] 58549.289091: sched_switch: kworker/0:1:0 [120] R ==> trace-cmd:2603 [120] + <idle>-0 [003] 58549.289092: kernel_stack: <stack trace> +=> schedule (ffffffff814b260e) +=> cpu_idle (ffffffff8100a38c) +=> start_secondary (ffffffff814ab828) + +*--func-stack*:: + Enable a stack trace on all functions. Note this is only applicable + for the "function" plugin tracer, and will only take effect if the + -l option is used and succeeds in limiting functions. If the function + tracer is not filtered, and the stack trace is enabled, you can live + lock the machine. + +*-f* 'filter':: + Specify a filter for the previous event. This must come after a *-e*. This + will filter what events get recorded based on the content of the event. + Filtering is passed to the kernel directly so what filtering is allowed + may depend on what version of the kernel you have. Basically, it will + let you use C notation to check if an event should be processed or not. + +---------------------------------------- + ==, >=, <=, >, <, &, |, && and || +---------------------------------------- + + The above are usually safe to use to compare fields. + +*-R* 'trigger':: + Specify a trigger for the previous event. This must come after a *-e*. + This will add a given trigger to the given event. To only enable the trigger + and not the event itself, then place the event after the *-v* option. + + See Documentation/trace/events.txt in the Linux kernel source for more + information on triggers. + +*-v*:: + This will negate options specified after it on the command line. It affects: +[verse] +-- + *-e*: Causes all specified events to not be traced. This is useful for + selecting a subsystem to be traced but to leave out various events. + For example: "-e sched -v -e "\*stat\*"" will enable all events in + the sched subsystem except those that have "stat" in their names. + *-B*: Deletes the specified ftrace instance. There must be no + configuration options related to this instance in the command line. + For example: "-v -B bar -B foo" will delete instance bar and create + a new instance foo. + Note: the *-v* option was taken from the way grep(1) inverts the following + matches. +-- +*-P* 'pid':: + This will filter only the specified process IDs. Using *-P* will let you + trace only events that are caused by the process. + +*-c*:: + Used *-P* to trace the process' children too (if kernel supports it). + +*--user*:: + Execute the specified *command* as given user. + +*-C* 'clock':: + Set the trace clock to "clock". + + Use trace-cmd(1) list -C to see what clocks are available. + +*-l* 'function-name':: + This will limit the 'function' and 'function_graph' tracers to only trace + the given function name. More than one *-l* may be specified on the + command line to trace more than one function. The limited use of glob + expressions are also allowed. These are 'match\*' to only filter functions + that start with 'match'. '\*match' to only filter functions that end with + 'match'. '\*match\*' to only filter on functions that contain 'match'. + +*-g* 'function-name':: + This option is for the function_graph plugin. It will graph the given + function. That is, it will only trace the function and all functions that + it calls. You can have more than one *-g* on the command line. + +*-n* 'function-name':: + This has the opposite effect of *-l*. The function given with the *-n* + option will not be traced. This takes precedence, that is, if you include + the same function for both *-n* and *-l*, it will not be traced. + +*-d*:: + Some tracer plugins enable the function tracer by default. Like the + latency tracers. This option prevents the function tracer from being + enabled at start up. + +*-D*:: + The option *-d* will try to use the function-trace option to disable the + function tracer (if available), otherwise it defaults to the proc file: + /proc/sys/kernel/ftrace_enabled, but will not touch it if the function-trace + option is available. The *-D* option will disable both the ftrace_enabled + proc file as well as the function-trace option if it exists. + + Note, this disable function tracing for all users, which includes users + outside of ftrace tracers (stack_tracer, perf, etc). + +*-O* 'option':: + Ftrace has various options that can be enabled or disabled. This allows + you to set them. Appending the text 'no' to an option disables it. + For example: "-O nograph-time" will disable the "graph-time" Ftrace + option. + +*-b* 'size':: + This sets the ring buffer size to 'size' kilobytes. Because the Ftrace + ring buffer is per CPU, this size is the size of each per CPU ring buffer + inside the kernel. Using "-b 10000" on a machine with 4 CPUs will make + Ftrace have a total buffer size of 40 Megs. + +*-B* 'buffer-name':: + If the kernel supports multiple buffers, this will add a buffer with + the given name. If the buffer name already exists, that buffer is just + reset. + + After a buffer name is stated, all events added after that will be + associated with that buffer. If no buffer is specified, or an event + is specified before a buffer name, it will be associated with the + main (toplevel) buffer. + + trace-cmd set -e sched -B block -e block -B time -e timer sleep 1 + + The above is will enable all sched events in the main buffer. It will + then create a 'block' buffer instance and enable all block events within + that buffer. A 'time' buffer instance is created and all timer events + will be enabled for that event. + +*-m* 'size':: + The max size in kilobytes that a per cpu buffer should be. Note, due + to rounding to page size, the number may not be totally correct. + Also, this is performed by switching between two buffers that are half + the given size thus the output may not be of the given size even if + much more was written. + + Use this to prevent running out of diskspace for long runs. + +*-M* 'cpumask':: + Set the cpumask for to trace. It only affects the last buffer instance + given. If supplied before any buffer instance, then it affects the + main buffer. The value supplied must be a hex number. + + trace-cmd set -p function -M c -B events13 -e all -M 5 + + If the -M is left out, then the mask stays the same. To enable all + CPUs, pass in a value of '-1'. + +*-i*:: + By default, if an event is listed that trace-cmd does not find, it + will exit with an error. This option will just ignore events that are + listed on the command line but are not found on the system. + +*-q* | *--quiet*:: + Suppresses normal output, except for errors. + +*--max-graph-depth* 'depth':: + Set the maximum depth the function_graph tracer will trace into a function. + A value of one will only show where userspace enters the kernel but not any + functions called in the kernel. The default is zero, which means no limit. + +*--cmdlines-size* 'size':: + Set the number of entries the kernel tracing file "saved_cmdlines" can + contain. This file is a circular buffer which stores the mapping between + cmdlines and PIDs. If full, it leads to unresolved cmdlines ("<...>") within + the trace. The kernel default value is 128. + +*--module* 'module':: + Filter a module's name in function tracing. It is equivalent to adding + ':mod:module' after all other functions being filtered. If no other function + filter is listed, then all modules functions will be filtered in the filter. + + '--module snd' is equivalent to '-l :mod:snd' + + '--module snd -l "*jack*"' is equivalent to '-l "*jack*:mod:snd"' + + '--module snd -n "*"' is equivalent to '-n :mod:snd' + +*--stderr*:: + Have output go to stderr instead of stdout, but the output of the command + executed will not be changed. This is useful if you want to monitor the + output of the command being executed, but not see the output from trace-cmd. + +*--fork*:: + If a command is listed, then trace-cmd will wait for that command to finish, + unless the *--fork* option is specified. Then it will fork the command and + return immediately. + +*--verbose*[='level']:: + Set the log level. Supported log levels are "none", "critical", "error", "warning", + "info", "debug", "all" or their identifiers "0", "1", "2", "3", "4", "5", "6". Setting the log + level to specific value enables all logs from that and all previous levels. + The level will default to "info" if one is not specified. + + Example: enable all critical, error and warning logs + + trace-cmd set --verbose=warning + +EXAMPLES +-------- + +Enable all events for tracing: + +------------------------------ + # trace-cmd set -e all +------------------------------ + +Set the function tracer: + +------------------------------ + # trace-cmd set -p function +------------------------------ + + +SEE ALSO +-------- +trace-cmd(1), trace-cmd-report(1), trace-cmd-start(1), trace-cmd-stop(1), +trace-cmd-extract(1), trace-cmd-reset(1), trace-cmd-split(1), +trace-cmd-list(1), trace-cmd-listen(1), trace-cmd-profile(1) + +AUTHOR +------ +Written by Tzvetomir Stoyanov (VMware) <tz.stoyanov@gmail.com> + +RESOURCES +--------- +https://git.kernel.org/pub/scm/utils/trace-cmd/trace-cmd.git/ + +COPYING +------- +Copyright \(C) 2010 Red Hat, Inc. Free use of this software is granted under +the terms of the GNU Public License (GPL). diff --git a/Documentation/trace-cmd/trace-cmd-show.1.txt b/Documentation/trace-cmd/trace-cmd-show.1.txt new file mode 100644 index 00000000..ea2fda28 --- /dev/null +++ b/Documentation/trace-cmd/trace-cmd-show.1.txt @@ -0,0 +1,100 @@ +TRACE-CMD-SHOW(1) +================= + +NAME +---- +trace-cmd-show - show the contents of the Ftrace Linux kernel tracing buffer. + +SYNOPSIS +-------- +*trace-cmd show* ['OPTIONS'] + +DESCRIPTION +----------- +The trace-cmd(1) show displays the contents of one of the Ftrace Linux +kernel tracing files: trace, snapshot, or trace_pipe. It is basically +the equivalent of doing: + + cat /sys/kernel/debug/tracing/trace + +OPTIONS +------- +*-p*:: + Instead of displaying the contents of the "trace" file, use the + "trace_pipe" file. The difference between the two is that the "trace" + file is static. That is, if tracing is stopped, the "trace" file + will show the same contents each time. + + The "trace_pipe" file is a consuming read, where a read of the file + will consume the output of what was read and it will not read the + same thing a second time even if tracing is stopped. This file + als will block. If no data is available, trace-cmd show will stop + and wait for data to appear. + +*-s*:: + Instead of reading the "trace" file, read the snapshot file. The snapshot + is made by an application writing into it and the kernel will perform + as swap between the currently active buffer and the current snapshot + buffer. If no more swaps are made, the snapshot will remain static. + This is not a consuming read. + +*-c* 'cpu':: + Read only the trace file for a specified CPU. + +*-f*:: + Display the full path name of the file that is being displayed. + +*-B* 'buf':: + If a buffer instance was created, then the *-B* option will access the + files associated with the given buffer. + +*--tracing_on*:: + Show if tracing is on for the given instance. + +*--current_tracer*:: + Show what the current tracer is. + +*--buffer_size*:: + Show the current buffer size (per-cpu) + +*--buffer_total_size*:: + Show the total size of all buffers. + +*--ftrace_filter*:: + Show what function filters are set. + +*--ftrace_notrace*:: + Show what function disabled filters are set. + +*--ftrace_pid*:: + Show the PIDs the function tracer is limited to (if any). + +*--graph_function*:: + Show the functions that will be graphed. + +*--graph_notrace*:: + Show the functions that will not be graphed. + +*--cpumask*:: + Show the mask of CPUs that tracing will trace. + + +SEE ALSO +-------- +trace-cmd(1), trace-cmd-record(1), trace-cmd-report(1), trace-cmd-start(1), +trace-cmd-extract(1), trace-cmd-reset(1), trace-cmd-split(1), +trace-cmd-list(1), trace-cmd-listen(1) + +AUTHOR +------ +Written by Steven Rostedt, <rostedt@goodmis.org> + +RESOURCES +--------- +https://git.kernel.org/pub/scm/utils/trace-cmd/trace-cmd.git/ + +COPYING +------- +Copyright \(C) 2010 Red Hat, Inc. Free use of this software is granted under +the terms of the GNU Public License (GPL). + diff --git a/Documentation/trace-cmd/trace-cmd-snapshot.1.txt b/Documentation/trace-cmd/trace-cmd-snapshot.1.txt new file mode 100644 index 00000000..0a34bcd9 --- /dev/null +++ b/Documentation/trace-cmd/trace-cmd-snapshot.1.txt @@ -0,0 +1,65 @@ +TRACE-CMD-SNAPSHOT(1) +===================== + +NAME +---- +trace-cmd-snapshot - take, reset, free, or show a Ftrace kernel snapshot + +SYNOPSIS +-------- +*trace-cmd snapshot* ['OPTIONS'] + +DESCRIPTION +----------- +The trace-cmd(1) snapshot controls or displays the Ftrace Linux kernel +snapshot feature (if the kernel supports it). This is useful to "freeze" +an instance of a live trace but without stopping the trace. + + trace-cmd start -p function + trace-cmd snapshot -s + trace-cmd snapshot + [ dumps the content of buffer at 'trace-cmd snapshot -s' ] + trace-cmd snapshot -s + trace-cmd snapshot + [ dumps the new content of the buffer at the last -s operation ] + +OPTIONS +------- +*-s*:: + Take a snapshot of the currently running buffer. + +*-r*:: + Clear out the buffer. + +*-f*:: + Free the snapshot buffer. The buffer takes up memory inside the + kernel. It is best to free it when not in use. The first -s + operation will allocate it if it is not already allocated. + +*-c* 'cpu':: + Operate on a per cpu snapshot (may not be fully supported by all kernels) + +*-B* 'buf':: + If a buffer instance was created, then the *-B* option will operate on + the snapshot within the buffer. + + +SEE ALSO +-------- +trace-cmd(1), trace-cmd-record(1), trace-cmd-report(1), trace-cmd-start(1), +trace-cmd-extract(1), trace-cmd-reset(1), trace-cmd-split(1), +trace-cmd-list(1), trace-cmd-listen(1) + +AUTHOR +------ +Written by Steven Rostedt, <rostedt@goodmis.org> + +RESOURCES +--------- +https://git.kernel.org/pub/scm/utils/trace-cmd/trace-cmd.git/ + +COPYING +------- +Copyright \(C) 2010 Red Hat, Inc. Free use of this software is granted under +the terms of the GNU Public License (GPL). + diff --git a/Documentation/trace-cmd/trace-cmd-split.1.txt b/Documentation/trace-cmd/trace-cmd-split.1.txt new file mode 100644 index 00000000..25385796 --- /dev/null +++ b/Documentation/trace-cmd/trace-cmd-split.1.txt @@ -0,0 +1,107 @@ +TRACE-CMD-SPLIT(1) +================== + +NAME +---- +trace-cmd-split - split a trace.dat file into smaller files + +SYNOPSIS +-------- +*trace-cmd split* ['OPTIONS'] ['start-time' ['end-time']] + +DESCRIPTION +----------- +The trace-cmd(1) split is used to break up a trace.dat into small files. +The 'start-time' specifies where the new file will start at. Using +'trace-cmd-report(1)' and copying the time stamp given at a particular event, +can be used as input for either 'start-time' or 'end-time'. The split will +stop creating files when it reaches an event after 'end-time'. If only the +end-time is needed, use 0.0 as the start-time. + +If start-time is left out, then the split will start at the beginning of the +file. If end-time is left out, then split will continue to the end unless it +meets one of the requirements specified by the options. + +OPTIONS +------- +*-i* 'file':: + If this option is not specified, then the split command will look for the + file named 'trace.dat'. This options will allow the reading of another + file other than 'trace.dat'. + +*-o* 'file':: + By default, the split command will use the input file name as a basis of + where to write the split files. The output file will be the input file + with an attached \'.#\' to the end: trace.dat.1, trace.dat.2, etc. + + This option will change the name of the base file used. + + -o file will create file.1, file.2, etc. + +*-s* 'seconds':: + This specifies how many seconds should be recorded before the new file + should stop. + +*-m* 'milliseconds':: + This specifies how many milliseconds should be recorded before the new + file should stop. + +*-u* 'microseconds':: + This specifies how many microseconds should be recorded before the new + file should stop. + +*-e* 'events':: + This specifies how many events should be recorded before the new file + should stop. + +*-p* 'pages':: + This specifies the number of pages that should be recorded before the new + file should stop. + + Note: only one of *-p*, *-e*, *-u*, *-m*, *-s* may be specified at a time. + + If *-p* is specified, then *-c* is automatically set. + +*-r*:: + This option causes the break up to repeat until end-time is reached (or + end of the input if end-time is not specified). + + trace-cmd split -r -e 10000 + + This will break up trace.dat into several smaller files, each with at most + 10,000 events in it. + +*-c*:: + This option causes the above break up to be per CPU. + + trace-cmd split -c -p 10 + + This will create a file that has 10 pages per each CPU from the input. + +*-C* 'cpu':: + This option will split for a single CPU. Only the cpu named will be extracted + from the file. + + trace-cmd split -C 1 + + This will split out all the events for cpu 1 in the file. + +SEE ALSO +-------- +trace-cmd(1), trace-cmd-record(1), trace-cmd-report(1), trace-cmd-start(1), +trace-cmd-stop(1), trace-cmd-extract(1), trace-cmd-reset(1), +trace-cmd-list(1), trace-cmd-listen(1) + +AUTHOR +------ +Written by Steven Rostedt, <rostedt@goodmis.org> + +RESOURCES +--------- +https://git.kernel.org/pub/scm/utils/trace-cmd/trace-cmd.git/ + +COPYING +------- +Copyright \(C) 2010 Red Hat, Inc. Free use of this software is granted under +the terms of the GNU Public License (GPL). + diff --git a/Documentation/trace-cmd/trace-cmd-stack.1.txt b/Documentation/trace-cmd/trace-cmd-stack.1.txt new file mode 100644 index 00000000..20752407 --- /dev/null +++ b/Documentation/trace-cmd/trace-cmd-stack.1.txt @@ -0,0 +1,50 @@ +TRACE-CMD-STACK(1) +================== + +NAME +---- +trace-cmd-stack - read, enable or disable Ftrace Linux kernel stack tracing. + +SYNOPSIS +-------- +*trace-cmd stack* + +DESCRIPTION +----------- +The trace-cmd(1) stack enables the Ftrace stack tracer within the kernel. +The stack tracer enables the function tracer and at each function call +within the kernel, the stack is checked. When a new maximum usage stack +is discovered, it is recorded. + +When no option is used, the current stack is displayed. + +To enable the stack tracer, use the option *--start*, and to disable +the stack tracer, use the option *--stop*. The output will be the maximum +stack found since the start was enabled. + +Use *--reset* to reset the stack counter to zero. + +User *--verbose*[='level'] to set the log level. Supported log levels are "none", "critical", "error", +"warning", "info", "debug", "all" or their identifiers "0", "1", "2", "3", "4", "5", "6". Setting +the log level to specific value enables all logs from that and all previous levels. The level will +default to "info" if one is not specified. + +SEE ALSO +-------- +trace-cmd(1), trace-cmd-record(1), trace-cmd-report(1), trace-cmd-start(1), +trace-cmd-extract(1), trace-cmd-reset(1), trace-cmd-split(1), +trace-cmd-list(1), trace-cmd-listen(1) + +AUTHOR +------ +Written by Steven Rostedt, <rostedt@goodmis.org> + +RESOURCES +--------- +https://git.kernel.org/pub/scm/utils/trace-cmd/trace-cmd.git/ + +COPYING +------- +Copyright \(C) 2010 Red Hat, Inc. Free use of this software is granted under +the terms of the GNU Public License (GPL). + diff --git a/Documentation/trace-cmd/trace-cmd-start.1.txt b/Documentation/trace-cmd/trace-cmd-start.1.txt new file mode 100644 index 00000000..03c5d127 --- /dev/null +++ b/Documentation/trace-cmd/trace-cmd-start.1.txt @@ -0,0 +1,51 @@ +TRACE-CMD-START(1) +================== + +NAME +---- +trace-cmd-start - start the Ftrace Linux kernel tracer without recording + +SYNOPSIS +-------- +*trace-cmd start* ['OPTIONS'] + +DESCRIPTION +----------- +The trace-cmd(1) start enables all the Ftrace tracing the same way +trace-cmd-record(1) does. The difference is that it does not run threads to +create a trace.dat file. This is useful just to enable Ftrace and you are only +interested in the trace after some event has occurred and the trace is +stopped. Then the trace can be read straight from the Ftrace pseudo file +system or can be extracted with trace-cmd-extract(1). + +OPTIONS +------- +The options are the same as 'trace-cmd-record(1)', except that it does not +take options specific to recording (*-s*, *-o*, *-N*, and *-t*). + +*--fork* :: + This option is only available for trace-cmd start. It tells trace-cmd + to not wait for the process to finish before returning. + With this option, trace-cmd start will return right after it forks + the process on the command line. This option only has an effect if + trace-cmd start also executes a command. + +SEE ALSO +-------- +trace-cmd(1), trace-cmd-record(1), trace-cmd-report(1), trace-cmd-stop(1), +trace-cmd-extract(1), trace-cmd-reset(1), trace-cmd-split(1), +trace-cmd-list(1), trace-cmd-listen(1) + +AUTHOR +------ +Written by Steven Rostedt, <rostedt@goodmis.org> + +RESOURCES +--------- +https://git.kernel.org/pub/scm/utils/trace-cmd/trace-cmd.git/ + +COPYING +------- +Copyright \(C) 2010 Red Hat, Inc. Free use of this software is granted under +the terms of the GNU Public License (GPL). + diff --git a/Documentation/trace-cmd/trace-cmd-stat.1.txt b/Documentation/trace-cmd/trace-cmd-stat.1.txt new file mode 100644 index 00000000..fb800f91 --- /dev/null +++ b/Documentation/trace-cmd/trace-cmd-stat.1.txt @@ -0,0 +1,80 @@ +TRACE-CMD-STAT(1) +================= + +NAME +---- +trace-cmd-stat - show the status of the tracing (ftrace) system + +SYNOPSIS +-------- +*trace-cmd stat* ['OPTIONS'] + +DESCRIPTION +----------- +The trace-cmd(1) stat displays the various status of the tracing (ftrace) +system. The status that it shows is: + +*Instances:* List all configured ftrace instances. + +*Tracer:* if one of the tracers (like function_graph) is active. Otherwise + nothing is displayed. + +*Events:* Lists the events that are enable. + +*Event filters:* Shows any filters that are set for any events + +*Function filters:* Shows any filters for the function tracers + +*Graph functions:* Shows any functions that the function graph tracer should graph + +*Buffers:* Shows the trace buffer size if they have been expanded. + By default, tracing buffers are in a compressed format until they are used. + If they are compressed, the buffer display will not be shown. + +*Trace clock:* If the tracing clock is anything other than the default "local" + it will be displayed. + +*Trace CPU mask:* If not all available CPUs are in the tracing CPU mask, then + the tracing CPU mask will be displayed. + +*Trace max latency:* Shows the value of the trace max latency if it is other than zero. + +*Kprobes:* Shows any kprobes that are defined for tracing. + +*Uprobes:* Shows any uprobes that are defined for tracing. + +*Error log:* Dump the content of ftrace error_log file. + +OPTIONS +------- +*-B* 'buffer-name':: + Display the status of a given buffer instance. May be specified more than once + to display the status of multiple instances. + +*-t*:: + If *-B* is also specified, show the status of the top level tracing directory + as well as the instance(s). + +*-o*:: + Display the all the options along with their values. If they start with "no", then + the option is disabled. + +SEE ALSO +-------- +trace-cmd(1), trace-cmd-record(1), trace-cmd-report(1), trace-cmd-start(1), +trace-cmd-stop(1), trace-cmd-extract(1), trace-cmd-reset(1), +trace-cmd-split(1), trace-cmd-listen(1) + +AUTHOR +------ +Written by Steven Rostedt, <rostedt@goodmis.org> + +RESOURCES +--------- +https://git.kernel.org/pub/scm/utils/trace-cmd/trace-cmd.git/ + +COPYING +------- +Copyright \(C) 2014 Red Hat, Inc. Free use of this software is granted under +the terms of the GNU Public License (GPL). + diff --git a/Documentation/trace-cmd/trace-cmd-stop.1.txt b/Documentation/trace-cmd/trace-cmd-stop.1.txt new file mode 100644 index 00000000..313192c3 --- /dev/null +++ b/Documentation/trace-cmd/trace-cmd-stop.1.txt @@ -0,0 +1,63 @@ +TRACE-CMD-STOP(1) +================= + +NAME +---- +trace-cmd-stop - stop the Ftrace Linux kernel tracer from writing to the ring +buffer. + +SYNOPSIS +-------- +*trace-cmd stop* ['OPTIONS'] + +DESCRIPTION +----------- +The trace-cmd(1) stop is a complement to 'trace-cmd-start(1)'. This will +disable Ftrace from writing to the ring buffer. This does not stop the +overhead that the tracing may incur. Only the updating of the ring buffer is +disabled, the Ftrace tracing may still be inducing overhead. + +After stopping the trace, the 'trace-cmd-extract(1)' may strip out the data +from the ring buffer and create a trace.dat file. The Ftrace pseudo file +system may also be examined. + +To disable the tracing completely to remove the overhead it causes, use +'trace-cmd-reset(1)'. But after a reset is performed, the data that has been +recorded is lost. + +OPTIONS +------- +*-B* 'buffer-name':: + If the kernel supports multiple buffers, this will stop the trace for + only the given buffer. It does not affect any other buffer. This may be + used multiple times to specify different buffers. When this option is + used, the top level instance will not be stopped unless *-t* is given. + +*-a*:: + Stop the trace for all existing buffer instances. When this option + is used, the top level instance will not be stopped unless *-t* is given. + +*-t*:: + Stops the top level instance buffer. Without the *-B* or *-a* option this + is the same as the default. But if *-B* or *-a* is used, this is + required if the top level instance buffer should also be stopped. + +SEE ALSO +-------- +trace-cmd(1), trace-cmd-record(1), trace-cmd-report(1), trace-cmd-start(1), +trace-cmd-extract(1), trace-cmd-reset(1), trace-cmd-split(1), +trace-cmd-list(1), trace-cmd-listen(1) + +AUTHOR +------ +Written by Steven Rostedt, <rostedt@goodmis.org> + +RESOURCES +--------- +https://git.kernel.org/pub/scm/utils/trace-cmd/trace-cmd.git/ + +COPYING +------- +Copyright \(C) 2010 Red Hat, Inc. Free use of this software is granted under +the terms of the GNU Public License (GPL). + diff --git a/Documentation/trace-cmd/trace-cmd-stream.1.txt b/Documentation/trace-cmd/trace-cmd-stream.1.txt new file mode 100644 index 00000000..f83652b8 --- /dev/null +++ b/Documentation/trace-cmd/trace-cmd-stream.1.txt @@ -0,0 +1,50 @@ +TRACE-CMD-STREAM(1) +=================== + +NAME +---- +trace-cmd-stream - stream a trace to stdout as it is happening + +SYNOPSIS +-------- +*trace-cmd stream ['OPTIONS']* ['command'] + +DESCRIPTION +----------- +The trace-cmd(1) stream will start tracing just like trace-cmd-record(1), except +it will not record to a file and instead it will read the binary buffer +as it is happening, convert it to a human readable format and write it to +stdout. + +This is basically the same as trace-cmd-start(1) and then doing a trace-cmd-show(1) +with the *-p* option. trace-cmd-stream is not as efficient as reading from the +pipe file as most of the stream work is done in userspace. This is useful if +it is needed to do the work mostly in userspace instead of the kernel, and stream +also helps to debug trace-cmd-profile(1) which uses the stream code to perform +the live data analysis for the profile. + + +OPTIONS +------- + These are the same as trace-cmd-record(1), except that it does not take + the *-o* option. + +SEE ALSO +-------- +trace-cmd(1), trace-cmd-record(1), trace-cmd-report(1), trace-cmd-start(1), +trace-cmd-stop(1), trace-cmd-reset(1), trace-cmd-split(1), +trace-cmd-list(1), trace-cmd-listen(1) + +AUTHOR +------ +Written by Steven Rostedt, <rostedt@goodmis.org> + +RESOURCES +--------- +https://git.kernel.org/pub/scm/utils/trace-cmd/trace-cmd.git/ + +COPYING +------- +Copyright \(C) 2014 Red Hat, Inc. Free use of this software is granted under +the terms of the GNU Public License (GPL). + diff --git a/Documentation/trace-cmd/trace-cmd.1.txt b/Documentation/trace-cmd/trace-cmd.1.txt new file mode 100644 index 00000000..7e161273 --- /dev/null +++ b/Documentation/trace-cmd/trace-cmd.1.txt @@ -0,0 +1,109 @@ +TRACE-CMD(1) +============ + +NAME +---- +trace-cmd - interacts with Ftrace Linux kernel internal tracer + +SYNOPSIS +-------- +*trace-cmd* 'COMMAND' ['OPTIONS'] + +DESCRIPTION +----------- +The trace-cmd(1) command interacts with the Ftrace tracer that is built inside +the Linux kernel. It interfaces with the Ftrace specific files found in the +debugfs file system under the tracing directory. A 'COMMAND' must be +specified to tell trace-cmd what to do. + + +COMMANDS +-------- + + record - record a live trace and write a trace.dat file to the + local disk or to the network. + + set - set a ftrace configuration parameter. + + report - reads a trace.dat file and converts the binary data to a + ASCII text readable format. + + stream - Start tracing and read the output directly + + profile - Start profiling and read the output directly + + hist - show a histogram of the events. + + stat - show tracing (ftrace) status of the running system + + options - list the plugin options that are available to *report* + + start - start the tracing without recording to a trace.dat file. + + stop - stop tracing (only disables recording, overhead of tracer + is still in effect) + + restart - restart tracing from a previous stop (only effects recording) + + extract - extract the data from the kernel buffer and create a trace.dat + file. + + show - display the contents of one of the Ftrace Linux kernel tracing files + + reset - disables all tracing and gives back the system performance. + (clears all data from the kernel buffers) + + clear - clear the content of the Ftrace ring buffers. + + split - splits a trace.dat file into smaller files. + + list - list the available plugins or events that can be recorded. + + listen - open up a port to listen for remote tracing connections. + + agent - listen on a vsocket for trace clients + + setup-guest - create FIFOs for tracing guest VMs + + restore - restore the data files of a crashed run of trace-cmd record + + snapshot- take snapshot of running trace + + stack - run and display the stack tracer + + check-events - parse format strings for all trace events and return + whether all formats are parseable + + convert - convert trace files + + dump - read out the meta data from a trace file + +OPTIONS +------- + +*-h*, --help:: + Display the help text. + +Other options see the man page for the corresponding command. + +SEE ALSO +-------- +trace-cmd-record(1), trace-cmd-report(1), trace-cmd-hist(1), trace-cmd-start(1), +trace-cmd-stop(1), trace-cmd-extract(1), trace-cmd-reset(1), +trace-cmd-restore(1), trace-cmd-stack(1), trace-cmd-convert(1), +trace-cmd-split(1), trace-cmd-list(1), trace-cmd-listen(1), +trace-cmd.dat(5), trace-cmd-check-events(1) trace-cmd-stat(1) + +AUTHOR +------ +Written by Steven Rostedt, <rostedt@goodmis.org> + +RESOURCES +--------- +https://git.kernel.org/pub/scm/utils/trace-cmd/trace-cmd.git/ + +COPYING +------- +Copyright \(C) 2010 Red Hat, Inc. Free use of this software is granted under +the terms of the GNU Public License (GPL). + diff --git a/Documentation/trace-cmd/trace-cmd.dat.v6.5.txt b/Documentation/trace-cmd/trace-cmd.dat.v6.5.txt new file mode 100644 index 00000000..8437b363 --- /dev/null +++ b/Documentation/trace-cmd/trace-cmd.dat.v6.5.txt @@ -0,0 +1,266 @@ +TRACE-CMD.DAT.v6(5) +=================== + +NAME +---- +trace-cmd.dat.v6 - trace-cmd version 6 file format + +SYNOPSIS +-------- +*trace-cmd.dat* ignore + +DESCRIPTION +----------- +The trace-cmd(1) utility produces a "trace.dat" file. The file may also +be named anything depending if the user specifies a different output name, +but it must have a certain binary format. The file is used +by trace-cmd to save kernel traces into it and be able to extract +the trace from it at a later point (see *trace-cmd-report(1)*). + + +INITIAL FORMAT +-------------- + + The first three bytes contain the magic value: + + 0x17 0x08 0x44 + + The next 7 bytes contain the characters: + + "tracing" + + The next set of characters contain a null '\0' terminated string + that contains the version of the file: + + "6\0" + + The next 1 byte contains the flags for the file endianess: + + 0 = little endian + 1 = big endian + + The next byte contains the number of bytes per "long" value: + + 4 - 32-bit long values + 8 - 64-bit long values + + Note: This is the long size of the target's userspace. Not the + kernel space size. + + [ Now all numbers are written in file defined endianess. ] + + The next 4 bytes are a 32-bit word that defines what the traced + host machine page size was. + +HEADER INFO FORMAT +------------------ + + Directly after the initial format comes information about the + trace headers recorded from the target box. + + The next 12 bytes contain the string: + + "header_page\0" + + The next 8 bytes are a 64-bit word containing the size of the + page header information stored next. + + The next set of data is of the size read from the previous 8 bytes, + and contains the data retrieved from debugfs/tracing/events/header_page. + + Note: The size of the second field \fBcommit\fR contains the target + kernel long size. For example: + + field: local_t commit; offset:8; \fBsize:8;\fR signed:1; + + shows the kernel has a 64-bit long. + + The next 13 bytes contain the string: + + "header_event\0" + + The next 8 bytes are a 64-bit word containing the size of the + event header information stored next. + + The next set of data is of the size read from the previous 8 bytes + and contains the data retrieved from debugfs/tracing/events/header_event. + + This data allows the trace-cmd tool to know if the ring buffer format + of the kernel made any changes. + +FTRACE EVENT FORMATS +-------------------- + + Directly after the header information comes the information about + the Ftrace specific events. These are the events used by the Ftrace plugins + and are not enabled by the event tracing. + + The next 4 bytes contain a 32-bit word of the number of Ftrace event + format files that are stored in the file. + + For the number of times defined by the previous 4 bytes is the + following: + + 8 bytes for the size of the Ftrace event format file. + + The Ftrace event format file copied from the target machine: + debugfs/tracing/events/ftrace/<event>/format + +EVENT FORMATS +------------- + + Directly after the Ftrace formats comes the information about + the event layout. + + The next 4 bytes are a 32-bit word containing the number of + event systems that are stored in the file. These are the + directories in debugfs/tracing/events excluding the \fBftrace\fR + directory. + + For the number of times defined by the previous 4 bytes is the + following: + + A null-terminated string containing the system name. + + 4 bytes containing a 32-bit word containing the number + of events within the system. + + For the number of times defined in the previous 4 bytes is the + following: + + 8 bytes for the size of the event format file. + + The event format file copied from the target machine: + debugfs/tracing/events/<system>/<event>/format + +KALLSYMS INFORMATION +-------------------- + + Directly after the event formats comes the information of the mapping + of function addresses to the function names. + + The next 4 bytes are a 32-bit word containing the size of the + data holding the function mappings. + + The next set of data is of the size defined by the previous 4 bytes + and contains the information from the target machine's file: + /proc/kallsyms + + +TRACE_PRINTK INFORMATION +------------------------ + + If a developer used trace_printk() within the kernel, it may + store the format string outside the ring buffer. + This information can be found in: + debugfs/tracing/printk_formats + + The next 4 bytes are a 32-bit word containing the size of the + data holding the printk formats. + + The next set of data is of the size defined by the previous 4 bytes + and contains the information from debugfs/tracing/printk_formats. + + +PROCESS INFORMATION +------------------- + + Directly after the trace_printk formats comes the information mapping + a PID to a process name. + + The next 8 bytes contain a 64-bit word that holds the size of the + data mapping the PID to a process name. + + The next set of data is of the size defined by the previous 8 bytes + and contains the information from debugfs/tracing/saved_cmdlines. + + +REST OF TRACE-CMD HEADER +------------------------ + + Directly after the process information comes the last bit of the + trace.dat file header. + + The next 4 bytes are a 32-bit word defining the number of CPUs that + were discovered on the target machine (and has matching trace data + for it). + + The next 10 bytes are one of the following: + + "options \0" + + "latency \0" + + "flyrecord\0" + + If it is "options \0" then: + + The next 2 bytes are a 16-bit word defining the current option. + If the the value is zero then there are no more options. + + Otherwise, the next 4 bytes contain a 32-bit word containing the + option size. If the reader does not know how to handle the option + it can simply skip it. Currently there are no options defined, + but this is here to extend the data. + + The next option will be directly after the previous option, and + the options ends with a zero in the option type field. + + The next 10 bytes after the options are one of the following: + + "latency \0" + + "flyrecord\0" + + which would follow the same as if options were not present. + + If the value is "latency \0", then the rest of the file is + simply ASCII text that was taken from the target's: + debugfs/tracing/trace + + If the value is "flyrecord\0", the following is present: + + For the number of CPUs that were read earlier, the + following is present: + + 8 bytes that are a 64-bit word containing the offset into the file + that holds the data for the CPU. + + 8 bytes that are a 64-bit word containing the size of the CPU + data at that offset. + +CPU DATA +-------- + + The CPU data is located in the part of the file that is specified + in the end of the header. Padding is placed between the header and + the CPU data, placing the CPU data at a page aligned (target page) position + in the file. + + This data is copied directly from the Ftrace ring buffer and is of the + same format as the ring buffer specified by the event header files + loaded in the header format file. + + The trace-cmd tool will try to \fBmmap(2)\fR the data page by page with the + target's page size if possible. If it fails to mmap, it will just read the + data instead. + +SEE ALSO +-------- +trace-cmd(1), trace-cmd-record(1), trace-cmd-report(1), trace-cmd-start(1), +trace-cmd-stop(1), trace-cmd-extract(1), trace-cmd-reset(1), +trace-cmd-split(1), trace-cmd-list(1), trace-cmd-listen(1), +trace-cmd.dat(5) + +AUTHOR +------ +Written by Steven Rostedt, <rostedt@goodmis.org> + +RESOURCES +--------- +https://git.kernel.org/pub/scm/utils/trace-cmd/trace-cmd.git/ + +COPYING +------- +Copyright \(C) 2010 Red Hat, Inc. Free use of this software is granted under +the terms of the GNU Public License (GPL). diff --git a/Documentation/trace-cmd/trace-cmd.dat.v7.5.txt b/Documentation/trace-cmd/trace-cmd.dat.v7.5.txt new file mode 100644 index 00000000..e5bcac76 --- /dev/null +++ b/Documentation/trace-cmd/trace-cmd.dat.v7.5.txt @@ -0,0 +1,451 @@ +TRACE-CMD.DAT.v7(5) +=================== + +NAME +---- +trace-cmd.dat.v7 - trace-cmd version 7 file format + +SYNOPSIS +-------- +*trace-cmd.dat* ignore + +DESCRIPTION +----------- +The trace-cmd(1) utility produces a "trace.dat" file. The file may also +be named anything depending if the user specifies a different output name, +but it must have a certain binary format. The file is used +by trace-cmd to save kernel traces into it and be able to extract +the trace from it at a later point (see *trace-cmd-report(1)*). + + +INITIAL FORMAT +-------------- + + The first three bytes contain the magic value: + + 0x17 0x08 0x44 + + The next 7 bytes contain the characters: + + "tracing" + + The next set of characters contain a null '\0' terminated string + that contains the version of the file: + + "7\0" + + The next 1 byte contains the flags for the file endianess: + + 0 = little endian + 1 = big endian + + The next byte contains the number of bytes per "long" value: + + 4 - 32-bit long values + 8 - 64-bit long values + + Note: This is the long size of the target's user space. Not the + kernel space size. + + [ Now all numbers are written in file defined endianess. ] + + The next 4 bytes are a 32-bit word that defines what the traced + host machine page size was. + + The compression algorithm header is written next: + "name\0version\0" + where "name" and "version" are strings, name and version of the + compression algorithm used to compress the trace file. If the name + is "none", the data in the file is not compressed. + + The next 8 bytes are 64-bit integer, the offset within the file where + the first OPTIONS section is located. + + The rest of the file consists of different sections. The only mandatory + is the first OPTIONS section, all others are optional. The location and + the order of the sections is not strict. Each section starts with a header: + +FORMAT OF THE SECTION HEADER +---------------------------- + <2 bytes> unsigned short integer, ID of the section. + <2 bytes> unsigned short integer, section flags: + 1 = the section is compressed. + <4 bytes> ID of a string, description of the section. + <4 bytes> unsigned integer, size of the section in the file. + + If the section is compressed, the above is the compressed size. + The section must be uncompressed on reading. The described format of + the sections refers to the uncompressed data. + +COMPRESSION FORMAT OF THE FILE SECTIONS +--------------------------------------- + + Some of the sections in the file may be compressed with the compression algorithm, + specified in the compression algorithm header. Compressed sections have a compression + header, written after the section header and right before the compressed data: + <4 bytes> unsigned int, size of compressed data in this section. + <4 bytes> unsigned int, size of uncompressed data. + <data> binary compressed data, with the specified size. + +COMPRESSION FORMAT OF THE TRACE DATA +------------------------------------ + + There are two special sections, BUFFER FLYRECORD and BUFFER LATENCY, containing + trace data. These sections may be compressed with the compression algorithm, specified + in the compression header. Usually the size of these sections is huge, that's why its + compression format is different from the other sections. The trace data is compressed + in chunks The size of one chunk is specified in the file creation time. The format + of compressed trace data is: + <4 bytes> unsigned int, count of chunks. + Follows the compressed chunks of given count. For each chunk: + <4 bytes> unsigned int, size of compressed data in this chunk. + <4 bytes> unsigned int, size of uncompressed data, aligned with the trace page size. + <data> binary compressed data, with the specified size. + These chunks must be uncompressed on reading. The described format of + trace data refers to the uncompressed data. + +OPTIONS SECTION +--------------- + + Section ID: 0 + + This is the the only mandatory section in the file. There can be multiple + options sections, the first one is located at the offset specified right + after the compression algorithm header. The section consists of multiple + trace options, each option has the following format: + <2 bytes> unsigned short integer, ID of the option. + <4 bytes> unsigned integer, size of the option's data. + <binary data> bytes of the size specified above, data of the option. + + + Options, supported by the trace file version 7: + + DONE: id 0, size 8 + This option indicates the end of the options section, it is written + always as last option. The DONE option data is: + <8 bytes> long long unsigned integer, offset in the trace file where + the next options section is located. If this offset is 0, then there + are no more options sections. + + DATE: id 1, size vary + The DATE option data is a null terminated ASCII string, which represents + the time difference between trace events timestamps and the Generic Time + of Day of the system. + + CPUSTAT: id 2, size vary + The CPUSTAT option data is a null terminated ASCII string, the content of the + "per_cpu/cpu<id>/stats" file from the trace directory. There is a CPUSTAT option + for each CPU. + + BUFFER: id 3, size vary + The BUFFER option describes the flyrecord trace data saved in the file, collected + from one trace instance. There is BUFFER option for each trace instance. The format + of the BUFFER data is: + <8 bytes> long long unsigned integer, offset in the trace file where the + BUFFER FLYRECORD section is located, containing flyrecord trace data. + <string> a null terminated ASCII string, name of the trace instance. Empty string "" + is saved as name of the top instance. + <string> a null terminated ASCII string, trace clock used for events timestamps in + this trace instance. + <4 bytes> unsigned integer, size of the trace buffer page. + <4 bytes> unsigned integer, count of the CPUs with trace data. + For each CPU of the above count: + <4 bytes> unsigned integer, ID of the CPU. + <8 bytes> long long unsigned integer, offset in the trace file where the trace data + for this CPU is located. + <8 bytes> long long unsigned integer, size of the trace data for this CPU. + + TRACECLOCK: id 4, size vary + The TRACECLOCK option data is a null terminated ASCII string, the content of the + "trace_clock" file from the trace directory. + + UNAME: id 5, size vary + The UNAME option data is a null terminated ASCII string, identifying the system where + the trace data is collected. The string is retrieved by the uname() system call. + + HOOK: id 6, size vary + The HOOK option data is a null terminated ASCII string, describing event hooks: custom + event matching to connect any two events together. + + OFFSET: id 7, size vary + The OFFSET option data is a null terminated ASCII string, representing a fixed time that + is added to each event timestamp on reading. + + CPUCOUNT: id 8, size 4 + The CPUCOUNT option data is: + <4 bytes> unsigned integer, number of CPUs in the system. + + VERSION: id 9, size vary + The VERSION option data is a null terminated ASCII string, representing the version of + the trace-cmd application, used to collect these trace logs. + + PROCMAPS: id 10, size vary + The PROCMAPS option data is a null terminated ASCII string, representing the memory map + of each traced filtered process. The format of the string is, for each filtered process: + <procss ID> <libraries count> <process command> \n + <memory start address> <memory end address> <full path of the mapped library file> \n + ... + separate line for each library, used by this process + ... + ... + + TRACEID: id 11, size 8 + The TRACEID option data is a unique identifier of this tracing session: + <8 bytes> long long unsigned integer, trace session identifier. + + TIME_SHIFT: id 12, size vary + The TIME_SHIFT option stores time synchronization information, collected during host and guest + tracing session. Usually it is saved in the guest trace file. This information is used to + synchronize guest with host events timestamps, when displaying all files from this tracing + session. The format of the TIME_SHIFT option data is: + <8 bytes> long long unsigned integer, trace identifier of the peer (usually the host). + <4 bytes> unsigned integer, flags specific to the time synchronization protocol, used in this + trace session. + <4 bytes> unsigned integer, number of traced CPUs. For each CPU, timestamps corrections + are recorded: + <4 bytes> unsigned integer, count of the recorded timestamps corrections for this CPU. + <array of unsigned long long integers of the above count>, times when the corrections are calculated + <array of unsigned long long integers of the above count>, corrections offsets + <array of unsigned long long integers of the above count>, corrections scaling ratio + + GUEST: id 13, size vary + The GUEST option stores information about traced guests in this tracing session. Usually it is + saved in the host trace file. There is a separate GUEST option for each traced guest. + The information is used when displaying all files from this tracing session. The format of + the GUEST option data is: + <string> a null terminated ASCII string, name of the guest. + <8 bytes> long long unsigned integer, trace identifier of the guest for this session. + <4 bytes> unsigned integer, number of guest's CPUs. For each CPU: + <4 bytes> unsigned integer, ID of the CPU. + <4 bytes> unsigned integer, PID of the host task, emulating this guest CPU. + + TSC2NSEC: id 14, size 16 + The TSC2NSEC option stores information, used to convert TSC events timestamps to nanoseconds. + The format of the TSC2NSEC option data is: + <4 bytes> unsigned integer, time multiplier. + <4 bytes> unsigned integer, time shift. + <8 bytes> unsigned long long integer, time offset. + + HEADER_INFO: id 16, size 8 + The HEADER_INFO option data is: + <8 bytes> long long unsigned integer, offset into the trace file where the HEADER INFO + section is located + + FTRACE_EVENTS: id 17, size 8 + The FTRACE_EVENTS option data is: + <8 bytes> long long unsigned integer, offset into the trace file where the + FTRACE EVENT FORMATS section is located. + + EVENT_FORMATS: id 18, size 8 + The EVENT_FORMATS option data is: + <8 bytes> long long unsigned integer, offset into the trace file where the EVENT FORMATS + section is located. + + KALLSYMS: id 19, size 8 + The KALLSYMS option data is: + <8 bytes> long long unsigned integer, offset into the trace file where the KALLSYMS + section is located. + + PRINTK: id 20, size 8 + The PRINTK option data is: + <8 bytes> long long unsigned integer, offset into the trace file where the TRACE_PRINTK + section is located. + + CMDLINES: id 21, size 8 + The CMDLINES option data is: + <8 bytes> long long unsigned integer, offset into the trace file where the + SAVED COMMAND LINES section is located. + + BUFFER_TEXT: id 22, size + The BUFFER_LAT option describes the latency trace data saved in the file. The format + of the BUFFER_LAT data is: + <8 bytes> long long unsigned integer, offset in the trace file where the + BUFFER LATENCY section is located, containing latency trace data. + <string> a null terminated ASCII string, name of the trace instance. Empty string "" + is saved as name of the top instance. + <string> a null terminated ASCII string, trace clock used for events timestamps in + this trace instance. + + +HEADER INFO SECTION +------------------- + + Section ID: 16 + + The first 12 bytes of the section, after the section header, contain the string: + + "header_page\0" + + The next 8 bytes are a 64-bit word containing the size of the + page header information stored next. + + The next set of data is of the size read from the previous 8 bytes, + and contains the data retrieved from debugfs/tracing/events/header_page. + + Note: The size of the second field \fBcommit\fR contains the target + kernel long size. For example: + + field: local_t commit; offset:8; \fBsize:8;\fR signed:1; + + shows the kernel has a 64-bit long. + + The next 13 bytes contain the string: + + "header_event\0" + + The next 8 bytes are a 64-bit word containing the size of the + event header information stored next. + + The next set of data is of the size read from the previous 8 bytes + and contains the data retrieved from debugfs/tracing/events/header_event. + + This data allows the trace-cmd tool to know if the ring buffer format + of the kernel made any changes. + +FTRACE EVENT FORMATS SECTION +---------------------------- + + Section ID: 17 + + Directly after the section header comes the information about + the Ftrace specific events. These are the events used by the Ftrace plugins + and are not enabled by the event tracing. + + The next 4 bytes contain a 32-bit word of the number of Ftrace event + format files that are stored in the file. + + For the number of times defined by the previous 4 bytes is the + following: + + 8 bytes for the size of the Ftrace event format file. + + The Ftrace event format file copied from the target machine: + debugfs/tracing/events/ftrace/<event>/format + +EVENT FORMATS SECTION +--------------------- + + Section ID: 18 + + Directly after the section header comes the information about + the event layout. + + The next 4 bytes are a 32-bit word containing the number of + event systems that are stored in the file. These are the + directories in debugfs/tracing/events excluding the \fBftrace\fR + directory. + + For the number of times defined by the previous 4 bytes is the + following: + + A null-terminated string containing the system name. + + 4 bytes containing a 32-bit word containing the number + of events within the system. + + For the number of times defined in the previous 4 bytes is the + following: + + 8 bytes for the size of the event format file. + + The event format file copied from the target machine: + debugfs/tracing/events/<system>/<event>/format + +KALLSYMS SECTION +---------------- + + Section ID: 19 + + Directly after the section header comes the information of the mapping + of function addresses to the function names. + + The next 4 bytes are a 32-bit word containing the size of the + data holding the function mappings. + + The next set of data is of the size defined by the previous 4 bytes + and contains the information from the target machine's file: + /proc/kallsyms + + +TRACE_PRINTK SECTION +-------------------- + + Section ID: 20 + + If a developer used trace_printk() within the kernel, it may + store the format string outside the ring buffer. + This information can be found in: + debugfs/tracing/printk_formats + + The next 4 bytes are a 32-bit word containing the size of the + data holding the printk formats. + + The next set of data is of the size defined by the previous 4 bytes + and contains the information from debugfs/tracing/printk_formats. + + +SAVED COMMAND LINES SECTION +--------------------------- + + Section ID: 21 + + Directly after the section header comes the information mapping + a PID to a process name. + + The next 8 bytes contain a 64-bit word that holds the size of the + data mapping the PID to a process name. + + The next set of data is of the size defined by the previous 8 bytes + and contains the information from debugfs/tracing/saved_cmdlines. + + +BUFFER FLYRECORD SECTION +------------------------ + + This section contains flyrecord tracing data, collected in one trace instance. + The data is saved per CPU. Each BUFFER FLYRECORD section has a corresponding BUFFER + option, containing information about saved CPU's trace data. Padding is placed between + the section header and the CPU data, placing the CPU data at a page aligned (target page) + position in the file. + + This data is copied directly from the Ftrace ring buffer and is of the + same format as the ring buffer specified by the event header files + loaded in the header format file. + + The trace-cmd tool will try to \fBmmap(2)\fR the data page by page with the + target's page size if possible. If it fails to mmap, it will just read the + data instead. + +BUFFER TEXT SECTION +------------------------ + + This section contains latency tracing data, ASCII text taken from the + target's debugfs/tracing/trace file. + +STRINGS SECTION +------------------------ + + All strings from trace file metadata are stored in string section in the file. The section + contains a list of NULL terminated ASCII strings. An ID of the string is used in the file + meta data, which is the offset of the actual string into the string section. Strings can be stored + into multiple string sections in the file. + +SEE ALSO +-------- +trace-cmd(1), trace-cmd-record(1), trace-cmd-report(1), trace-cmd-start(1), +trace-cmd-stop(1), trace-cmd-extract(1), trace-cmd-reset(1), +trace-cmd-split(1), trace-cmd-list(1), trace-cmd-listen(1), +trace-cmd.dat(5) + +AUTHOR +------ +Written by Steven Rostedt, <rostedt@goodmis.org> + +RESOURCES +--------- +https://git.kernel.org/pub/scm/utils/trace-cmd/trace-cmd.git/ + +COPYING +------- +Copyright \(C) 2010 Red Hat, Inc. Free use of this software is granted under +the terms of the GNU Public License (GPL). |