'\" t
.\"     Title: trace-cmd-set
.\"    Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
.\"      Date: 09/11/2020
.\"    Manual: \ \&
.\"    Source: \ \&
.\"  Language: English
.\"
.TH "TRACE\-CMD\-SET" "1" "09/11/2020" "\ \&" "\ \&"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
trace-cmd-set \- set a configuration parameter of the Ftrace Linux internal tracer
.SH "SYNOPSIS"
.sp
\fBtrace\-cmd set\fR [\fIOPTIONS\fR] [\fIcommand\fR]
.SH "DESCRIPTION"
.sp
The trace\-cmd(1) set command will set a configuration parameter of the Ftrace Linux kernel tracer\&. The specified \fBcommand\fR 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\&.
.SH "OPTIONS"
.PP
\fB\-p\fR \fItracer\fR
.RS 4
Specify a tracer\&. Tracers usually do more than just trace an event\&. Common tracers are:
\fBfunction\fR,
\fBfunction_graph\fR,
\fBpreemptirqsoff\fR,
\fBirqsoff\fR,
\fBpreemptoff\fR
and
\fBwakeup\fR\&. A tracer must be supported by the running kernel\&. To see a list of available tracers, see trace\-cmd\-list(1)\&.
.RE
.PP
\fB\-e\fR \fIevent\fR
.RS 4
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
\fIevent\fR
is of the format "subsystem:event\-name"\&. You can also just specify the subsystem without the
\fI:event\-name\fR
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\&.
.sp
.if n \{\
.RS 4
.\}
.nf
The \*(Aqevent\*(Aq can also contain glob expressions\&. That is, "*stat*" will
select all events (or subsystems) that have the characters "stat" in their
names\&.
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
The keyword \*(Aqall\*(Aq can be used to enable all events\&.
.fi
.if n \{\
.RE
.\}
.RE
.PP
\fB\-T\fR
.RS 4
Enable a stacktrace on each event\&. For example:
.sp
.if n \{\
.RS 4
.\}
.nf
          <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)
.fi
.if n \{\
.RE
.\}
.RE
.PP
\fB\-\-func\-stack\fR
.RS 4
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\&.
.RE
.PP
\fB\-f\fR \fIfilter\fR
.RS 4
Specify a filter for the previous event\&. This must come after a
\fB\-e\fR\&. 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\&.
.RE
.sp
.if n \{\
.RS 4
.\}
.nf
    ==, >=, <=, >, <, &, |, && and ||
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
The above are usually safe to use to compare fields\&.
.fi
.if n \{\
.RE
.\}
.PP
\fB\-R\fR \fItrigger\fR
.RS 4
Specify a trigger for the previous event\&. This must come after a
\fB\-e\fR\&. 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
\fB\-v\fR
option\&.
.sp
.if n \{\
.RS 4
.\}
.nf
See Documentation/trace/events\&.txt in the Linux kernel source for more
information on triggers\&.
.fi
.if n \{\
.RE
.\}
.RE
.PP
\fB\-v\fR
.RS 4
This will negate options specified after it on the command line\&. It affects:
.RE
.sp
.if n \{\
.RS 4
.\}
.nf
     \fB\-e\fR: 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\&.
     \fB\-B\fR: 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 \fB\-v\fR option was taken from the way grep(1) inverts the following
    matches\&.
.fi
.if n \{\
.RE
.\}
.PP
\fB\-P\fR \fIpid\fR
.RS 4
This will filter only the specified process IDs\&. Using
\fB\-P\fR
will let you trace only events that are caused by the process\&.
.RE
.PP
\fB\-c\fR
.RS 4
Used
\fB\-P\fR
to trace the process\*(Aq children too (if kernel supports it)\&.
.RE
.PP
\fB\-\-user\fR
.RS 4
Execute the specified
\fBcommand\fR
as given user\&.
.RE
.PP
\fB\-C\fR \fIclock\fR
.RS 4
Set the trace clock to "clock"\&.
.sp
.if n \{\
.RS 4
.\}
.nf
Use trace\-cmd(1) list \-C to see what clocks are available\&.
.fi
.if n \{\
.RE
.\}
.RE
.PP
\fB\-l\fR \fIfunction\-name\fR
.RS 4
This will limit the
\fIfunction\fR
and
\fIfunction_graph\fR
tracers to only trace the given function name\&. More than one
\fB\-l\fR
may be specified on the command line to trace more than one function\&. The limited use of glob expressions are also allowed\&. These are
\fImatch*\fR
to only filter functions that start with
\fImatch\fR\&.
\fI*match\fR
to only filter functions that end with
\fImatch\fR\&.
\fI*match\e*\fR
to only filter on functions that contain
\fImatch\fR\&.
.RE
.PP
\fB\-g\fR \fIfunction\-name\fR
.RS 4
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
\fB\-g\fR
on the command line\&.
.RE
.PP
\fB\-n\fR \fIfunction\-name\fR
.RS 4
This has the opposite effect of
\fB\-l\fR\&. The function given with the
\fB\-n\fR
option will not be traced\&. This takes precedence, that is, if you include the same function for both
\fB\-n\fR
and
\fB\-l\fR, it will not be traced\&.
.RE
.PP
\fB\-d\fR
.RS 4
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\&.
.RE
.PP
\fB\-D\fR
.RS 4
The option
\fB\-d\fR
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
\fB\-D\fR
option will disable both the ftrace_enabled proc file as well as the function\-trace option if it exists\&.
.sp
.if n \{\
.RS 4
.\}
.nf
Note, this disable function tracing for all users, which includes users
outside of ftrace tracers (stack_tracer, perf, etc)\&.
.fi
.if n \{\
.RE
.\}
.RE
.PP
\fB\-O\fR \fIoption\fR
.RS 4
Ftrace has various options that can be enabled or disabled\&. This allows you to set them\&. Appending the text
\fIno\fR
to an option disables it\&. For example: "\-O nograph\-time" will disable the "graph\-time" Ftrace option\&.
.RE
.PP
\fB\-b\fR \fIsize\fR
.RS 4
This sets the ring buffer size to
\fIsize\fR
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\&.
.RE
.PP
\fB\-B\fR \fIbuffer\-name\fR
.RS 4
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\&.
.sp
.if n \{\
.RS 4
.\}
.nf
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\&.
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
trace\-cmd set \-e sched \-B block \-e block \-B time \-e timer sleep 1
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
The above is will enable all sched events in the main buffer\&. It will
then create a \*(Aqblock\*(Aq buffer instance and enable all block events within
that buffer\&. A \*(Aqtime\*(Aq buffer instance is created and all timer events
will be enabled for that event\&.
.fi
.if n \{\
.RE
.\}
.RE
.PP
\fB\-m\fR \fIsize\fR
.RS 4
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\&.
.sp
.if n \{\
.RS 4
.\}
.nf
Use this to prevent running out of diskspace for long runs\&.
.fi
.if n \{\
.RE
.\}
.RE
.PP
\fB\-M\fR \fIcpumask\fR
.RS 4
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\&.
.sp
.if n \{\
.RS 4
.\}
.nf
trace\-cmd set \-p function \-M c \-B events13 \-e all \-M 5
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
If the \-M is left out, then the mask stays the same\&. To enable all
CPUs, pass in a value of \*(Aq\-1\*(Aq\&.
.fi
.if n \{\
.RE
.\}
.RE
.PP
\fB\-i\fR
.RS 4
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\&.
.RE
.PP
\fB\-q\fR | \fB\-\-quiet\fR
.RS 4
Suppresses normal output, except for errors\&.
.RE
.PP
\fB\-\-max\-graph\-depth\fR \fIdepth\fR
.RS 4
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\&.
.RE
.PP
\fB\-\-cmdlines\-size\fR \fIsize\fR
.RS 4
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\&.
.RE
.PP
\fB\-\-module\fR \fImodule\fR
.RS 4
Filter a module\(cqs name in function tracing\&. It is equivalent to adding
\fI:mod:module\fR
after all other functions being filtered\&. If no other function filter is listed, then all modules functions will be filtered in the filter\&.
.sp
.if n \{\
.RS 4
.\}
.nf
\*(Aq\-\-module snd\*(Aq  is equivalent to  \*(Aq\-l :mod:snd\*(Aq
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
\*(Aq\-\-module snd \-l "*jack*"\*(Aq is equivalent to \*(Aq\-l "*jack*:mod:snd"\*(Aq
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
\*(Aq\-\-module snd \-n "*"\*(Aq is equivalent to \*(Aq\-n :mod:snd\*(Aq
.fi
.if n \{\
.RE
.\}
.RE
.PP
\fB\-\-stderr\fR
.RS 4
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\&.
.RE
.PP
\fB\-\-fork\fR
.RS 4
If a command is listed, then trace\-cmd will wait for that command to finish, unless the
\fB\-\-fork\fR
option is specified\&. Then it will fork the command and return immediately\&.
.RE
.SH "EXAMPLES"
.sp
Enable all events for tracing:
.sp
.if n \{\
.RS 4
.\}
.nf
 # trace\-cmd set \-e all
.fi
.if n \{\
.RE
.\}
.sp
Set the function tracer:
.sp
.if n \{\
.RS 4
.\}
.nf
 # trace\-cmd set \-p function
.fi
.if n \{\
.RE
.\}
.SH "SEE ALSO"
.sp
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)
.SH "AUTHOR"
.sp
Written by Tzvetomir Stoyanov (VMware) <\m[blue]\fBtz\&.stoyanov@gmail\&.com\fR\m[]\&\s-2\u[1]\d\s+2>
.SH "RESOURCES"
.sp
git://git\&.kernel\&.org/pub/scm/linux/kernel/git/rostedt/trace\-cmd\&.git
.SH "COPYING"
.sp
Copyright (C) 2010 Red Hat, Inc\&. Free use of this software is granted under the terms of the GNU Public License (GPL)\&.
.SH "NOTES"
.IP " 1." 4
tz.stoyanov@gmail.com
.RS 4
\%mailto:tz.stoyanov@gmail.com
.RE