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

   1 lttng-enable-event(1)
   2 =====================
   3 :revdate: 14 June 2021
   4
   5
   6 NAME
   7 ----
   8 lttng-enable-event - Create or enable LTTng recording event rules
   9
  10
  11 SYNOPSIS
  12 --------
  13 Create or enable one or more recording event rules to match Linux kernel
  14 tracepoint or system call events:
  15
  16 [verse]
  17 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-event* option:--kernel [option:--tracepoint | option:--syscall]
  18       (option:--all | 'NAME'[,'NAME']...) [option:--filter='EXPR']
  19       [option:--session='SESSION'] [option:--channel='CHANNEL']
  20
  21 Create or enable a recording event rule to match Linux kernel events
  22 created from a dynamic instrumentation point:
  23
  24 [verse]
  25 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-event* option:--kernel
  26       (option:--probe='LOC' | option:--function='LOC' | option:--userspace-probe='LOC') 'RECORDNAME'
  27       [option:--session='SESSION'] [option:--channel='CHANNEL']
  28
  29 Create or enable one or more recording event rules to match
  30 user space tracepoint events:
  31
  32 [verse]
  33 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-event* option:--userspace [option:--tracepoint]
  34       (option:--all | 'NAME'[,'NAME']...) [option:--exclude='XNAME'[,'XNAME']...]
  35       [option:--loglevel='LOGLEVEL' | option:--loglevel-only='LOGLEVEL'] [option:--filter='EXPR']
  36       [option:--session='SESSION'] [option:--channel='CHANNEL']
  37
  38 Create or enable one or more recording event rules to match
  39 Java/Python logging events:
  40
  41 [verse]
  42 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-event* (option:--jul | option:--log4j | option:--python)
  43       [option:--tracepoint] (option:--all | 'NAME'[,'NAME']...)
  44       [option:--loglevel='LOGLEVEL' | option:--loglevel-only='LOGLEVEL'] [option:--filter='EXPR']
  45       [option:--session='SESSION'] [option:--channel='CHANNEL']
  46
  47 DESCRIPTION
  48 -----------
  49 The `lttng enable-event` command does one of:
  50
  51 * Create one or more recording event rules.
  52
  53 * Enable one or more disabled recording event rules.
  54 +
  55 See the ``<<enable,Enable a disabled recording event rule>>'' section
  56 below.
  57
  58 See man:lttng-concepts(7) to learn more about instrumentation points,
  59 events, recording event rules, and event records.
  60
  61 The recording event rule(s) to create or enable belong to:
  62
  63 With the option:--session='SESSION' option::
  64     The recording session named 'SESSION'.
  65
  66 Without the option:--session option::
  67     The current recording session (see man:lttng-concepts(7) to learn
  68     more about the current recording session).
  69
  70 With the option:--channel='CHANNEL' option::
  71     The channel named 'CHANNEL'.
  72
  73 Without the option:--channel option::
  74     The channel named `channel0`.
  75 +
  76 If there's already a channel for the selected recording session and
  77 domain which isn't named `channel0`, the `enable-event` command fails.
  78 Otherwise, it automatically creates it.
  79
  80 See the ``<<examples,EXAMPLES>>'' section below for usage examples.
  81
  82 List the recording event rules of a specific recording session
  83 and/or channel with the man:lttng-list(1) and man:lttng-status(1)
  84 commands.
  85
  86 Disable an enabled recording event rule with the
  87 man:lttng-disable-event(1) command.
  88
  89
  90 Overview of recording event rule conditions
  91 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  92 For LTTng to emit and record an event{nbsp}__E__,{nbsp}__E__ must
  93 satisfy *all* the conditions of a recording event rule{nbsp}__ER__, that
  94 is:
  95
  96 Explicit conditions::
  97     You set the following conditions when you create or
  98     enable{nbsp}__ER__ with the `enable-event` command:
  99 +
 100 --
 101 * The instrumentation point type from which LTTng creates{nbsp}__E__
 102   has a specific type.
 103 +
 104 See the ``<<inst-point-type-cond,Instrumentation point type
 105 condition>>'' section below.
 106
 107 * A pattern matches the name of{nbsp}__E__ while another pattern
 108   doesn't.
 109 +
 110 See the ``<<event-name-cond,Event name condition>>'' section below.
 111
 112 * The log level of the instrumentation point from which LTTng
 113   creates{nbsp}__E__ is at least as severe as some value, or is exactly
 114   some value.
 115 +
 116 See the ``<<inst-point-log-level-cond,Instrumentation point log level
 117 condition>>'' section below.
 118
 119 * The fields of the payload of{nbsp}__E__ and the current context fields
 120   satisfy a filter expression.
 121 +
 122 See the ``<<filter-cond,Event payload and context filter condition>>''
 123 section below.
 124 --
 125
 126 Implicit conditions::
 127 +
 128 --
 129 * _ER_ itself is enabled.
 130 +
 131 A recording event rule is enabled on creation.
 132 +
 133 Enable a disabled recording event rule with the `enable-event` command.
 134
 135 * The channel to which{nbsp}__ER__ is attached is enabled.
 136 +
 137 A channel is enabled on creation.
 138 +
 139 Enable a disabled channel with the man:lttng-enable-channel(1) command.
 140
 141 * The recording session of{nbsp}__ER__ is active (started).
 142 +
 143 A recording session is inactive (stopped) on creation.
 144 +
 145 Start an inactive recording session with the man:lttng-start(1) command.
 146
 147 * The process for which LTTng creates{nbsp}__E__ is allowed to record
 148   events.
 149 +
 150 All processes are allowed to record events on recording session
 151 creation.
 152 +
 153 Use the man:lttng-track(1) and man:lttng-untrack(1) commands to select
 154 which processes are allowed to record events based on specific process
 155 attributes.
 156 --
 157
 158 The dedicated command-line options of most conditions are optional: if
 159 you don't specify the option, the associated condition is always
 160 satisfied.
 161
 162
 163 [[inst-point-type-cond]]
 164 Instrumentation point type condition
 165 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 166 An event{nbsp}__E__ satisfies the instrumentation point type condition
 167 of a recording event rule if the instrumentation point from which LTTng
 168 creates{nbsp}__E__ is:
 169
 170 For the Linux kernel tracing domain (option:--kernel option)::
 171     With the option:--tracepoint option or without any other instrumentation point type option:::
 172         An LTTng kernel tracepoint, that is, a statically defined point
 173         in the source code of the kernel image or of a kernel module
 174         with LTTng kernel tracer macros.
 175 +
 176 As of LTTng{nbsp}{lttng_version}, this is the default instrumentation
 177 point type of the Linux kernel tracing domain, but this may change in
 178 the future.
 179 +
 180 List the available Linux kernel tracepoints with `lttng list --kernel`.
 181 See man:lttng-list(1) to learn more.
 182
 183     With the option:--syscall option:::
 184         The entry and exit of a Linux kernel system call.
 185 +
 186 List the available Linux kernel system call instrumentation points with
 187 `lttng list --kernel --syscall`. See man:lttng-list(1) to learn more.
 188
 189     With the option:--probe option:::
 190         A Linux kprobe, that is, a single probe dynamically placed in
 191         the compiled kernel code.
 192 +
 193 The argument of the option:--probe option is the location of the
 194 kprobe to insert, either a symbol or a
 195 memory address, while 'RECORDNAME' is the name of the record
 196 of{nbsp}__E__ (see the ``<<er-name,Event record name>>'' section below).
 197 +
 198 The payload of a Linux kprobe event is empty.
 199
 200     With the option:--userspace-probe option:::
 201         A Linux user space probe, that is, a single probe dynamically
 202         placed at the entry of a compiled user space application/library
 203         function through the kernel.
 204 +
 205 The argument of the option:--userspace-probe option is the location
 206 of the user space probe to insert, one of:
 207 +
 208 --
 209 * A path and symbol (ELF method).
 210 * A path, provider name, and probe name (SystemTap User-level Statically
 211   Defined Tracing (USDT) method; a DTrace-style marker).
 212 +
 213 As of LTTng{nbsp}{lttng_version}, LTTng only supports USDT probes which
 214 are :not: reference-counted.
 215 --
 216 +
 217 'RECORDNAME' is the name of the record of{nbsp}__E__ (see the
 218 ``<<er-name,Event record name>>'' section below).
 219 +
 220 The payload of a Linux user space probe event is empty.
 221
 222     With the option:--function option:::
 223         A Linux kretprobe, that is, two probes dynamically placed at the
 224         entry and exit of a function in the compiled kernel code.
 225 +
 226 The argument of the option:--function option is the location of the
 227 Linux kretprobe to insert, either a symbol or
 228 a memory address, while 'RECORDNAME' is the name of the record
 229 of{nbsp}__E__ (see the ``<<er-name,Event record name>>'' section below).
 230 +
 231 The payload of a Linux kretprobe event is empty.
 232
 233 For the user space tracing domain (option:--userspace option)::
 234     With or without the option:--tracepoint option:::
 235         An LTTng user space tracepoint, that is, a statically defined
 236         point in the source code of a C/$$C++$$ application/library with
 237         LTTng user space tracer macros.
 238 +
 239 As of LTTng{nbsp}{lttng_version}, this is the default and sole
 240 instrumentation point type of the user space tracing domain, but this
 241 may change in the future.
 242 +
 243 List the available user space tracepoints with `lttng list --userspace`.
 244 See man:lttng-list(1) to learn more.
 245
 246 For the `java.util.logging` (option:--jul option), Apache log4j (option:--log4j option), and Python (option:--python option) tracing domains::
 247     With or without the option:--tracepoint option:::
 248         A logging statement.
 249 +
 250 As of LTTng{nbsp}{lttng_version}, this is the default and sole
 251 instrumentation point type of the `java.util.logging`, Apache log4j, and
 252 Python tracing domains, but this may change in the future.
 253 +
 254 List the available Java and Python loggers with `lttng list --jul`,
 255 `lttng list --log4j`, and `lttng list --python`. See man:lttng-list(1)
 256 to learn more.
 257
 258
 259 [[event-name-cond]]
 260 Event name condition
 261 ~~~~~~~~~~~~~~~~~~~~
 262 An event{nbsp}__E__ satisfies the event name condition of a recording
 263 event rule{nbsp}__ER__ if the two following statements are true:
 264
 265 * You specify the option:--all option or, depending on the
 266   instrumentation type condition (see the
 267   ``<<inst-point-type-cond,Instrumentation point type condition>>''
 268   section above) of{nbsp}__ER__, 'NAME' matches:
 269 +
 270 --
 271 LTTng tracepoint::
 272     The full name of the tracepoint from which LTTng creates{nbsp}__E__.
 273 +
 274 Note that the full name of a user space tracepoint is
 275 __PROVIDER__++:++__NAME__, where __PROVIDER__ is the tracepoint provider
 276 name and __NAME__ is the tracepoint name.
 277
 278 Logging statement::
 279     The name of the Java or Python logger from which LTTng
 280     creates{nbsp}__E__.
 281
 282 Linux system call::
 283     The name of the system call, without any `sys_` prefix, from which
 284     LTTng creates{nbsp}__E__.
 285 --
 286
 287 * You don't specify the option:--exclude=__XNAME__[++,++__XNAME__]...
 288   option or, depending on the instrumentation type condition
 289   of{nbsp}__ER__, none of the 'XNAME' arguments matches the full name of
 290   the user space tracepoint from which LTTng creates{nbsp}__E__.
 291 +
 292 The option:--exclude option is only available with the option:--userspace
 293 option.
 294
 295 This condition is only meaningful for the LTTng tracepoint, logging
 296 statement, and Linux system call instrumentation point types: it's
 297 always satisfied for the other types.
 298
 299 In all cases, 'NAME' and 'XNAME' are globbing patterns: the `*`
 300 character means ``match anything''. To match a literal `*` character,
 301 use :escwc:. To match a literal `,` character, use
 302 :esccomma:.
 303
 304 IMPORTANT: Make sure to **single-quote** 'NAME' and 'XNAME' when they
 305 contain the `*` character and when you run the `enable-event` command
 306 from a shell.
 307
 308 With the LTTng tracepoint, logging statement, and Linux system call
 309 instrumentation point types, the `enable-event` command creates or
 310 enables one independent recording event rule per 'NAME' argument
 311 (non-option, comma-separated). With the option:--all option, the
 312 `enable-event` command creates or enables a single recording event rule.
 313
 314
 315 [[inst-point-log-level-cond]]
 316 Instrumentation point log level condition
 317 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 318 An event{nbsp}__E__ satisfies the instrumentation point log level
 319 condition of a recording event rule if either:
 320
 321 * The option:--loglevel and option:--loglevel-only options are
 322   missing.
 323
 324 * The log level of the LTTng user space tracepoint or logging statement
 325   which creates{nbsp}__E__ is:
 326       With the option:--loglevel='LOGLEVEL' option::
 327           At least as severe as 'LOGLEVEL'.
 328
 329       With the option:--loglevel-only='LOGLEVEL' option::
 330           Exactly 'LOGLEVEL'.
 331
 332 This condition is only meaningful for the LTTng user space tracepoint
 333 and logging statement instrumentation point types: it's always satisfied
 334 for other types.
 335
 336 The available values of 'LOGLEVEL' are, depending on the tracing domain,
 337 from the most to the least severe:
 338
 339 User space (option:--userspace option)::
 340 +
 341 * `EMERG` (0)
 342 * `ALERT` (1)
 343 * `CRIT` (2)
 344 * `ERR` (3)
 345 * `WARNING` (4)
 346 * `NOTICE` (5)
 347 * `INFO` (6)
 348 * `DEBUG_SYSTEM` (7)
 349 * `DEBUG_PROGRAM` (8)
 350 * `DEBUG_PROCESS` (9)
 351 * `DEBUG_MODULE` (10)
 352 * `DEBUG_UNIT` (11)
 353 * `DEBUG_FUNCTION` (12)
 354 * `DEBUG_LINE` (13)
 355 * `DEBUG` (14)
 356
 357 `java.util.logging` (option:--jul option)::
 358 +
 359 * `OFF` (`INT32_MAX`)
 360 * `SEVERE` (1000)
 361 * `WARNING` (900)
 362 * `INFO` (800)
 363 * `CONFIG` (700)
 364 * `FINE` (500)
 365 * `FINER` (400)
 366 * `FINEST` (300)
 367 * `ALL` (`INT32_MIN`)
 368
 369 Apache log4j (option:--log4j option)::
 370 +
 371 * `OFF` (`INT32_MAX`)
 372 * `FATAL` (50000)
 373 * `ERROR` (40000)
 374 * `WARN` (30000)
 375 * `INFO` (20000)
 376 * `DEBUG` (10000)
 377 * `TRACE` (5000)
 378 * `ALL` (`INT32_MIN`)
 379
 380 Python (option:--python option)::
 381 +
 382 * `CRITICAL` (50)
 383 * `ERROR` (40)
 384 * `WARNING` (30)
 385 * `INFO` (20)
 386 * `DEBUG` (10)
 387 * `NOTSET` (0)
 388
 389
 390 [[filter-cond]]
 391 Event payload and context filter condition
 392 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 393 An event{nbsp}__E__ satisfies the event payload and context filter
 394 condition of a recording event rule if the option:--filter='EXPR'
 395 option is missing or if 'EXPR' is _true_.
 396
 397 This condition is only meaningful for the LTTng tracepoint and Linux
 398 system call instrumentation point types: it's always satisfied for other
 399 types.
 400
 401 'EXPR' can contain references to the payload fields of{nbsp}__E__ and
 402 to the current context fields.
 403
 404 IMPORTANT: Make sure to **single-quote** 'EXPR' when you run the
 405 `enable-event` command from a shell, as filter expressions typically
 406 include characters having a special meaning for most shells.
 407
 408 The expected syntax of 'EXPR' is similar to the syntax of a
 409 C{nbsp}language conditional expression (an expression which an `if`
 410 statement can evaluate), but there are a few differences:
 411
 412 * A _NAME_ expression identifies an event payload field named
 413   _NAME_ (a C{nbsp}identifier).
 414 +
 415 Use the C{nbsp}language dot and square bracket notations to access
 416 nested structure and array/sequence fields. You can only use a constant,
 417 positive integer number within square brackets. If the index is out of
 418 bounds, 'EXPR' is _false_.
 419 +
 420 The value of an enumeration field is an integer.
 421 +
 422 When a field expression doesn't exist, 'EXPR' is _false_.
 423 +
 424 Examples: `my_field`, `target_cpu`, `seq[7]`, `msg.user[1].data[2][17]`.
 425
 426 * A ++$ctx.++__TYPE__ expression identifies the statically-known context
 427   field having the type _TYPE_ (a C{nbsp}identifier).
 428 +
 429 List the available statically-known context field names with the
 430 man:lttng-add-context(1) command.
 431 +
 432 When a field expression doesn't exist, 'EXPR' is _false_.
 433 +
 434 Examples: `$ctx.prio`, `$ctx.preemptible`,
 435 `$ctx.perf:cpu:stalled-cycles-frontend`.
 436
 437 * A ++$app.++__PROVIDER__++:++__TYPE__ expression identifies the
 438   application-specific context field having the type _TYPE_ (a
 439   C{nbsp}identifier) from the provider _PROVIDER_ (a C{nbsp}identifier).
 440 +
 441 When a field expression doesn't exist, 'EXPR' is _false_.
 442 +
 443 Example: `$app.server:cur_user`.
 444
 445 * Compare strings, either string fields or string literals
 446   (double-quoted), with the `==` and `!=` operators.
 447 +
 448 When comparing to a string literal, the `*` character means ``match
 449 anything''. To match a literal `*` character, use :escwc:.
 450 +
 451 Examples: `my_field == "user34"`, `my_field == my_other_field`,
 452 `my_field == "192.168.*"`.
 453
 454 * The precedence table of the operators which are supported in 'EXPR'
 455   is as follows. In this table, the highest precedence is{nbsp}1:
 456 +
 457 [options="header"]
 458 |===
 459 |Precedence |Operator |Description |Associativity
 460 |1 |`-` |Unary minus |Right-to-left
 461 |1 |`+` |Unary plus |Right-to-left
 462 |1 |`!` |Logical NOT |Right-to-left
 463 |1 |`~` |Bitwise NOT |Right-to-left
 464 |2 |`<<` |Bitwise left shift |Left-to-right
 465 |2 |`>>` |Bitwise right shift |Left-to-right
 466 |3 |`&` |Bitwise AND |Left-to-right
 467 |4 |`^` |Bitwise XOR |Left-to-right
 468 |5 |`\|` |Bitwise OR |Left-to-right
 469 |6 |`<` |Less than |Left-to-right
 470 |6 |`<=` |Less than or equal to |Left-to-right
 471 |6 |`>` |Greater than |Left-to-right
 472 |6 |`>=` |Greater than or equal to |Left-to-right
 473 |7 |`==` |Equal to |Left-to-right
 474 |7 |`!=` |Not equal to |Left-to-right
 475 |8 |`&&` |Logical AND |Left-to-right
 476 |9 |`\|\|` |Logical OR |Left-to-right
 477 |===
 478 +
 479 Parentheses are supported to bypass the default order.
 480 +
 481 IMPORTANT: Unlike the C{nbsp}language, the bitwise AND and OR operators
 482 (`&` and `|`) in 'EXPR' take precedence over relational operators (`<`,
 483 `<=`, `>`, `>=`, `==`, and `!=`). This means the expression `2 & 2 == 2`
 484 is _true_ while the equivalent C{nbsp}expression is _false_.
 485 +
 486 The arithmetic operators are :not: supported.
 487 +
 488 LTTng first casts all integer constants and fields to signed 64-bit
 489 integers. The representation of negative integers is two's complement.
 490 This means that, for example, the signed 8-bit integer field 0xff (-1)
 491 becomes 0xffffffffffffffff (still -1) once casted.
 492 +
 493 Before a bitwise operator is applied, LTTng casts all its operands to
 494 unsigned 64-bit integers, and then casts the result back to a signed
 495 64-bit integer. For the bitwise NOT operator, it's the equivalent of
 496 this C{nbsp}expression:
 497 +
 498 [source,c]
 499 ----
 500 (int64_t) ~((uint64_t) val)
 501 ----
 502 +
 503 For the binary bitwise operators, it's the equivalent of those
 504 C{nbsp}expressions:
 505 +
 506 [source,c]
 507 ----
 508 (int64_t) ((uint64_t) lhs >> (uint64_t) rhs)
 509 (int64_t) ((uint64_t) lhs << (uint64_t) rhs)
 510 (int64_t) ((uint64_t) lhs & (uint64_t) rhs)
 511 (int64_t) ((uint64_t) lhs ^ (uint64_t) rhs)
 512 (int64_t) ((uint64_t) lhs | (uint64_t) rhs)
 513 ----
 514 +
 515 If the right-hand side of a bitwise shift operator (`<<` and `>>`) is
 516 not in the [0,{nbsp}63] range, then 'EXPR' is _false_.
 517
 518 [NOTE]
 519 ====
 520 Use the man:lttng-track(1) and man:lttng-untrack(1) commands to allow or
 521 disallow processes to record LTTng events based on their attributes
 522 instead of using equivalent statically-known context fields in 'EXPR'
 523 like `$ctx.pid`.
 524
 525 The former method is much more efficient.
 526 ====
 527
 528 'EXPR' examples:
 529
 530 ----------------------------
 531 msg_id == 23 && size >= 2048
 532 ----------------------------
 533
 534 -------------------------------------------------
 535 $ctx.procname == "lttng*" && (!flag || poel < 34)
 536 -------------------------------------------------
 537
 538 ---------------------------------------------------------
 539 $app.my_provider:my_context == 17.34e9 || some_enum >= 14
 540 ---------------------------------------------------------
 541
 542 ---------------------------------------
 543 $ctx.cpu_id == 2 && filename != "*.log"
 544 ---------------------------------------
 545
 546 ------------------------------------------------
 547 eax_reg & 0xff7 == 0x240 && x[4] >> 12 <= 0x1234
 548 ------------------------------------------------
 549
 550
 551 [[er-name]]
 552 Event record name
 553 ~~~~~~~~~~~~~~~~~
 554 When LTTng records an event{nbsp}__E__, the resulting event record has a
 555 name which depends on the instrumentation point type condition (see the
 556 ``<<inst-point-type-cond,Instrumentation point type condition>>''
 557 section above) of the recording event rule which matched{nbsp}__E__:
 558
 559 LTTng tracepoint (option:--kernel/option:--userspace and option:--tracepoint options)::
 560     Full name of the tracepoint from which LTTng creates{nbsp}__E__.
 561 +
 562 Note that the full name of a user space tracepoint is
 563 __PROVIDER__++:++__NAME__, where __PROVIDER__ is the tracepoint provider
 564 name and __NAME__ is the tracepoint name.
 565
 566 `java.util.logging` logging statement (option:--jul and option:--tracepoint options)::
 567     `lttng_jul:event`
 568 +
 569 Such an event record has a string field `logger_name` which contains the
 570 name of the `java.util.logging` logger from which LTTng
 571 creates{nbsp}__E__.
 572
 573 Apache log4j logging statement (option:--log4j and option:--tracepoint options)::
 574     `lttng_log4j:event`
 575 +
 576 Such an event record has a string field `logger_name` which contains the
 577 name of the Apache log4j logger from which LTTng creates{nbsp}__E__.
 578
 579 Python logging statement (option:--python and option:--tracepoint options)::
 580     `lttng_python:event`
 581 +
 582 Such an event record has a string field `logger_name` which contains the
 583 name of the Python logger from which LTTng creates{nbsp}__E__.
 584
 585 Linux system call (option:--kernel and option:--syscall options)::
 586     Entry:::
 587         ++syscall_entry_++__NAME__, where _NAME_ is the name of the
 588         system call from which LTTng creates{nbsp}__E__, without any
 589         `sys_` prefix.
 590
 591     Exit:::
 592         ++syscall_exit_++__NAME__, where _NAME_ is the name of the
 593         system call from which LTTng creates{nbsp}__E__, without any
 594         `sys_` prefix.
 595
 596 Linux kprobe (option:--kernel and option:--probe options)::
 597 Linux user space probe (option:--kernel and option:--userspace-probe options)::
 598     'RECORDNAME' (first non-option argument).
 599
 600 Linux kretprobe (option:--kernel and option:--function options)::
 601     Entry:::
 602         __RECORDNAME__++_entry++
 603
 604     Exit:::
 605         __RECORDNAME__++_exit++
 606
 607
 608 [[enable]]
 609 Enable a disabled recording event rule
 610 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 611 The `enable-event` command can enable a disabled recording event rule,
 612 as listed in the output of the man:lttng-list(1) command.
 613
 614 You may enable a disabled recording event rule regardless of the
 615 activity (started or stopped) of its recording session (see
 616 man:lttng-start(1) and man:lttng-stop(1)).
 617
 618 To enable a disabled recording event rule, run the `enable-event`
 619 command with the exact same options and arguments that you used to
 620 create it. In particular, with the option:--filter='EXPR' option, 'EXPR'
 621 must be the exact same string as the one you used on creation.
 622
 623
 624 include::common-lttng-cmd-options-head.txt[]
 625
 626
 627 Tracing domain
 628 ~~~~~~~~~~~~~~
 629 One of:
 630
 631 option:-j, option:--jul::
 632     Create or enable recording event rules in the `java.util.logging`
 633     (JUL) tracing domain.
 634
 635 option:-k, option:--kernel::
 636     Create or enable recording event rules in the Linux kernel tracing
 637     domain.
 638
 639 option:-l, option:--log4j::
 640     Create or enable recording event rules in the Apache log4j tracing
 641     domain.
 642
 643 option:-p, option:--python::
 644     Create or enable recording event rules in the Python tracing domain.
 645
 646 option:-u, option:--userspace::
 647     Create or enable recording event rules in the user space tracing
 648     domain.
 649
 650
 651 Recording target
 652 ~~~~~~~~~~~~~~~~
 653 option:-c 'CHANNEL', option:--channel='CHANNEL'::
 654     Create or enable recording event rules attached to the channel named
 655     'CHANNEL' instead of `channel0`.
 656
 657 option:-s 'SESSION', option:--session='SESSION'::
 658     Create or enable recording event rules in the recording session
 659     named 'SESSION' instead of the current recording session.
 660
 661
 662 Instrumentation point type condition
 663 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 664 See the ``<<inst-point-type-cond,Instrumentation point type
 665 condition>>'' section above.
 666
 667 At most one of:
 668
 669 option:--function='LOC'::
 670     Only match Linux kretprobe events.
 671 +
 672 Only available with the option:--kernel option.
 673 +
 674 'LOC' is one of:
 675 +
 676 --
 677 * A function address (`0x` hexadecimal prefix supported).
 678 * A function symbol name.
 679 * A function symbol name and an offset
 680   (__SYMBOL__++pass:[+]++__OFFSET__ format).
 681 --
 682 +
 683 You must specify the event record name with 'RECORDNAME'. See the
 684 ``<<er-name,Event record name>>'' section above to learn more.
 685
 686 option:--probe='LOC'::
 687     Only match Linux kprobe events.
 688 +
 689 Only available with the option:--kernel option.
 690 +
 691 'LOC' is one of:
 692 +
 693 --
 694 * An address (`0x` hexadecimal prefix supported).
 695 * A symbol name.
 696 * A symbol name and an offset (__SYMBOL__++pass:[+]++__OFFSET__ format).
 697 --
 698 +
 699 You must specify the event record name with 'RECORDNAME'. See the
 700 ``<<er-name,Event record name>>'' section above to learn more.
 701
 702 option:--userspace-probe='LOC'::
 703     Only match Linux user space probe events.
 704 +
 705 Only available with the option:--kernel option.
 706 +
 707 'LOC' is one of:
 708 +
 709 --
 710 \[++elf:++]__PATH__++:++__SYMBOL__::
 711     Probe an available symbol within a user space application or
 712     library.
 713 +
 714 --
 715 'PATH'::
 716     Application or library path.
 717 +
 718 One of:
 719 +
 720 * An absolute path.
 721 * A relative path.
 722 * The name of an application as found in the directories listed in the
 723   `PATH` environment variable.
 724
 725 'SYMBOL'::
 726     Symbol name of the function of which to instrument the entry.
 727 +
 728 'SYMBOL' can be any defined code symbol in the output of the man:nm(1)
 729 command, including with its nloption:--dynamic option, which lists
 730 dynamic symbols.
 731 --
 732 +
 733 As of LTTng{nbsp}{lttng_version}, not specifying `elf:` is equivalent to
 734 specifying it, but this default may change in the future.
 735 +
 736 Examples:
 737 +
 738 * `--userspace-probe=/usr/lib/libc.so.6:malloc`
 739 * `--userspace-probe=./myapp:createUser`
 740 * `--userspace-probe=elf:httpd:ap_run_open_htaccess`
 741
 742 ++sdt:++__PATH__++:++__PROVIDER__++:++__NAME__::
 743     Use a SystemTap User-level Statically Defined Tracing (USDT) probe
 744     within a user space application or library.
 745 +
 746 --
 747 'PATH'::
 748     Application or library path.
 749 +
 750 This can be:
 751 +
 752 * An absolute path.
 753 * A relative path.
 754 * The name of an application as found in the directories listed in the
 755   `PATH` environment variable.
 756
 757 'PROVIDER'::
 758 'NAME'::
 759     USDT provider and probe names.
 760 +
 761 For example, with the following USDT probe:
 762 +
 763 [source,c]
 764 ----
 765 DTRACE_PROBE2("server", "accept_request",
 766               request_id, ip_addr);
 767 ----
 768 +
 769 The provider/probe name pair is `server:accept_request`.
 770 --
 771 +
 772 Example: `--userspace-probe=sdt:./build/server:server:accept_request`
 773 --
 774 +
 775 You must specify the event record name with 'RECORDNAME'. See the
 776 ``<<er-name,Event record name>>'' section above to learn more.
 777
 778 option:--syscall::
 779     Only match Linux system call events.
 780 +
 781 Only available with the option:--kernel option.
 782
 783 option:--tracepoint::
 784     Only match:
 785 +
 786 With the option:--kernel or option:--userspace option:::
 787     LTTng tracepoint events.
 788 With the option:--jul, option:--log4j, or option:--python option:::
 789     Logging events.
 790
 791 With the option:--kernel, not specifying any of the instrumentation
 792 point type options is equivalent to specifying the option:--tracepoint
 793 option, but this default may change in the future.
 794
 795 With the option:--userspace, option:--jul, option:--log4j, and
 796 option:--python options, not specifying the option:--tracepoint option
 797 is equivalent to specifying it, but this default may change in the
 798 future.
 799
 800
 801 Event name condition
 802 ~~~~~~~~~~~~~~~~~~~~
 803 See the ``<<event-name-cond,Event name condition>>'' section above.
 804
 805 option:-a, option:--all::
 806     Equivalent to a single 'NAME' argument (LTTng tracepoint or logger
 807     name) set to `*` (match anything).
 808 +
 809 You may :not: use this option with a 'NAME' argument.
 810
 811 option:-x 'XNAME'[,'XNAME']..., option:--exclude='XNAME'[,'XNAME']...::
 812     Only match events of which none of the 'XNAME' arguments
 813     matches the full name of the LTTng user space tracepoint.
 814 +
 815 Only available with the option:--userspace option.
 816 +
 817 'XNAME' is a globbing pattern: the `*` character means ``match
 818 anything''. To match a literal `*` character, use :escwc:. To match
 819 a literal `,` character, use :esccomma:.
 820
 821
 822 Instrumentation point log level condition
 823 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 824 See the ``<<inst-point-log-level-cond,Instrumentation point log level
 825 condition>>'' section above.
 826
 827 At most one of:
 828
 829 option:--loglevel='LOGLEVEL'::
 830     Only match events of which the log level of the LTTng tracepoint or
 831     logging statement is at least as severe as 'LOGLEVEL'.
 832
 833 option:--loglevel-only='LOGLEVEL'::
 834     Only match events of which the log level of the LTTng tracepoint or
 835     logging statement is exactly 'LOGLEVEL'.
 836
 837 The instrumentation point log level options above are :not: available
 838 with the option:--kernel option.
 839
 840
 841 Event payload and context filter condition
 842 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 843 See the ``<<filter-cond,Event payload and context filter condition>>''
 844 section above.
 845
 846 option:-f 'EXPR', option:--filter='EXPR'::
 847     Only match events of which 'EXPR', which can contain references to
 848     event payload and current context fields, is _true_.
 849 +
 850 This option is only available with the option:--tracepoint or
 851 option:--syscall option.
 852
 853
 854 include::common-lttng-cmd-help-options.txt[]
 855
 856
 857 include::common-lttng-cmd-after-options.txt[]
 858
 859
 860 [[examples]]
 861 EXAMPLES
 862 --------
 863 .Create a recording event rule which matches all Linux system call events (current recording session, default channel).
 864 ====
 865 See the option:--all and option:--syscall options.
 866
 867 [role="term"]
 868 ----
 869 $ lttng enable-event --kernel --all --syscall
 870 ----
 871 ====
 872
 873 .Create a recording event rule which matches user space tracepoint events named specifically (current recording session, default channel).
 874 ====
 875 The recording event rule below matches all user space tracepoint events
 876 of which the name starts with `my_provider:msg`.
 877
 878 [role="term"]
 879 ----
 880 $ lttng enable-event --userspace 'my_provider:msg*'
 881 ----
 882 ====
 883
 884 .Create three recording event rules which match Python logging events named specifically (current recording session, default channel).
 885 ====
 886 [role="term"]
 887 ----
 888 $ lttng enable-event --python server3,ui.window,user-mgmt
 889 ----
 890 ====
 891
 892 .Create a recording event rule which matches Apache log4j logging events with a specific log level range (current recording session, specific channel).
 893 ====
 894 See the option:--channel, option:--all, and option:--loglevel options.
 895
 896 [role="term"]
 897 ----
 898 $ lttng enable-event --log4j --channel=my-loggers \
 899                      --all --loglevel=INFO
 900 ----
 901 ====
 902
 903 .Create a recording event rule which matches specific Linux kprobe events (current recording session, default channel).
 904 ====
 905 The recording event rule below matches the entry of `usb_disconnect()`
 906 Linux kernel function calls. The records of such events are named `usbd`
 907 (see the ``<<er-name,Event record name>>'' section above).
 908
 909 See the option:--probe option.
 910
 911 [role="term"]
 912 ----
 913 $ lttng enable-event --kernel --probe=usb_disconnect usbd
 914 ----
 915 ====
 916
 917 .Create a recording event rule which matches Linux kernel tracepoint events which satisfy an event payload and context filter (specific recording session, default channel).
 918 ====
 919 See the option:--session and option:--filter options.
 920
 921 [role="term"]
 922 ----
 923 $ lttng enable-event --kernel --session=my-session 'sched_*' \
 924         --filter='$ctx.preemptible && comm != "systemd*"'
 925 ----
 926 ====
 927
 928 .Enable two Linux kernel tracepoint recording event rules (current recording session, specific channel).
 929 ====
 930 See the option:--channel option.
 931
 932 [role="term"]
 933 ----
 934 $ lttng enable-event --kernel --channel=tva ja,wendy
 935 ----
 936 ====
 937
 938
 939 include::common-footer.txt[]
 940
 941
 942 SEE ALSO
 943 --------
 944 man:lttng(1),
 945 man:lttng-disable-event(1),
 946 man:lttng-enable-channel(1),
 947 man:lttng-list(1),
 948 man:lttng-start(1),
 949 man:lttng-track(1),
 950 man:lttng-concepts(7)