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

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