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

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