1TRACE-CMD-SET(1)                                              TRACE-CMD-SET(1)
2
3
4

NAME

6       trace-cmd-set - set a configuration parameter of the Ftrace Linux
7       internal tracer
8

SYNOPSIS

10       trace-cmd set [OPTIONS] [command]
11

DESCRIPTION

13       The trace-cmd(1) set command will set a configuration parameter of the
14       Ftrace Linux kernel tracer. The specified command will be run after the
15       ftrace state is set. The configured ftrace state can be restored to
16       default using the trace-cmd-reset(1) command.
17

OPTIONS

19       -p tracer
20           Specify a tracer. Tracers usually do more than just trace an event.
21           Common tracers are: function, function_graph, preemptirqsoff,
22           irqsoff, preemptoff and wakeup. A tracer must be supported by the
23           running kernel. To see a list of available tracers, see
24           trace-cmd-list(1).
25
26       -e event
27           Specify an event to trace. Various static trace points have been
28           added to the Linux kernel. They are grouped by subsystem where you
29           can enable all events of a given subsystem or specify specific
30           events to be enabled. The event is of the format
31           "subsystem:event-name". You can also just specify the subsystem
32           without the :event-name or the event-name without the "subsystem:".
33           Using "-e sched_switch" will enable the "sched_switch" event where
34           as, "-e sched" will enable all events under the "sched" subsystem.
35
36               The 'event' can also contain glob expressions. That is, "*stat*" will
37               select all events (or subsystems) that have the characters "stat" in their
38               names.
39
40               The keyword 'all' can be used to enable all events.
41
42       -T
43           Enable a stacktrace on each event. For example:
44
45                         <idle>-0     [003] 58549.289091: sched_switch:         kworker/0:1:0 [120] R ==> trace-cmd:2603 [120]
46                         <idle>-0     [003] 58549.289092: kernel_stack:         <stack trace>
47               => schedule (ffffffff814b260e)
48               => cpu_idle (ffffffff8100a38c)
49               => start_secondary (ffffffff814ab828)
50
51       --func-stack
52           Enable a stack trace on all functions. Note this is only applicable
53           for the "function" plugin tracer, and will only take effect if the
54           -l option is used and succeeds in limiting functions. If the
55           function tracer is not filtered, and the stack trace is enabled,
56           you can live lock the machine.
57
58       -f filter
59           Specify a filter for the previous event. This must come after a -e.
60           This will filter what events get recorded based on the content of
61           the event. Filtering is passed to the kernel directly so what
62           filtering is allowed may depend on what version of the kernel you
63           have. Basically, it will let you use C notation to check if an
64           event should be processed or not.
65
66               ==, >=, <=, >, <, &, |, && and ||
67
68           The above are usually safe to use to compare fields.
69
70       -R trigger
71           Specify a trigger for the previous event. This must come after a
72           -e. This will add a given trigger to the given event. To only
73           enable the trigger and not the event itself, then place the event
74           after the -v option.
75
76               See Documentation/trace/events.txt in the Linux kernel source for more
77               information on triggers.
78
79       -v
80           This will negate options specified after it on the command line. It
81           affects:
82
83                -e: Causes all specified events to not be traced. This is useful for
84                      selecting a subsystem to be traced but to leave out various events.
85                      For example: "-e sched -v -e "*stat*"" will enable all events in
86                      the sched subsystem except those that have "stat" in their names.
87                -B: Deletes the specified ftrace instance. There must be no
88                      configuration options related to this instance in the command line.
89                      For example: "-v -B bar -B foo" will delete instance bar and create
90                      a new instance foo.
91               Note: the -v option was taken from the way grep(1) inverts the following
92               matches.
93
94       -P pid
95           This will filter only the specified process IDs. Using -P will let
96           you trace only events that are caused by the process.
97
98       -c
99           Used -P to trace the process' children too (if kernel supports it).
100
101       --user
102           Execute the specified command as given user.
103
104       -C clock
105           Set the trace clock to "clock".
106
107               Use trace-cmd(1) list -C to see what clocks are available.
108
109       -l function-name
110           This will limit the function and function_graph tracers to only
111           trace the given function name. More than one -l may be specified on
112           the command line to trace more than one function. The limited use
113           of glob expressions are also allowed. These are match* to only
114           filter functions that start with match.  *match to only filter
115           functions that end with match.  *match\* to only filter on
116           functions that contain match.
117
118       -g function-name
119           This option is for the function_graph plugin. It will graph the
120           given function. That is, it will only trace the function and all
121           functions that it calls. You can have more than one -g on the
122           command line.
123
124       -n function-name
125           This has the opposite effect of -l. The function given with the -n
126           option will not be traced. This takes precedence, that is, if you
127           include the same function for both -n and -l, it will not be
128           traced.
129
130       -d
131           Some tracer plugins enable the function tracer by default. Like the
132           latency tracers. This option prevents the function tracer from
133           being enabled at start up.
134
135       -D
136           The option -d will try to use the function-trace option to disable
137           the function tracer (if available), otherwise it defaults to the
138           proc file: /proc/sys/kernel/ftrace_enabled, but will not touch it
139           if the function-trace option is available. The -D option will
140           disable both the ftrace_enabled proc file as well as the
141           function-trace option if it exists.
142
143               Note, this disable function tracing for all users, which includes users
144               outside of ftrace tracers (stack_tracer, perf, etc).
145
146       -O option
147           Ftrace has various options that can be enabled or disabled. This
148           allows you to set them. Appending the text no to an option disables
149           it. For example: "-O nograph-time" will disable the "graph-time"
150           Ftrace option.
151
152       -b size
153           This sets the ring buffer size to size kilobytes. Because the
154           Ftrace ring buffer is per CPU, this size is the size of each per
155           CPU ring buffer inside the kernel. Using "-b 10000" on a machine
156           with 4 CPUs will make Ftrace have a total buffer size of 40 Megs.
157
158       -B buffer-name
159           If the kernel supports multiple buffers, this will add a buffer
160           with the given name. If the buffer name already exists, that buffer
161           is just reset.
162
163               After a buffer name is stated, all events added after that will be
164               associated with that buffer. If no buffer is specified, or an event
165               is specified before a buffer name, it will be associated with the
166               main (toplevel) buffer.
167
168               trace-cmd set -e sched -B block -e block -B time -e timer sleep 1
169
170               The above is will enable all sched events in the main buffer. It will
171               then create a 'block' buffer instance and enable all block events within
172               that buffer. A 'time' buffer instance is created and all timer events
173               will be enabled for that event.
174
175       -m size
176           The max size in kilobytes that a per cpu buffer should be. Note,
177           due to rounding to page size, the number may not be totally
178           correct. Also, this is performed by switching between two buffers
179           that are half the given size thus the output may not be of the
180           given size even if much more was written.
181
182               Use this to prevent running out of diskspace for long runs.
183
184       -M cpumask
185           Set the cpumask for to trace. It only affects the last buffer
186           instance given. If supplied before any buffer instance, then it
187           affects the main buffer. The value supplied must be a hex number.
188
189               trace-cmd set -p function -M c -B events13 -e all -M 5
190
191               If the -M is left out, then the mask stays the same. To enable all
192               CPUs, pass in a value of '-1'.
193
194       -i
195           By default, if an event is listed that trace-cmd does not find, it
196           will exit with an error. This option will just ignore events that
197           are listed on the command line but are not found on the system.
198
199       -q | --quiet
200           Suppresses normal output, except for errors.
201
202       --max-graph-depth depth
203           Set the maximum depth the function_graph tracer will trace into a
204           function. A value of one will only show where userspace enters the
205           kernel but not any functions called in the kernel. The default is
206           zero, which means no limit.
207
208       --cmdlines-size size
209           Set the number of entries the kernel tracing file "saved_cmdlines"
210           can contain. This file is a circular buffer which stores the
211           mapping between cmdlines and PIDs. If full, it leads to unresolved
212           cmdlines ("<...>") within the trace. The kernel default value is
213           128.
214
215       --module module
216           Filter a module’s name in function tracing. It is equivalent to
217           adding :mod:module after all other functions being filtered. If no
218           other function filter is listed, then all modules functions will be
219           filtered in the filter.
220
221               '--module snd'  is equivalent to  '-l :mod:snd'
222
223               '--module snd -l "*jack*"' is equivalent to '-l "*jack*:mod:snd"'
224
225               '--module snd -n "*"' is equivalent to '-n :mod:snd'
226
227       --stderr
228           Have output go to stderr instead of stdout, but the output of the
229           command executed will not be changed. This is useful if you want to
230           monitor the output of the command being executed, but not see the
231           output from trace-cmd.
232
233       --fork
234           If a command is listed, then trace-cmd will wait for that command
235           to finish, unless the --fork option is specified. Then it will fork
236           the command and return immediately.
237

EXAMPLES

239       Enable all events for tracing:
240
241            # trace-cmd set -e all
242
243       Set the function tracer:
244
245            # trace-cmd set -p function
246

SEE ALSO

248       trace-cmd(1), trace-cmd-report(1), trace-cmd-start(1),
249       trace-cmd-stop(1), trace-cmd-extract(1), trace-cmd-reset(1),
250       trace-cmd-split(1), trace-cmd-list(1), trace-cmd-listen(1),
251       trace-cmd-profile(1)
252

AUTHOR

254       Written by Tzvetomir Stoyanov (VMware) <tz.stoyanov@gmail.com[1]>
255

RESOURCES

257       https://git.kernel.org/pub/scm/utils/trace-cmd/trace-cmd.git/
258

COPYING

260       Copyright (C) 2010 Red Hat, Inc. Free use of this software is granted
261       under the terms of the GNU Public License (GPL).
262

NOTES

264        1. tz.stoyanov@gmail.com
265           mailto:tz.stoyanov@gmail.com
266
267
268
269                                  03/29/2021                  TRACE-CMD-SET(1)
Impressum