7 lttng-create - Create an LTTng tracing session
15 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *create* [option:--shm-path='PATH']
16 [option:--no-output | option:--output='PATH' | option:--set-url=file://'PATH'] ['SESSION']
18 Network streaming mode:
21 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *create* [option:--shm-path='PATH']
22 (option:--set-url='URL' | option:--ctrl-url='URL' option:--data-url='URL') ['SESSION']
27 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *create* option:--snapshot [option:--shm-path='PATH']
28 [option:--set-url='URL' | option:--ctrl-url='URL' option:--data-url='URL'] ['SESSION']
33 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *create* option:--live[='DELAYUS'] [option:--shm-path='PATH']
34 [option:--set-url='URL' | option:--ctrl-url='URL' option:--data-url='URL'] ['SESSION']
39 The `lttng create` command creates a new tracing session.
41 A tracing session is a named container of channels, which in turn
42 contain event rules. It is domain-agnostic, in that channels and event
43 rules can be enabled for the user space tracer and/or the Linux
46 On execution, an `.lttngrc` file is created, if it does not exist, in the
47 user's home directory. This file contains the name of the current tracing
48 session. When creating a new tracing session with `lttng create`, the
49 current tracing session is set to this new tracing session. The
50 man:lttng-set-session(1) command can be used to set the current
51 tracing session without manually editing the `.lttngrc` file.
53 If 'SESSION' is omitted, a session name is automatically created having
54 this form: `auto-YYYYmmdd-HHMMSS`. 'SESSION' *must not* contain the
57 The option:--shm-path option can be used to specify the path to the
58 shared memory holding the ring buffers. Specifying a location on an
59 NVRAM file system makes it possible to retrieve the latest recorded
60 trace data when the system reboots after a crash. To view the events
61 of ring buffer files after a system crash, use the
62 man:lttng-crash(1) utility.
64 Tracing sessions are destroyed using the man:lttng-destroy(1)
70 There are four tracing session modes:
73 Traces the local system and writes the trace to the local
74 file system. The option:--output option specifies the trace path.
75 Using option:--set-url=file://'PATH' is the equivalent of using
76 option:--output='PATH'. The file system output can be disabled using
77 the option:--no-output option.
79 If none of the options mentioned above are used, then the trace is
80 written locally in the `$LTTNG_HOME/lttng-traces` directory
81 (`$LTTNG_HOME` defaults to `$HOME`).
83 Network streaming mode::
84 Traces the local system and sends the trace over the network to
85 a listening relay daemon (see man:lttng-relayd(8)).
86 The option:--set-url, or option:--ctrl-url and option:--data-url
87 options set the trace output destination (see the
88 <<url-format,URL format>> section below).
91 Traces the local system without writing the trace to the local file
92 system (implicit option:--no-output option). Channels are automatically
93 configured to be snapshot-ready on creation (see
94 man:lttng-enable-channel(1)). The man:lttng-snapshot(1)
95 command is used to take snapshots of the current ring buffers.
96 The option:--set-url, or option:--ctrl-url and option:--data-url
97 options set the default snapshot output destination.
100 Traces the local system, sending trace data to an LTTng relay daemon
101 over the network (see man:lttng-relayd(8)). The
102 option:--set-url, or option:--ctrl-url and option:--data-url options
103 set the trace output destination. The live output URLs cannot use
104 the `file://` protocol (see the <<url-format,URL format>>
111 The option:--set-url, option:--ctrl-url, and option:--data-url options'
114 The format of those URLs is one of:
118 'NETPROTO'://('HOST' | 'IPADDR')[:__CTRLPORT__[:__DATAPORT__]][/'TRACEPATH']
120 The `file://` protocol targets the *local file system* and can only
121 be used as the option:--set-url option's argument in _local mode_.
124 Absolute path to trace files on the local file system.
126 The other version is used for the _network streaming mode_.
129 Network protocol, amongst:
133 TCP over IPv4; the default values of `<ctrl port>` and `<data port>`
134 are resp. 5342 and 5343.
137 TCP over IPv6: same default ports as the `net` protocol.
140 Same as the `net` protocol; can only be used with the
141 option:--ctrl-url and option:--data-url options together.
144 Same as the `net6` protocol; can only be used with the
145 option:--ctrl-url and option:--data-url options together.
148 ('HOST' | 'IPADDR')::
149 Hostname or IP address (IPv6 address *must* be enclosed in brackets
150 (`[` and `]`); see https://www.ietf.org/rfc/rfc2732.txt[RFC 2732]).
159 Path of trace files on the remote file system. This path is relative
160 to the base output directory set on the relay daemon side;
161 see man:lttng-relayd(8).
164 include::common-cmd-options-head.txt[]
169 option:--live[='DELAYUS']::
170 Create the session in live mode. The optional 'DELAYUS' parameter,
171 given in microseconds, is the maximum time the user can wait for
172 the data to be flushed. This mode can be set with a network URL
173 (options option:--set-url, or option:--ctrl-url and option:--data-url)
174 and must have a relay daemon listening (see man:lttng-relayd(8)).
176 By default, 'DELAYUS' is {default_lttng_live_timer} and the network URL
177 is set to `net://127.0.0.1`.
180 Create the session in snapshot mode. This is the equivalent of using
181 the option:--no-output option and creating all the channels of this
182 new tracing session in overwrite mode with an `mmap` output type.
188 Do not output any trace data.
190 option:-o, option:--output='PATH'::
191 Set trace output path to 'PATH'.
193 option:--shm-path='PATH'::
194 Create shared memory holding buffers at 'PATH'.
199 See the <<url-format,URL format>> section above for more information
200 about the syntax of the following options' 'URL' argument.
202 option:-C, option:--ctrl-url='URL'::
203 Set control path URL to 'URL' (must use option:--data-url option
206 option:-D, option:--data-url='URL'::
207 Set data path URL to 'URL' (must use option:--ctrl-url option
210 option:-U, option:--set-url='URL'::
211 Set URL destination of the trace data to 'URL'. It is persistent for
212 the session lifetime. This option sets both data
213 (option:--data-url option) and control (option:--ctrl-url option)
214 URLs at the same time.
217 include::common-cmd-help-options.txt[]
220 include::common-cmd-footer.txt[]
225 man:lttng-destroy(1),
226 man:lttng-set-session(1),