Commit | Line | Data |
---|---|---|
b4867b3b PP |
1 | lttng-enable-channel(1) |
2 | ======================= | |
188419c4 | 3 | :revdate: 3 May 2021 |
b4867b3b PP |
4 | |
5 | ||
6 | NAME | |
7 | ---- | |
8 | lttng-enable-channel - Create or enable LTTng channels | |
9 | ||
10 | ||
11 | SYNOPSIS | |
12 | -------- | |
13 | Create a Linux kernel channel: | |
14 | ||
15 | [verse] | |
ce19b9ed | 16 | *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-channel* option:--kernel |
188419c4 | 17 | [option:--discard | option:--overwrite] [option:--output=(**mmap** | **splice**)] |
b4867b3b PP |
18 | [option:--subbuf-size='SIZE'] [option:--num-subbuf='COUNT'] |
19 | [option:--switch-timer='PERIODUS'] [option:--read-timer='PERIODUS'] | |
188419c4 PP |
20 | [option:--monitor-timer='PERIODUS'] [option:--buffers-global] |
21 | [option:--tracefile-size='SIZE' [option:--tracefile-count='COUNT']] | |
b4867b3b PP |
22 | [option:--session='SESSION'] 'CHANNEL' |
23 | ||
24 | Create a user space channel: | |
25 | ||
26 | [verse] | |
ce19b9ed | 27 | *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-channel* option:--userspace |
188419c4 PP |
28 | [option:--overwrite | [option:--discard] option:--blocking-timeout='TIMEOUTUS'] |
29 | [option:--output=**mmap**] [option:--buffers-uid | option:--buffers-pid] | |
b4867b3b PP |
30 | [option:--subbuf-size='SIZE'] [option:--num-subbuf='COUNT'] |
31 | [option:--switch-timer='PERIODUS'] [option:--read-timer='PERIODUS'] | |
7197e9ec | 32 | [option:--monitor-timer='PERIODUS'] |
188419c4 | 33 | [option:--tracefile-size='SIZE' [option:--tracefile-count='COUNT']] |
b4867b3b PP |
34 | [option:--session='SESSION'] 'CHANNEL' |
35 | ||
188419c4 | 36 | Enable channel(s): |
b4867b3b PP |
37 | |
38 | [verse] | |
ce19b9ed | 39 | *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-channel* (option:--userspace | option:--kernel) |
b4867b3b PP |
40 | [option:--session='SESSION'] 'CHANNEL'[,'CHANNEL']... |
41 | ||
42 | ||
43 | DESCRIPTION | |
44 | ----------- | |
188419c4 | 45 | The `lttng enable-channel` command does one of: |
b4867b3b | 46 | |
188419c4 | 47 | * Create a channel named 'CHANNEL'. |
b4867b3b | 48 | |
188419c4 PP |
49 | * Enable one or more disabled channels named 'CHANNEL' |
50 | (non-option argument, comma-separated). | |
b4867b3b | 51 | |
188419c4 | 52 | See man:lttng-concepts(7) to learn more about channels. |
b4867b3b | 53 | |
188419c4 | 54 | The channel(s) to create or enable belong to: |
b4867b3b | 55 | |
188419c4 PP |
56 | With the option:--session='SESSION' option:: |
57 | The tracing session named 'SESSION'. | |
b4867b3b | 58 | |
188419c4 PP |
59 | Without the option:--session option:: |
60 | The current tracing session (see man:lttng-concepts(7) to learn more | |
61 | about the current tracing session). | |
b4867b3b | 62 | |
188419c4 PP |
63 | NOTE: The man:lttng-enable-event(1) command can automatically create a |
64 | default channel when no channel exists for the provided tracing domain. | |
b4867b3b | 65 | |
188419c4 PP |
66 | List the channels of a given tracing session with the |
67 | man:lttng-list(1) and man:lttng-status(1) commands. | |
b4867b3b | 68 | |
188419c4 PP |
69 | Disable an enabled channel with the man:lttng-disable-channel(1) |
70 | command. | |
b4867b3b | 71 | |
188419c4 PP |
72 | [IMPORTANT] |
73 | ==== | |
74 | As of LTTng{nbsp}{lttng_version}, you may :not: perform the following | |
75 | operations with the `enable-channel` command: | |
b4867b3b | 76 | |
188419c4 | 77 | * Change an attribute of an existing channel. |
b4867b3b | 78 | |
188419c4 PP |
79 | * Enable a disabled channel once its tracing session has been active |
80 | (started; see man:lttng-start(1)) at least once. | |
b4867b3b | 81 | |
188419c4 PP |
82 | * Create a channel once its tracing session has been active at least |
83 | once. | |
b4867b3b | 84 | |
188419c4 PP |
85 | * Create a user space channel with a given buffering scheme |
86 | (option:--buffers-uid or option:--buffers-pid options) and create a | |
87 | second user space channel with a different buffering scheme in the | |
88 | same tracing session. | |
89 | ==== | |
b4867b3b | 90 | |
b4867b3b | 91 | |
55e06994 | 92 | include::common-lttng-cmd-options-head.txt[] |
b4867b3b | 93 | |
b4867b3b | 94 | |
188419c4 PP |
95 | Tracing domain |
96 | ~~~~~~~~~~~~~~ | |
97 | One of: | |
b4867b3b | 98 | |
188419c4 PP |
99 | option:-k, option:--kernel:: |
100 | Create or enable channels in the Linux kernel domain. | |
b4867b3b | 101 | |
188419c4 PP |
102 | option:-u, option:--userspace:: |
103 | Create or enable channels in the user space domain. | |
980bb5fd | 104 | |
b4867b3b | 105 | |
188419c4 PP |
106 | Recording target |
107 | ~~~~~~~~~~~~~~~~ | |
108 | option:-s 'SESSION', option:--session='SESSION':: | |
109 | Create or enable channels in the tracing session named 'SESSION' | |
110 | instead of the current tracing session. | |
b4867b3b PP |
111 | |
112 | ||
188419c4 PP |
113 | Buffering scheme |
114 | ~~~~~~~~~~~~~~~~ | |
b4867b3b PP |
115 | One of: |
116 | ||
188419c4 PP |
117 | option:--buffers-global:: |
118 | Allocate a single set of ring buffers for the whole system. | |
119 | + | |
120 | Only available with the option:--kernel option. | |
121 | + | |
122 | As of LTTng{nbsp}{lttng_version}, this is the default buffering scheme | |
123 | for the Linux kernel tracing domain, but this may change in the future. | |
b4867b3b | 124 | |
188419c4 PP |
125 | option:--buffers-pid:: |
126 | Allocate one set of ring buffers (one per CPU) for each instrumented | |
127 | process of: | |
128 | + | |
129 | -- | |
130 | If you connect to the root session daemon:: | |
131 | All Unix users. | |
132 | + | |
133 | See the ``Session daemon connection'' section of man:lttng(1) to learn | |
134 | how a user application connects to a session daemon. | |
b4867b3b | 135 | |
188419c4 PP |
136 | Otherwise:: |
137 | Your Unix user. | |
138 | -- | |
139 | + | |
140 | Only available with the option:--userspace option. | |
b4867b3b | 141 | |
188419c4 PP |
142 | option:--buffers-uid:: |
143 | Allocate one set of ring buffers (one per CPU) shared by all the | |
144 | instrumented processes of: | |
145 | + | |
146 | -- | |
147 | If you connect to the root session daemon:: | |
148 | Each Unix user. | |
149 | + | |
150 | See the ``Session daemon connection'' section of man:lttng(1) to learn | |
151 | how a user application connects to a session daemon. | |
152 | ||
153 | Otherwise:: | |
154 | Your Unix user. | |
155 | -- | |
156 | + | |
157 | Only available with the option:--userspace option. | |
158 | + | |
159 | As of LTTng{nbsp}{lttng_version}, this is the default buffering scheme | |
160 | for the user space tracing domain, but this may change in the future. | |
b4867b3b PP |
161 | |
162 | ||
188419c4 PP |
163 | Event record loss mode |
164 | ~~~~~~~~~~~~~~~~~~~~~~ | |
7197e9ec | 165 | option:--blocking-timeout='TIMEOUTUS':: |
188419c4 PP |
166 | Set the channel's blocking timeout value to __TIMEOUTUS__{nbsp}µs |
167 | for instrumented applications executed with a set | |
168 | `LTTNG_UST_ALLOW_BLOCKING` environment variable. | |
169 | + | |
170 | 'TIMEOUTUS' is one of: | |
7197e9ec PP |
171 | + |
172 | -- | |
188419c4 | 173 | `0` (default):: |
7197e9ec PP |
174 | Do not block (non-blocking mode). |
175 | ||
176 | `inf`:: | |
188419c4 PP |
177 | Block forever until a sub-buffer is available to write the event |
178 | record. | |
7197e9ec | 179 | |
188419c4 PP |
180 | __N__, a positive value:: |
181 | Wait for at most __N__{nbsp}µs when trying to write to a sub-buffer. | |
182 | After __N__{nbsp}µs, discard the event record. | |
7197e9ec PP |
183 | -- |
184 | + | |
188419c4 PP |
185 | This option is only available with both the option:--userspace and |
186 | option:--discard options. | |
7197e9ec | 187 | |
b4867b3b PP |
188 | One of: |
189 | ||
190 | option:--discard:: | |
188419c4 PP |
191 | Discard event records when there's no available sub-buffer. |
192 | + | |
193 | As of LTTng{nbsp}{lttng_version}, this is the default event record loss | |
194 | mode, but this may change in the future. | |
b4867b3b PP |
195 | |
196 | option:--overwrite:: | |
188419c4 PP |
197 | Overwrite the whole sub-buffer containing the oldest event records |
198 | when there's no available sub-buffer (flight recorder mode). | |
b4867b3b PP |
199 | |
200 | ||
201 | Sub-buffers | |
202 | ~~~~~~~~~~~ | |
203 | option:--num-subbuf='COUNT':: | |
188419c4 PP |
204 | Use 'COUNT' sub-buffers per ring buffer. |
205 | + | |
206 | The effective value is 'COUNT' rounded up to the next power of two. | |
b4867b3b PP |
207 | + |
208 | Default values: | |
209 | + | |
188419c4 PP |
210 | option:--userspace and option:--buffers-uid options::: |
211 | +{default_ust_uid_channel_subbuf_num}+ | |
212 | option:--userspace and option:--buffers-pid options::: | |
213 | +{default_ust_pid_channel_subbuf_num}+ | |
214 | option:--kernel and option:--buffers-global options::: | |
215 | +{default_kernel_channel_subbuf_num}+ | |
216 | `metadata` channel::: | |
217 | +{default_metadata_subbuf_num}+ | |
b4867b3b | 218 | |
55d7bb02 PP |
219 | option:--output='TYPE':: |
220 | Set channel's output type to 'TYPE'. | |
221 | + | |
188419c4 PP |
222 | 'TYPE' is one of: |
223 | + | |
224 | -- | |
225 | `mmap`::: | |
226 | Share ring buffers between the tracer and the consumer daemon with | |
227 | the man:mmap(2) system call. | |
228 | ||
229 | `splice`::: | |
230 | Share ring buffers between the tracer and the consumer daemon | |
231 | with the man:splice(2) system call. | |
232 | + | |
233 | Only available with the option:--kernel option. | |
234 | -- | |
55d7bb02 PP |
235 | + |
236 | Default values: | |
237 | + | |
188419c4 PP |
238 | option:--userspace and option:--buffers-uid options::: |
239 | `mmap` | |
240 | option:--userspace and option:--buffers-pid options::: | |
241 | `mmap` | |
242 | option:--kernel and option:--buffers-global options::: | |
243 | `splice` | |
244 | `metadata` channel::: | |
245 | `mmap` | |
55d7bb02 | 246 | |
b4867b3b | 247 | option:--subbuf-size='SIZE':: |
188419c4 PP |
248 | Set the size of each sub-buffer to 'SIZE' bytes. |
249 | + | |
250 | The effective value is 'SIZE' rounded up to the next power of two. | |
251 | + | |
252 | The `k`{nbsp}(KiB), `M`{nbsp}(MiB), and `G`{nbsp}(GiB) suffixes are | |
253 | supported. | |
b4867b3b PP |
254 | + |
255 | The minimum sub-buffer size, for each tracer, is the maximum value | |
188419c4 PP |
256 | between the default below and the system page size (see man:getconf(1) |
257 | with the `PAGE_SIZE` variable). | |
b4867b3b PP |
258 | + |
259 | Default values: | |
260 | + | |
188419c4 PP |
261 | option:--userspace and option:--buffers-uid options::: |
262 | +{default_ust_uid_channel_subbuf_size}+ | |
263 | option:--userspace and option:--buffers-pid options::: | |
264 | +{default_ust_pid_channel_subbuf_size}+ | |
265 | option:--kernel and option:--buffers-global options::: | |
266 | +{default_kernel_channel_subbuf_size}+ | |
267 | `metadata` channel::: | |
268 | +{default_metadata_subbuf_size}+ | |
b4867b3b PP |
269 | |
270 | ||
271 | Trace files | |
272 | ~~~~~~~~~~~ | |
273 | option:--tracefile-count='COUNT':: | |
188419c4 PP |
274 | Limit the number of trace files which LTTng writes for this channel |
275 | to 'COUNT'. | |
b4867b3b | 276 | + |
188419c4 | 277 | 'COUNT' set to `0` means ``unlimited''. |
b4867b3b | 278 | + |
188419c4 PP |
279 | Default: +{default_channel_tracefile_count}+. |
280 | + | |
281 | You must also use the option:--tracefile-size option with this option. | |
b4867b3b PP |
282 | |
283 | option:--tracefile-size='SIZE':: | |
188419c4 PP |
284 | Set the maximum size of each trace file which LTTng writes for |
285 | this channel to __SIZE__{nbsp}bytes. | |
286 | + | |
287 | 'SIZE' set to `0` means ``unlimited''. | |
288 | + | |
289 | Default: +{default_channel_tracefile_size}+. | |
b4867b3b | 290 | + |
188419c4 PP |
291 | NOTE: Data streams which LTTng writes for a channel configured with this |
292 | option may inaccurately report discarded event records as of | |
293 | CTF{nbsp}1.8. | |
b4867b3b PP |
294 | |
295 | ||
296 | Timers | |
297 | ~~~~~~ | |
188419c4 PP |
298 | option:--monitor-timer='PERIODUS':: |
299 | Set the period of the monitor timer of the channel to | |
300 | __PERIODUS__{nbsp}µs. | |
301 | + | |
302 | Set 'PERIODUS' to `0` to disable the monitor timer. | |
961df0d0 PP |
303 | + |
304 | Default values: | |
305 | + | |
188419c4 PP |
306 | option:--userspace and option:--buffers-uid options::: |
307 | +{default_ust_uid_channel_monitor_timer}+ | |
308 | option:--userspace and option:--buffers-pid options::: | |
309 | +{default_ust_pid_channel_monitor_timer}+ | |
310 | option:--kernel and option:--buffers-global options::: | |
311 | +{default_kernel_channel_monitor_timer}+ | |
312 | ||
313 | option:--read-timer='PERIODUS':: | |
314 | Set the period of the read timer of the channel to | |
315 | __PERIODUS__{nbsp}µs. | |
316 | + | |
317 | Set 'PERIODUS' to `0` to disable the read timer. | |
b4867b3b PP |
318 | + |
319 | Default values: | |
320 | + | |
188419c4 PP |
321 | option:--userspace and option:--buffers-uid options::: |
322 | +{default_ust_uid_channel_read_timer}+ | |
323 | option:--userspace and option:--buffers-pid options::: | |
324 | +{default_ust_pid_channel_read_timer}+ | |
325 | option:--kernel and option:--buffers-global options::: | |
326 | +{default_kernel_channel_read_timer}+ | |
327 | `metadata` channel::: | |
328 | +{default_metadata_read_timer}+ | |
b4867b3b PP |
329 | |
330 | option:--switch-timer='PERIODUS':: | |
188419c4 PP |
331 | Set the period of the switch timer of the channel to |
332 | __PERIODUS__{nbsp}µs. | |
333 | + | |
334 | Set 'PERIODUS' to `0` to disable the switch timer. | |
c93eadad PP |
335 | + |
336 | Default values: | |
337 | + | |
188419c4 PP |
338 | option:--userspace and option:--buffers-uid options::: |
339 | +{default_ust_uid_channel_switch_timer}+ | |
340 | option:--userspace and option:--buffers-pid options::: | |
341 | +{default_ust_pid_channel_switch_timer}+ | |
342 | option:--kernel and option:--buffers-global options::: | |
343 | +{default_kernel_channel_switch_timer}+ | |
344 | `metadata` channel::: | |
345 | +{default_metadata_switch_timer}+ | |
b4867b3b PP |
346 | |
347 | ||
55e06994 | 348 | include::common-lttng-cmd-help-options.txt[] |
b4867b3b PP |
349 | |
350 | ||
55e06994 PP |
351 | include::common-lttng-cmd-after-options.txt[] |
352 | ||
353 | ||
354 | include::common-footer.txt[] | |
b4867b3b PP |
355 | |
356 | ||
357 | SEE ALSO | |
358 | -------- | |
491d1539 | 359 | man:lttng(1), |
188419c4 | 360 | man:lttng-disable-channel(1), |
21b35b3a PP |
361 | man:lttng-list(1), |
362 | man:lttng-concepts(7) |