lttng-create(1): add relay mode
[lttng-tools.git] / doc / man / lttng-create.1.txt
CommitLineData
ba50d967
PP
1lttng-create(1)
2===============
3
4
5NAME
6----
7lttng-create - Create an LTTng tracing session
8
9
10SYNOPSIS
11--------
f87c4756 12Local mode:
ba50d967
PP
13
14[verse]
f87c4756
PP
15*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *create* [option:--shm-path='PATH']
16 [option:--no-output | option:--output='PATH' | option:--set-url=file://'PATH'] ['SESSION']
17
18Network streaming mode:
19
20[verse]
21*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *create* [option:--shm-path='PATH']
22 (option:--set-url='URL' | option:--ctrl-url='URL' option:--data-url='URL') ['SESSION']
ba50d967
PP
23
24Snapshot mode:
25
26[verse]
f87c4756
PP
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']
ba50d967
PP
29
30Live mode:
31
32[verse]
f87c4756
PP
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']
ba50d967
PP
35
36
37DESCRIPTION
38-----------
39The `lttng create` command creates a new tracing session.
40
41A tracing session is a named container of channels, which in turn
42contain event rules. It is domain-agnostic, in that channels and event
43rules can be enabled for the user space tracer and/or the Linux
44kernel tracer.
45
46On execution, an `.lttngrc` file is created, if it does not exist, in the
47user's home directory. This file contains the name of the current tracing
48session. When creating a new tracing session with `lttng create`, the
49current tracing session is set to this new tracing session. The
7c1a4458 50man:lttng-set-session(1) command can be used to set the current
ba50d967
PP
51tracing session without manually editing the `.lttngrc` file.
52
53If 'SESSION' is omitted, a session name is automatically created having
54this form: `auto-YYYYmmdd-HHMMSS`. 'SESSION' *must not* contain the
55character `/`.
56
57The option:--shm-path option can be used to specify the path to the
58shared memory holding the ring buffers. Specifying a location on an
59NVRAM file system makes it possible to retrieve the latest recorded
60trace data when the system reboots after a crash. To view the events
61of ring buffer files after a system crash, use the
7c1a4458 62man:lttng-crash(1) utility.
ba50d967 63
7c1a4458 64Tracing sessions are destroyed using the man:lttng-destroy(1)
ba50d967
PP
65command.
66
67
68Creation modes
69~~~~~~~~~~~~~~
f87c4756 70There are four tracing session modes:
ba50d967 71
f87c4756 72Local mode::
ba50d967
PP
73 Traces the local system and writes the trace to the local
74 file system. The option:--output option specifies the trace path.
f87c4756
PP
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.
78+
79If none of the options mentioned above are used, then the trace is
80written locally in the `$LTTNG_HOME/lttng-traces` directory
81(`$LTTNG_HOME` defaults to `$HOME`).
82
83Network 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).
ba50d967
PP
89
90Snapshot mode::
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
7c1a4458 94 man:lttng-enable-channel(1)). The man:lttng-snapshot(1)
ba50d967
PP
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.
98
99Live mode::
100 Traces the local system, sending trace data to an LTTng relay daemon
7c1a4458 101 over the network (see man:lttng-relayd(8)). The
ba50d967
PP
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
f87c4756
PP
104 the `file://` protocol (see the <<url-format,URL format>>
105 section below).
ba50d967
PP
106
107
108[[url-format]]
109URL format
110~~~~~~~~~~
f87c4756
PP
111The option:--set-url, option:--ctrl-url, and option:--data-url options'
112arguments are URLs.
ba50d967
PP
113
114The format of those URLs is one of:
115
116[verse]
117file://'TRACEPATH'
118'NETPROTO'://('HOST' | 'IPADDR')[:__CTRLPORT__[:__DATAPORT__]][/'TRACEPATH']
119
f87c4756
PP
120The `file://` protocol targets the *local file system* and can only
121be used as the option:--set-url option's argument in _local mode_.
ba50d967
PP
122
123'TRACEPATH'::
124 Absolute path to trace files on the local file system.
125
f87c4756 126The other version is used for the _network streaming mode_.
ba50d967
PP
127
128'NETPROTO'::
129 Network protocol, amongst:
130+
131* `net`: TCP over IPv4; the default values of `<ctrl port>` and
132 `<data port>` are resp. 5342 and 5343
133* `net6`: TCP over IPv6: same default ports as `net` protocol
134* `tcp`: same as `net` protocol; can only be used with the
135 option:--ctrl-url and option:--data-url options together
136* `tcp6`: same as `net6` protocol; can only be used with the
137 option:--ctrl-url and option:--data-url options together
138
139('HOST' | 'IPADDR')::
140 Hostname or IP address (IPv6 address *must* be enclosed in brackets
141 (`[` and `]`); see https://www.ietf.org/rfc/rfc2732.txt[RFC 2732]).
142
143'CTRLPORT'::
144 Control port.
145
146'DATAPORT'::
147 Data port.
148
149'TRACEPATH'::
150 Path of trace files on the remote file system. This path is relative
151 to the base output directory set on the relay daemon side;
7c1a4458 152 see man:lttng-relayd(8).
ba50d967
PP
153
154
155include::common-cmd-options-head.txt[]
156
157
f87c4756
PP
158Mode selection
159~~~~~~~~~~~~~~
ba50d967
PP
160option:--live[='DELAYUS']::
161 Create the session in live mode. The optional 'DELAYUS' parameter,
162 given in microseconds, is the maximum time the user can wait for
163 the data to be flushed. This mode can be set with a network URL
164 (options option:--set-url, or option:--ctrl-url and option:--data-url)
7c1a4458 165 and must have a relay daemon listening (see man:lttng-relayd(8)).
ba50d967 166+
c93eadad
PP
167By default, 'DELAYUS' is {default_lttng_live_timer} and the network URL
168is set to `net://127.0.0.1`.
ba50d967
PP
169
170option:--snapshot::
171 Create the session in snapshot mode. This is the equivalent of using
172 the option:--no-output option and creating all the channels of this
173 new tracing session in overwrite mode with an `mmap` output type.
174
175
176Output
177~~~~~~
178option:--no-output::
179 Do not output any trace data.
180
181option:-o, option:--output='PATH'::
182 Set trace output path to 'PATH'.
183
184option:--shm-path='PATH'::
185 Create shared memory holding buffers at 'PATH'.
186
187
188URL
189~~~
190See the <<url-format,URL format>> section above for more information
191about the syntax of the following options' 'URL' argument.
192
193option:-C, option:--ctrl-url='URL'::
194 Set control path URL to 'URL' (must use option:--data-url option
195 also).
196
197option:-D, option:--data-url='URL'::
198 Set data path URL to 'URL' (must use option:--ctrl-url option
199 also).
200
201option:-U, option:--set-url='URL'::
202 Set URL destination of the trace data to 'URL'. It is persistent for
203 the session lifetime. This option sets both data
204 (option:--data-url option) and control (option:--ctrl-url option)
205 URLs at the same time.
206
207
208include::common-cmd-help-options.txt[]
209
210
211include::common-cmd-footer.txt[]
212
213
214SEE ALSO
215--------
7c1a4458
PP
216man:lttng-destroy(1),
217man:lttng-set-session(1),
218man:lttng(1)
This page took 0.044118 seconds and 4 git commands to generate.