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