1LTTNG-CREATE(1)                  LTTng Manual                  LTTNG-CREATE(1)
2
3
4

NAME

6       lttng-create - Create an LTTng tracing session
7

SYNOPSIS

9       Local mode:
10
11       lttng [GENERAL OPTIONS] create [SESSION] [--shm-path=PATH]
12             [--no-output | --output=PATH | --set-url=file://PATH]
13
14       Network streaming mode:
15
16       lttng [GENERAL OPTIONS] create [SESSION] [--shm-path=PATH]
17             (--set-url=URL | --ctrl-url=URL --data-url=URL)
18       Snapshot mode:
19
20       lttng [GENERAL OPTIONS] create [SESSION] --snapshot
21             [--shm-path=PATH] [--set-url=URL | --ctrl-url=URL --data-url=URL]
22
23       Live mode:
24
25       lttng [GENERAL OPTIONS] create [SESSION] --live[=DELAYUS]
26             [--shm-path=PATH] [--set-url=URL | --ctrl-url=URL --data-url=URL]
27

DESCRIPTION

29       The lttng create command creates a new tracing session.
30
31       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
36       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
43       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
47       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
53       Tracing sessions are destroyed using the lttng-destroy(1) command.
54
55   Creation modes
56       There are four tracing session modes:
57
58       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
64           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
68       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
74       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
82       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
89   URL format
90       The --set-url, --ctrl-url, and --data-url options' arguments are URLs.
91
92       The format of those URLs is one of:
93
94           file://TRACEPATH
95           NETPROTO://(HOST | IPADDR)[:CTRLPORT[:DATAPORT]][/TRACEPATH]
96
97       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
101       TRACEPATH
102           Absolute path to trace files on the local file system.
103
104       The other version is available when the session is created in network
105       streaming, snapshot, or live mode.
106
107       NETPROTO
108           Network protocol, amongst:
109
110           net
111               TCP over IPv4; the default values of CTRLPORT and DATAPORT are
112               respectively 5342 and 5343.
113
114           net6
115               TCP over IPv6: same default ports as the net protocol.
116
117           tcp
118               Same as the net protocol; can only be used with the --ctrl-url
119               and --data-url options together.
120
121           tcp6
122               Same as the net6 protocol; can only be used with the --ctrl-url
123               and --data-url options together.
124
125       (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
129       CTRLPORT
130           Control port.
131
132       DATAPORT
133           Data port.
134
135       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

OPTIONS

141       General options are described in lttng(1).
142
143   Mode selection
144       --live[=DELAYUS]
145           Create the session in live mode.
146
147           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
153           By default, DELAYUS is 1000000 and the network URL is set to
154           net://127.0.0.1.
155
156       --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
161   Output
162       --no-output
163           In local mode, do not output any trace data.
164
165       -o PATH, --output=PATH
166           In local mode, set trace output path to PATH.
167
168       --shm-path=PATH
169           Create shared memory holding buffers at PATH.
170
171   URL
172       See the URL format section above for more information about the syntax
173       of the following options' URL argument.
174
175       -C URL, --ctrl-url=URL
176           Set control path URL to URL (must use --data-url option also).
177
178       -D URL, --data-url=URL
179           Set data path URL to URL (must use --ctrl-url option also).
180
181       -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
186           In local mode, URL must start with file:// followed by the
187           destination path on the local file system.
188
189   Program information
190       -h, --help
191           Show command help.
192
193           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
197       --list-options
198           List available command options.
199

ENVIRONMENT VARIABLES

201       LTTNG_ABORT_ON_ERROR
202           Set to 1 to abort the process after the first error is encountered.
203
204       LTTNG_HOME
205           Overrides the $HOME environment variable. Useful when the user
206           running the commands has a non-writable home directory.
207
208       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
212       LTTNG_SESSION_CONFIG_XSD_PATH
213           Path in which the session.xsd session configuration XML schema may
214           be found.
215
216       LTTNG_SESSIOND_PATH
217           Full session daemon binary path.
218
219           The --sessiond-path option has precedence over this environment
220           variable.
221
222       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

FILES

227       $LTTNG_HOME/.lttngrc
228           User LTTng runtime configuration.
229
230           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
235       $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
239       $LTTNG_HOME/.lttng
240           User LTTng runtime and configuration directory.
241
242       $LTTNG_HOME/.lttng/sessions
243           Default location of saved user tracing sessions (see lttng-save(1)
244           and lttng-load(1)).
245
246       /usr/local/etc/lttng/sessions
247           System-wide location of saved tracing sessions (see lttng-save(1)
248           and lttng-load(1)).
249
250           Note
251           $LTTNG_HOME defaults to $HOME when not explicitly set.
252

EXIT STATUS

254       0
255           Success
256
257       1
258           Command error
259
260       2
261           Undefined command
262
263       3
264           Fatal error
265
266       4
267           Command warning (something went wrong during the command)
268

BUGS

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

RESOURCES

274       ·   LTTng project website <http://lttng.org>
275
276       ·   LTTng documentation <http://lttng.org/docs>
277
278       ·   Git repositories <http://git.lttng.org>
279
280       ·   GitHub organization <http://github.com/lttng>
281
282       ·   Continuous integration <http://ci.lttng.org/>
283
284       ·   Mailing list <http://lists.lttng.org> for support and development:
285           lttng-dev@lists.lttng.org
286
287       ·   IRC channel <irc://irc.oftc.net/lttng>: #lttng on irc.oftc.net
288

COPYRIGHTS

290       This program is part of the LTTng-tools project.
291
292       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

THANKS

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
302       Also thanks to the Ericsson teams working on tracing which helped us
303       greatly with detailed bug reports and unusual test cases.
304

AUTHORS

306       LTTng-tools was originally written by Mathieu Desnoyers, Julien
307       Desfossez, and David Goulet. More people have since contributed to it.
308
309       LTTng-tools is currently maintained by Jérémie Galarneau
310       <mailto:jeremie.galarneau@efficios.com>.
311

SEE ALSO

313       lttng-destroy(1), lttng-set-session(1), lttng(1)
314
315
316
317LTTng 2.10.7                      05/24/2019                   LTTNG-CREATE(1)
Impressum