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

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