1TRACE-CMD-SET(1)               libtracefs Manual              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
67           .ft C
68               ==, >=, <=, >, <, &, |, && and ||
69           .ft
70
71
72           The above are usually safe to use to compare fields.
73
74       -R trigger
75           Specify a trigger for the previous event. This must come after a
76           -e. This will add a given trigger to the given event. To only
77           enable the trigger and not the event itself, then place the event
78           after the -v option.
79
80               See Documentation/trace/events.txt in the Linux kernel source for more
81               information on triggers.
82
83       -v
84           This will negate options specified after it on the command line. It
85           affects:
86
87                -e: Causes all specified events to not be traced. This is useful for
88                      selecting a subsystem to be traced but to leave out various events.
89                      For example: "-e sched -v -e "*stat*"" will enable all events in
90                      the sched subsystem except those that have "stat" in their names.
91                -B: Deletes the specified ftrace instance. There must be no
92                      configuration options related to this instance in the command line.
93                      For example: "-v -B bar -B foo" will delete instance bar and create
94                      a new instance foo.
95               Note: the -v option was taken from the way grep(1) inverts the following
96               matches.
97
98       -P pid
99           This will filter only the specified process IDs. Using -P will let
100           you trace only events that are caused by the process.
101
102       -c
103           Used -P to trace the process' children too (if kernel supports it).
104
105       --user
106           Execute the specified command as given user.
107
108       -C clock
109           Set the trace clock to "clock".
110
111               Use trace-cmd(1) list -C to see what clocks are available.
112
113       -l function-name
114           This will limit the function and function_graph tracers to only
115           trace the given function name. More than one -l may be specified on
116           the command line to trace more than one function. The limited use
117           of glob expressions are also allowed. These are match* to only
118           filter functions that start with match.  *match to only filter
119           functions that end with match.  *match\* to only filter on
120           functions that contain match.
121
122       -g function-name
123           This option is for the function_graph plugin. It will graph the
124           given function. That is, it will only trace the function and all
125           functions that it calls. You can have more than one -g on the
126           command line.
127
128       -n function-name
129           This has the opposite effect of -l. The function given with the -n
130           option will not be traced. This takes precedence, that is, if you
131           include the same function for both -n and -l, it will not be
132           traced.
133
134       -d
135           Some tracer plugins enable the function tracer by default. Like the
136           latency tracers. This option prevents the function tracer from
137           being enabled at start up.
138
139       -D
140           The option -d will try to use the function-trace option to disable
141           the function tracer (if available), otherwise it defaults to the
142           proc file: /proc/sys/kernel/ftrace_enabled, but will not touch it
143           if the function-trace option is available. The -D option will
144           disable both the ftrace_enabled proc file as well as the
145           function-trace option if it exists.
146
147               Note, this disable function tracing for all users, which includes users
148               outside of ftrace tracers (stack_tracer, perf, etc).
149
150       -O option
151           Ftrace has various options that can be enabled or disabled. This
152           allows you to set them. Appending the text no to an option disables
153           it. For example: "-O nograph-time" will disable the "graph-time"
154           Ftrace option.
155
156       -b size
157           This sets the ring buffer size to size kilobytes. Because the
158           Ftrace ring buffer is per CPU, this size is the size of each per
159           CPU ring buffer inside the kernel. Using "-b 10000" on a machine
160           with 4 CPUs will make Ftrace have a total buffer size of 40 Megs.
161
162       -B buffer-name
163           If the kernel supports multiple buffers, this will add a buffer
164           with the given name. If the buffer name already exists, that buffer
165           is just reset.
166
167               After a buffer name is stated, all events added after that will be
168               associated with that buffer. If no buffer is specified, or an event
169               is specified before a buffer name, it will be associated with the
170               main (toplevel) buffer.
171
172               trace-cmd set -e sched -B block -e block -B time -e timer sleep 1
173
174               The above is will enable all sched events in the main buffer. It will
175               then create a 'block' buffer instance and enable all block events within
176               that buffer. A 'time' buffer instance is created and all timer events
177               will be enabled for that event.
178
179       -m size
180           The max size in kilobytes that a per cpu buffer should be. Note,
181           due to rounding to page size, the number may not be totally
182           correct. Also, this is performed by switching between two buffers
183           that are half the given size thus the output may not be of the
184           given size even if much more was written.
185
186               Use this to prevent running out of diskspace for long runs.
187
188       -M cpumask
189           Set the cpumask for to trace. It only affects the last buffer
190           instance given. If supplied before any buffer instance, then it
191           affects the main buffer. The value supplied must be a hex number.
192
193               trace-cmd set -p function -M c -B events13 -e all -M 5
194
195               If the -M is left out, then the mask stays the same. To enable all
196               CPUs, pass in a value of '-1'.
197
198       -i
199           By default, if an event is listed that trace-cmd does not find, it
200           will exit with an error. This option will just ignore events that
201           are listed on the command line but are not found on the system.
202
203       -q | --quiet
204           Suppresses normal output, except for errors.
205
206       --max-graph-depth depth
207           Set the maximum depth the function_graph tracer will trace into a
208           function. A value of one will only show where userspace enters the
209           kernel but not any functions called in the kernel. The default is
210           zero, which means no limit.
211
212       --cmdlines-size size
213           Set the number of entries the kernel tracing file "saved_cmdlines"
214           can contain. This file is a circular buffer which stores the
215           mapping between cmdlines and PIDs. If full, it leads to unresolved
216           cmdlines ("<...>") within the trace. The kernel default value is
217           128.
218
219       --module module
220           Filter a module’s name in function tracing. It is equivalent to
221           adding :mod:module after all other functions being filtered. If no
222           other function filter is listed, then all modules functions will be
223           filtered in the filter.
224
225               '--module snd'  is equivalent to  '-l :mod:snd'
226
227               '--module snd -l "*jack*"' is equivalent to '-l "*jack*:mod:snd"'
228
229               '--module snd -n "*"' is equivalent to '-n :mod:snd'
230
231       --stderr
232           Have output go to stderr instead of stdout, but the output of the
233           command executed will not be changed. This is useful if you want to
234           monitor the output of the command being executed, but not see the
235           output from trace-cmd.
236
237       --fork
238           If a command is listed, then trace-cmd will wait for that command
239           to finish, unless the --fork option is specified. Then it will fork
240           the command and return immediately.
241
242       --verbose[=level]
243           Set the log level. Supported log levels are "none", "critical",
244           "error", "warning", "info", "debug", "all" or their identifiers
245           "0", "1", "2", "3", "4", "5", "6". Setting the log level to
246           specific value enables all logs from that and all previous levels.
247           The level will default to "info" if one is not specified.
248
249               Example: enable all critical, error and warning logs
250
251               trace-cmd set --verbose=warning
252

EXAMPLES

254       Enable all events for tracing:
255
256
257           .ft C
258            # trace-cmd set -e all
259           .ft
260
261
262       Set the function tracer:
263
264
265           .ft C
266            # trace-cmd set -p function
267           .ft
268
269

SEE ALSO

271       trace-cmd(1), trace-cmd-report(1), trace-cmd-start(1),
272       trace-cmd-stop(1), trace-cmd-extract(1), trace-cmd-reset(1),
273       trace-cmd-split(1), trace-cmd-list(1), trace-cmd-listen(1),
274       trace-cmd-profile(1)
275

AUTHOR

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

RESOURCES

280       https://git.kernel.org/pub/scm/utils/trace-cmd/trace-cmd.git/
281

COPYING

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

NOTES

287        1. tz.stoyanov@gmail.com
288           mailto:tz.stoyanov@gmail.com
289
290
291
292libtracefs                        07/23/2022                  TRACE-CMD-SET(1)
Impressum