1LTTNG-CREATE(1) LTTng Manual LTTNG-CREATE(1)
2
6 lttng-create - Create an LTTng tracing session
7
9 Local mode:
10 lttng [GENERAL OPTIONS] create [SESSION] [--shm-path=PATH]
12 [--no-output | --output=PATH | --set-url=file://PATH]
13 Network streaming mode:
15 lttng [GENERAL OPTIONS] create [SESSION] [--shm-path=PATH]
17 (--set-url=URL | --ctrl-url=URL --data-url=URL)
18 Snapshot mode:
19 lttng [GENERAL OPTIONS] create [SESSION] --snapshot
21 [--shm-path=PATH] [--set-url=URL | --ctrl-url=URL --data-url=URL]
22 Live mode:
24 lttng [GENERAL OPTIONS] create [SESSION] --live[=DELAYUS]
26 [--shm-path=PATH] [--set-url=URL | --ctrl-url=URL --data-url=URL]
27
29 The lttng create command creates a new tracing session.
30 A tracing session is a named container of channels, which in turn
32 contain event rules. It is domain-agnostic, in that channels and event
33 rules can be enabled for the user space tracer and/or the Linux kernel
34 tracer.
35 On execution, an .lttngrc file is created, if it does not exist, in the
37 user’s home directory. This file contains the name of the current
38 tracing session. When creating a new tracing session with lttng create,
39 the current tracing session is set to this new tracing session. The
40 lttng-set-session(1) command can be used to set the current tracing
41 session without manually editing the .lttngrc file.
42 If SESSION is omitted, a session name is automatically created having
44 this form: auto-YYYYmmdd-HHMMSS. SESSION must not contain the character
45 /.
46 The --shm-path option can be used to specify the path to the shared
48 memory holding the ring buffers. Specifying a location on an NVRAM file
49 system makes it possible to retrieve the latest recorded trace data
50 when the system reboots after a crash. To view the events of ring
51 buffer files after a system crash, use the lttng-crash(1) utility.
52 Tracing sessions are destroyed using the lttng-destroy(1) command.
54 Creation modes
56 There are four tracing session modes:
57 Local mode
59 Traces the local system and writes the trace to the local file
60 system. The --output option specifies the trace path. Using --set-
61 url=file://PATH is the equivalent of using --output=PATH. The file
62 system output can be disabled using the --no-output option.
63 If none of the options mentioned above are used, then the trace is
65 written locally in the $LTTNG_HOME/lttng-traces directory
66 ($LTTNG_HOME defaults to $HOME).
67 Network streaming mode
69 Traces the local system and sends the trace over the network to a
70 listening relay daemon (see lttng-relayd(8)). The --set-url, or
71 --ctrl-url and --data-url options set the trace output destination
72 (see the URL format section below).
73 Snapshot mode
75 Traces the local system without writing the trace to the local file
76 system (implicit --no-output option). Channels are automatically
77 configured to be snapshot-ready on creation (see lttng-enable-
78 channel(1)). The lttng-snapshot(1) command is used to take
79 snapshots of the current ring buffers. The --set-url, or --ctrl-url
80 and --data-url options set the default snapshot output destination.
81 Live mode
83 Traces the local system, sending trace data to an LTTng relay
84 daemon over the network (see lttng-relayd(8)). The --set-url, or
85 --ctrl-url and --data-url options set the trace output destination.
86 The live output URLs cannot use the file:// protocol (see the URL
87 format section below).
88 URL format
90 The --set-url, --ctrl-url, and --data-url options' arguments are URLs.
91 The format of those URLs is one of:
93 file://TRACEPATH
95 NETPROTO://(HOST | IPADDR)[:CTRLPORT[:DATAPORT]][/TRACEPATH]
96 The file:// protocol targets the local file system and can only be used
98 as the --set-url option’s argument when the session is created in local
99 or snapshot mode.
100 TRACEPATH
102 Absolute path to trace files on the local file system.
103 The other version is available when the session is created in network
105 streaming, snapshot, or live mode.
106 NETPROTO
108 Network protocol, amongst:
109 net
111 TCP over IPv4; the default values of CTRLPORT and DATAPORT are
112 respectively 5342 and 5343.
113 net6
115 TCP over IPv6: same default ports as the net protocol.
116 tcp
118 Same as the net protocol; can only be used with the --ctrl-url
119 and --data-url options together.
120 tcp6
122 Same as the net6 protocol; can only be used with the --ctrl-url
123 and --data-url options together.
124 (HOST | IPADDR)
126 Hostname or IP address (IPv6 address must be enclosed in brackets
127 ([ and ]); see RFC 2732 <https://www.ietf.org/rfc/rfc2732.txt>).
128 CTRLPORT
130 Control port.
131 DATAPORT
133 Data port.
134 TRACEPATH
136 Path of trace files on the remote file system. This path is
137 relative to the base output directory set on the relay daemon side;
138 see lttng-relayd(8).
139
141 General options are described in lttng(1).
142 Mode selection
144 --live[=DELAYUS]
145 Create the session in live mode.
146 The optional DELAYUS parameter, given in microseconds, is the
148 maximum time the user can wait for the data to be flushed. This
149 mode can be set with a network URL (options --set-url, or --ctrl-
150 url and --data-url) and must have a relay daemon listening (see
151 lttng-relayd(8)).
152 By default, DELAYUS is 1000000 and the network URL is set to
154 net://127.0.0.1.
155 --snapshot
157 Create the session in snapshot mode. This is the equivalent of
158 using the --no-output option and creating all the channels of this
159 new tracing session in overwrite mode with an mmap output type.
160 Output
162 --no-output
163 In local mode, do not output any trace data.
164 -o PATH, --output=PATH
166 In local mode, set trace output path to PATH.
167 --shm-path=PATH
169 Create shared memory holding buffers at PATH.
170 URL
172 See the URL format section above for more information about the syntax
173 of the following options' URL argument.
174 -C URL, --ctrl-url=URL
176 Set control path URL to URL (must use --data-url option also).
177 -D URL, --data-url=URL
179 Set data path URL to URL (must use --ctrl-url option also).
180 -U URL, --set-url=URL
182 Set URL destination of the trace data to URL. It is persistent for
183 the session lifetime. This option sets both data (--data-url
184 option) and control (--ctrl-url option) URLs at the same time.
185 In local mode, URL must start with file:// followed by the
187 destination path on the local file system.
188 Program information
190 -h, --help
191 Show command help.
192 This option, like lttng-help(1), attempts to launch /usr/bin/man to
194 view the command’s man page. The path to the man pager can be
195 overridden by the LTTNG_MAN_BIN_PATH environment variable.
196 --list-options
198 List available command options.
199
201 LTTNG_ABORT_ON_ERROR
202 Set to 1 to abort the process after the first error is encountered.
203 LTTNG_HOME
205 Overrides the $HOME environment variable. Useful when the user
206 running the commands has a non-writable home directory.
207 LTTNG_MAN_BIN_PATH
209 Absolute path to the man pager to use for viewing help information
210 about LTTng commands (using lttng-help(1) or lttng COMMAND --help).
211 LTTNG_SESSION_CONFIG_XSD_PATH
213 Path in which the session.xsd session configuration XML schema may
214 be found.
215 LTTNG_SESSIOND_PATH
217 Full session daemon binary path.
218 The --sessiond-path option has precedence over this environment
220 variable.
221 Note that the lttng-create(1) command can spawn an LTTng session daemon
223 automatically if none is running. See lttng-sessiond(8) for the
224 environment variables influencing the execution of the session daemon.
225
227 $LTTNG_HOME/.lttngrc
228 User LTTng runtime configuration.
229 This is where the per-user current tracing session is stored
231 between executions of lttng(1). The current tracing session can be
232 set with lttng-set-session(1). See lttng-create(1) for more
233 information about tracing sessions.
234 $LTTNG_HOME/lttng-traces
236 Default output directory of LTTng traces. This can be overridden
237 with the --output option of the lttng-create(1) command.
238 $LTTNG_HOME/.lttng
240 User LTTng runtime and configuration directory.
241 $LTTNG_HOME/.lttng/sessions
243 Default location of saved user tracing sessions (see lttng-save(1)
244 and lttng-load(1)).
245 /usr/local/etc/lttng/sessions
247 System-wide location of saved tracing sessions (see lttng-save(1)
248 and lttng-load(1)).
249 Note
251 $LTTNG_HOME defaults to $HOME when not explicitly set.
252
254 0
255 Success
256 1
258 Command error
259 2
261 Undefined command
262 3
264 Fatal error
265 4
267 Command warning (something went wrong during the command)
268
270 If you encounter any issue or usability problem, please report it on
271 the LTTng bug tracker <https://bugs.lttng.org/projects/lttng-tools>.
272
274 · LTTng project website <http://lttng.org>
275 · LTTng documentation <http://lttng.org/docs>
277 · Git repositories <http://git.lttng.org>
279 · GitHub organization <http://github.com/lttng>
281 · Continuous integration <http://ci.lttng.org/>
283 · Mailing list <http://lists.lttng.org> for support and development:
285 lttng-dev@lists.lttng.org
286 · IRC channel <irc://irc.oftc.net/lttng>: #lttng on irc.oftc.net
288
290 This program is part of the LTTng-tools project.
291 LTTng-tools is distributed under the GNU General Public License version
293 2 <http://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html>. See the
294 LICENSE <https://github.com/lttng/lttng-tools/blob/master/LICENSE> file
295 for details.
296
298 Special thanks to Michel Dagenais and the DORSAL laboratory
299 <http://www.dorsal.polymtl.ca/> at École Polytechnique de Montréal for
300 the LTTng journey.
301 Also thanks to the Ericsson teams working on tracing which helped us
303 greatly with detailed bug reports and unusual test cases.
304
306 LTTng-tools was originally written by Mathieu Desnoyers, Julien
307 Desfossez, and David Goulet. More people have since contributed to it.
308 LTTng-tools is currently maintained by Jérémie Galarneau
310 <mailto:jeremie.galarneau@efficios.com>.
311
313 lttng-destroy(1), lttng-set-session(1), lttng(1)
314LTTng 2.10.7 05/24/2019 LTTNG-CREATE(1)