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:
20 lttng [GENERAL OPTIONS] create [SESSION] --snapshot
22 [--shm-path=PATH] [--set-url=URL | --ctrl-url=URL --data-url=URL]
23 Live mode:
25 lttng [GENERAL OPTIONS] create [SESSION] --live[=DELAYUS]
27 [--shm-path=PATH] [--set-url=URL | --ctrl-url=URL --data-url=URL]
28
30 The lttng create command creates a new tracing session.
31 A tracing session is a named container of channels, which in turn
33 contain event rules. It is domain-agnostic, in that channels and event
34 rules can be enabled for the user space tracer and/or the Linux kernel
35 tracer.
36 On execution, an .lttngrc file is created, if it does not exist, in the
38 user’s home directory. This file contains the name of the current
39 tracing session. When creating a new tracing session with lttng create,
40 the current tracing session is set to this new tracing session. The
41 lttng-set-session(1) command can be used to set the current tracing
42 session without manually editing the .lttngrc file.
43 If SESSION is omitted, a session name is automatically created having
45 this form: auto-YYYYmmdd-HHMMSS. SESSION must not contain the character
46 /.
47 The --shm-path option can be used to specify the path to the shared
49 memory holding the ring buffers. Specifying a location on an NVRAM file
50 system makes it possible to retrieve the latest recorded trace data
51 when the system reboots after a crash. To view the events of ring
52 buffer files after a system crash, use the lttng-crash(1) utility.
53 Tracing sessions are destroyed using the lttng-destroy(1) command.
55 Creation modes
57 There are four tracing session modes:
58 Local mode
60 Traces the local system and writes the trace to the local file
61 system. The --output option specifies the trace path. Using --set-
62 url=file://PATH is the equivalent of using --output=PATH. The file
63 system output can be disabled using the --no-output option.
64 If none of the options mentioned above are used, then the trace is
66 written locally in the $LTTNG_HOME/lttng-traces directory
67 ($LTTNG_HOME defaults to $HOME).
68 Network streaming mode
70 Traces the local system and sends the trace over the network to a
71 listening relay daemon (see lttng-relayd(8)). The --set-url, or
72 --ctrl-url and --data-url options set the trace output destination
73 (see the URL format section below).
74 Snapshot mode
76 Traces the local system without writing the trace to the local file
77 system (implicit --no-output option). Channels are automatically
78 configured to be snapshot-ready on creation (see lttng-enable-
79 channel(1)). The lttng-snapshot(1) command is used to take
80 snapshots of the current ring buffers. The --set-url, or --ctrl-url
81 and --data-url options set the default snapshot output destination.
82 Live mode
84 Traces the local system, sending trace data to an LTTng relay
85 daemon over the network (see lttng-relayd(8)). The --set-url, or
86 --ctrl-url and --data-url options set the trace output destination.
87 The live output URLs cannot use the file:// protocol (see the URL
88 format section below).
89 URL format
91 The --set-url, --ctrl-url, and --data-url options' arguments are URLs.
92 The format of those URLs is one of:
94 file://TRACEPATH
96 NETPROTO://(HOST | IPADDR)[:CTRLPORT[:DATAPORT]][/TRACEPATH]
97 The file:// protocol targets the local file system and can only be used
99 as the --set-url option’s argument when the session is created in local
100 or snapshot mode.
101 TRACEPATH
103 Absolute path to trace files on the local file system.
104 The other version is available when the session is created in network
106 streaming, snapshot, or live mode.
107 NETPROTO
109 Network protocol, amongst:
110 net
112 TCP over IPv4; the default values of CTRLPORT and DATAPORT are
113 respectively 5342 and 5343.
114 net6
116 TCP over IPv6: same default ports as the net protocol.
117 tcp
119 Same as the net protocol; can only be used with the --ctrl-url
120 and --data-url options together.
121 tcp6
123 Same as the net6 protocol; can only be used with the --ctrl-url
124 and --data-url options together.
125 (HOST | IPADDR)
127 Hostname or IP address (IPv6 address must be enclosed in brackets
128 ([ and ]); see RFC 2732 <https://www.ietf.org/rfc/rfc2732.txt>).
129 CTRLPORT
131 Control port.
132 DATAPORT
134 Data port.
135 TRACEPATH
137 Path of trace files on the remote file system. This path is
138 relative to the base output directory set on the relay daemon side;
139 see lttng-relayd(8).
140
142 General options are described in lttng(1).
143 Mode selection
145 --live[=DELAYUS]
146 Create the session in live mode.
147 The optional DELAYUS parameter, given in microseconds, is the
149 maximum time the user can wait for the data to be flushed. This
150 mode can be set with a network URL (options --set-url, or --ctrl-
151 url and --data-url) and must have a relay daemon listening (see
152 lttng-relayd(8)).
153 By default, DELAYUS is 1000000 and the network URL is set to
155 net://127.0.0.1.
156 --snapshot
158 Create the session in snapshot mode. This is the equivalent of
159 using the --no-output option and creating all the channels of this
160 new tracing session in overwrite mode with an mmap output type.
161 Output
163 --no-output
164 In local mode, do not output any trace data.
165 -o PATH, --output=PATH
167 In local mode, set trace output path to PATH.
168 --shm-path=PATH
170 Create shared memory holding buffers at PATH.
171 URL
173 See the URL format section above for more information about the syntax
174 of the following options' URL argument.
175 -C URL, --ctrl-url=URL
177 Set control path URL to URL (must use --data-url option also).
178 -D URL, --data-url=URL
180 Set data path URL to URL (must use --ctrl-url option also).
181 -U URL, --set-url=URL
183 Set URL destination of the trace data to URL. It is persistent for
184 the session lifetime. This option sets both data (--data-url
185 option) and control (--ctrl-url option) URLs at the same time.
186 In local mode, URL must start with file:// followed by the
188 destination path on the local file system.
189 Program information
191 -h, --help
192 Show command help.
193 This option, like lttng-help(1), attempts to launch /usr/bin/man to
195 view the command’s man page. The path to the man pager can be
196 overridden by the LTTNG_MAN_BIN_PATH environment variable.
197 --list-options
199 List available command options.
200
202 LTTNG_ABORT_ON_ERROR
203 Set to 1 to abort the process after the first error is encountered.
204 LTTNG_HOME
206 Overrides the $HOME environment variable. Useful when the user
207 running the commands has a non-writable home directory.
208 LTTNG_MAN_BIN_PATH
210 Absolute path to the man pager to use for viewing help information
211 about LTTng commands (using lttng-help(1) or lttng COMMAND --help).
212 LTTNG_SESSION_CONFIG_XSD_PATH
214 Path in which the session.xsd session configuration XML schema may
215 be found.
216 LTTNG_SESSIOND_PATH
218 Full session daemon binary path.
219 The --sessiond-path option has precedence over this environment
221 variable.
222 Note that the lttng-create(1) command can spawn an LTTng session daemon
224 automatically if none is running. See lttng-sessiond(8) for the
225 environment variables influencing the execution of the session daemon.
226
228 $LTTNG_HOME/.lttngrc
229 User LTTng runtime configuration.
230 This is where the per-user current tracing session is stored
232 between executions of lttng(1). The current tracing session can be
233 set with lttng-set-session(1). See lttng-create(1) for more
234 information about tracing sessions.
235 $LTTNG_HOME/lttng-traces
237 Default output directory of LTTng traces. This can be overridden
238 with the --output option of the lttng-create(1) command.
239 $LTTNG_HOME/.lttng
241 User LTTng runtime and configuration directory.
242 $LTTNG_HOME/.lttng/sessions
244 Default location of saved user tracing sessions (see lttng-save(1)
245 and lttng-load(1)).
246 /usr/local/etc/lttng/sessions
248 System-wide location of saved tracing sessions (see lttng-save(1)
249 and lttng-load(1)).
250 Note
252 $LTTNG_HOME defaults to $HOME when not explicitly set.
253
255 0
256 Success
257 1
259 Command error
260 2
262 Undefined command
263 3
265 Fatal error
266 4
268 Command warning (something went wrong during the command)
269
271 If you encounter any issue or usability problem, please report it on
272 the LTTng bug tracker <https://bugs.lttng.org/projects/lttng-tools>.
273
275 • LTTng project website <https://lttng.org>
276 • LTTng documentation <https://lttng.org/docs>
278 • Git repositories <http://git.lttng.org>
280 • GitHub organization <http://github.com/lttng>
282 • Continuous integration <http://ci.lttng.org/>
284 • Mailing list <http://lists.lttng.org> for support and development:
286 lttng-dev@lists.lttng.org
287 • IRC channel <irc://irc.oftc.net/lttng>: #lttng on irc.oftc.net
289
291 This program is part of the LTTng-tools project.
292 LTTng-tools is distributed under the GNU General Public License version
294 2 <http://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html>. See the
295 LICENSE <https://github.com/lttng/lttng-tools/blob/master/LICENSE> file
296 for details.
297
299 Special thanks to Michel Dagenais and the DORSAL laboratory
300 <http://www.dorsal.polymtl.ca/> at École Polytechnique de Montréal for
301 the LTTng journey.
302 Also thanks to the Ericsson teams working on tracing which helped us
304 greatly with detailed bug reports and unusual test cases.
305
307 lttng-destroy(1), lttng-set-session(1), lttng(1)
308LTTng 2.12.4 18 January 2018 LTTNG-CREATE(1)