doc/man/lttng-enable-channel.1.txt

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