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

   1 lttng-enable-channel(1)
   2 =======================
   3 :revdate: 3 May 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 tracing session named 'SESSION'.
  58
  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).
  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 List the channels of a given tracing session with the
  67 man:lttng-list(1) and man:lttng-status(1) commands.
  68
  69 Disable an enabled channel with the man:lttng-disable-channel(1)
  70 command.
  71
  72 [IMPORTANT]
  73 ====
  74 As of LTTng{nbsp}{lttng_version}, you may :not: perform the following
  75 operations with the `enable-channel` command:
  76
  77 * Change an attribute of an existing channel.
  78
  79 * Enable a disabled channel once its tracing session has been active
  80   (started; see man:lttng-start(1)) at least once.
  81
  82 * Create a channel once its tracing session has been active at least
  83   once.
  84
  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 ====
  90
  91
  92 include::common-cmd-options-head.txt[]
  93
  94
  95 Tracing domain
  96 ~~~~~~~~~~~~~~
  97 One of:
  98
  99 option:-k, option:--kernel::
 100     Create or enable channels in the Linux kernel domain.
 101
 102 option:-u, option:--userspace::
 103     Create or enable channels in the user space domain.
 104
 105
 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.
 111
 112
 113 Buffering scheme
 114 ~~~~~~~~~~~~~~~~
 115 One of:
 116
 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.
 124
 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.
 135
 136 Otherwise::
 137     Your Unix user.
 138 --
 139 +
 140 Only available with the option:--userspace option.
 141
 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.
 161
 162
 163 Event record loss mode
 164 ~~~~~~~~~~~~~~~~~~~~~~
 165 option:--blocking-timeout='TIMEOUTUS'::
 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:
 171 +
 172 --
 173 `0` (default)::
 174     Do not block (non-blocking mode).
 175
 176 `inf`::
 177     Block forever until a sub-buffer is available to write the event
 178     record.
 179
 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.
 183 --
 184 +
 185 This option is only available with both the option:--userspace and
 186 option:--discard options.
 187
 188 One of:
 189
 190 option:--discard::
 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.
 195
 196 option:--overwrite::
 197     Overwrite the whole sub-buffer containing the oldest event records
 198     when there's no available sub-buffer (flight recorder mode).
 199
 200
 201 Sub-buffers
 202 ~~~~~~~~~~~
 203 option:--num-subbuf='COUNT'::
 204     Use 'COUNT' sub-buffers per ring buffer.
 205 +
 206 The effective value is 'COUNT' rounded up to the next power of two.
 207 +
 208 Default values:
 209 +
 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}+
 218
 219 option:--output='TYPE'::
 220     Set channel's output type to 'TYPE'.
 221 +
 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 --
 235 +
 236 Default values:
 237 +
 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`
 246
 247 option:--subbuf-size='SIZE'::
 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.
 254 +
 255 The minimum sub-buffer size, for each tracer, is the maximum value
 256 between the default below and the system page size (see man:getconf(1)
 257 with the `PAGE_SIZE` variable).
 258 +
 259 Default values:
 260 +
 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}+
 269
 270
 271 Trace files
 272 ~~~~~~~~~~~
 273 option:--tracefile-count='COUNT'::
 274     Limit the number of trace files which LTTng writes for this channel
 275     to 'COUNT'.
 276 +
 277 'COUNT' set to `0` means ``unlimited''.
 278 +
 279 Default: +{default_channel_tracefile_count}+.
 280 +
 281 You must also use the option:--tracefile-size option with this option.
 282
 283 option:--tracefile-size='SIZE'::
 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}+.
 290 +
 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.
 294
 295
 296 Timers
 297 ~~~~~~
 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.
 303 +
 304 Default values:
 305 +
 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.
 318 +
 319 Default values:
 320 +
 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}+
 329
 330 option:--switch-timer='PERIODUS'::
 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.
 335 +
 336 Default values:
 337 +
 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}+
 346
 347
 348 include::common-cmd-help-options.txt[]
 349
 350
 351 include::common-cmd-footer.txt[]
 352
 353
 354 SEE ALSO
 355 --------
 356 man:lttng(1),
 357 man:lttng-disable-channel(1),
 358 man:lttng-list(1),
 359 man:lttng-concepts(7)