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 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 This condition is only meaningful for the LTTng tracepoint and Linux
 399 system call instrumentation point types: it's always satisfied for other
 400 types.
 401
 402 'EXPR' can contain references to the payload fields of{nbsp}__E__ and
 403 to the current context fields.
 404
 405 IMPORTANT: Make sure to **single-quote** 'EXPR' when you run the
 406 `enable-event` command from a shell, as filter expressions typically
 407 include characters having a special meaning for most shells.
 408
 409 The expected syntax of 'EXPR' is similar to the syntax of a
 410 C{nbsp}language conditional expression (an expression which an `if`
 411 statement can evaluate), but there are a few differences:
 412
 413 * A _NAME_ expression identifies an event payload field named
 414   _NAME_ (a C{nbsp}identifier).
 415 +
 416 Use the C{nbsp}language dot and square bracket notations to access
 417 nested structure and array/sequence fields. You can only use a constant,
 418 positive integer number within square brackets. If the index is out of
 419 bounds, 'EXPR' is _false_.
 420 +
 421 The value of an enumeration field is an integer.
 422 +
 423 When a field expression doesn't exist, 'EXPR' is _false_.
 424 +
 425 Examples: `my_field`, `target_cpu`, `seq[7]`, `msg.user[1].data[2][17]`.
 426
 427 * A ++$ctx.++__TYPE__ expression identifies the statically-known context
 428   field having the type _TYPE_ (a C{nbsp}identifier).
 429 +
 430 List the available statically-known context field names with the
 431 man:lttng-add-context(1) command.
 432 +
 433 When a field expression doesn't exist, 'EXPR' is _false_.
 434 +
 435 Examples: `$ctx.prio`, `$ctx.preemptible`,
 436 `$ctx.perf:cpu:stalled-cycles-frontend`.
 437
 438 * A ++$app.++__PROVIDER__++:++__TYPE__ expression identifies the
 439   application-specific context field having the type _TYPE_ (a
 440   C{nbsp}identifier) from the provider _PROVIDER_ (a C{nbsp}identifier).
 441 +
 442 When a field expression doesn't exist, 'EXPR' is _false_.
 443 +
 444 Example: `$app.server:cur_user`.
 445
 446 * Compare strings, either string fields or string literals
 447   (double-quoted), with the `==` and `!=` operators.
 448 +
 449 When comparing to a string literal, the `*` character means ``match
 450 anything''. To match a literal `*` character, use :escwc:.
 451 +
 452 Examples: `my_field == "user34"`, `my_field == my_other_field`,
 453 `my_field == "192.168.*"`.
 454
 455 * The precedence table of the operators which are supported in 'EXPR'
 456   is as follows. In this table, the highest precedence is{nbsp}1:
 457 +
 458 [options="header"]
 459 |===
 460 |Precedence |Operator |Description |Associativity
 461 |1 |`-` |Unary minus |Right-to-left
 462 |1 |`+` |Unary plus |Right-to-left
 463 |1 |`!` |Logical NOT |Right-to-left
 464 |1 |`~` |Bitwise NOT |Right-to-left
 465 |2 |`<<` |Bitwise left shift |Left-to-right
 466 |2 |`>>` |Bitwise right shift |Left-to-right
 467 |3 |`&` |Bitwise AND |Left-to-right
 468 |4 |`^` |Bitwise XOR |Left-to-right
 469 |5 |`\|` |Bitwise OR |Left-to-right
 470 |6 |`<` |Less than |Left-to-right
 471 |6 |`<=` |Less than or equal to |Left-to-right
 472 |6 |`>` |Greater than |Left-to-right
 473 |6 |`>=` |Greater than or equal to |Left-to-right
 474 |7 |`==` |Equal to |Left-to-right
 475 |7 |`!=` |Not equal to |Left-to-right
 476 |8 |`&&` |Logical AND |Left-to-right
 477 |9 |`\|\|` |Logical OR |Left-to-right
 478 |===
 479 +
 480 Parentheses are supported to bypass the default order.
 481 +
 482 IMPORTANT: Unlike the C{nbsp}language, the bitwise AND and OR operators
 483 (`&` and `|`) in 'EXPR' take precedence over relational operators (`<`,
 484 `<=`, `>`, `>=`, `==`, and `!=`). This means the expression `2 & 2 == 2`
 485 is _true_ while the equivalent C{nbsp}expression is _false_.
 486 +
 487 The arithmetic operators are :not: supported.
 488 +
 489 LTTng first casts all integer constants and fields to signed 64-bit
 490 integers. The representation of negative integers is two's complement.
 491 This means that, for example, the signed 8-bit integer field 0xff (-1)
 492 becomes 0xffffffffffffffff (still -1) once casted.
 493 +
 494 Before a bitwise operator is applied, LTTng casts all its operands to
 495 unsigned 64-bit integers, and then casts the result back to a signed
 496 64-bit integer. For the bitwise NOT operator, it's the equivalent of
 497 this C{nbsp}expression:
 498 +
 499 [source,c]
 500 ----
 501 (int64_t) ~((uint64_t) val)
 502 ----
 503 +
 504 For the binary bitwise operators, it's the equivalent of those
 505 C{nbsp}expressions:
 506 +
 507 [source,c]
 508 ----
 509 (int64_t) ((uint64_t) lhs >> (uint64_t) rhs)
 510 (int64_t) ((uint64_t) lhs << (uint64_t) rhs)
 511 (int64_t) ((uint64_t) lhs & (uint64_t) rhs)
 512 (int64_t) ((uint64_t) lhs ^ (uint64_t) rhs)
 513 (int64_t) ((uint64_t) lhs | (uint64_t) rhs)
 514 ----
 515 +
 516 If the right-hand side of a bitwise shift operator (`<<` and `>>`) is
 517 not in the [0,{nbsp}63] range, then 'EXPR' is _false_.
 518
 519 [NOTE]
 520 ====
 521 Use the man:lttng-track(1) and man:lttng-untrack(1) commands to allow or
 522 disallow processes to record LTTng events based on their attributes
 523 instead of using equivalent statically-known context fields in 'EXPR'
 524 like `$ctx.pid`.
 525
 526 The former method is much more efficient.
 527 ====
 528
 529 'EXPR' examples:
 530
 531 ----------------------------
 532 msg_id == 23 && size >= 2048
 533 ----------------------------
 534
 535 -------------------------------------------------
 536 $ctx.procname == "lttng*" && (!flag || poel < 34)
 537 -------------------------------------------------
 538
 539 ---------------------------------------------------------
 540 $app.my_provider:my_context == 17.34e9 || some_enum >= 14
 541 ---------------------------------------------------------
 542
 543 ---------------------------------------
 544 $ctx.cpu_id == 2 && filename != "*.log"
 545 ---------------------------------------
 546
 547 ------------------------------------------------
 548 eax_reg & 0xff7 == 0x240 && x[4] >> 12 <= 0x1234
 549 ------------------------------------------------
 550
 551
 552 [[er-name]]
 553 Event record name
 554 ~~~~~~~~~~~~~~~~~
 555 When LTTng records an event{nbsp}__E__, the resulting event record has a
 556 name which depends on the instrumentation point type condition (see the
 557 <<inst-point-type-cond,Instrumentation point type condition>> section
 558 above) of the recording event rule which matched{nbsp}__E__:
 559
 560 LTTng tracepoint (option:--kernel/option:--userspace and option:--tracepoint options)::
 561     Full name of the tracepoint from which LTTng creates{nbsp}__E__.
 562 +
 563 Note that the full name of a user space tracepoint is
 564 __PROVIDER__++:++__NAME__, where __PROVIDER__ is the tracepoint provider
 565 name and __NAME__ is the tracepoint name.
 566
 567 `java.util.logging` logging statement (option:--jul and option:--tracepoint options)::
 568     `lttng_jul:event`
 569 +
 570 Such an event record has a string field `logger_name` which contains the
 571 name of the `java.util.logging` logger from which LTTng
 572 creates{nbsp}__E__.
 573
 574 Apache log4j logging statement (option:--log4j and option:--tracepoint options)::
 575     `lttng_log4j:event`
 576 +
 577 Such an event record has a string field `logger_name` which contains the
 578 name of the Apache log4j logger from which LTTng creates{nbsp}__E__.
 579
 580 Python logging statement (option:--python and option:--tracepoint options)::
 581     `lttng_python:event`
 582 +
 583 Such an event record has a string field `logger_name` which contains the
 584 name of the Python logger from which LTTng creates{nbsp}__E__.
 585
 586 Linux system call (option:--kernel and option:--syscall options)::
 587     Entry:::
 588         ++syscall_entry_++__NAME__, where _NAME_ is the name of the
 589         system call from which LTTng creates{nbsp}__E__, without any
 590         `sys_` prefix.
 591
 592     Exit:::
 593         ++syscall_exit_++__NAME__, where _NAME_ is the name of the
 594         system call from which LTTng creates{nbsp}__E__, without any
 595         `sys_` prefix.
 596
 597 Linux kprobe (option:--kernel and option:--probe options)::
 598 Linux user space probe (option:--kernel and option:--userspace-probe options)::
 599     'RECORDNAME' (first non-option argument).
 600
 601 Linux kretprobe (option:--kernel and option:--function options)::
 602     Entry:::
 603         __RECORDNAME__++_entry++
 604
 605     Exit:::
 606         __RECORDNAME__++_exit++
 607
 608
 609 [[enable]]
 610 Enable a disabled recording event rule
 611 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 612 The `enable-event` command can enable a disabled recording event rule,
 613 as listed in the output of the man:lttng-list(1) command.
 614
 615 You may enable a disabled recording event rule regardless of the
 616 activity (started or stopped) of its tracing session (see
 617 man:lttng-start(1) and man:lttng-stop(1)).
 618
 619 To enable a disabled recording event rule, run the `enable-event`
 620 command with the exact same options and arguments that you used to
 621 create it. In particular, with the option:--filter='EXPR' option, 'EXPR'
 622 must be the exact same string as the one you used on creation.
 623
 624
 625 include::common-lttng-cmd-options-head.txt[]
 626
 627
 628 Tracing domain
 629 ~~~~~~~~~~~~~~
 630 One of:
 631
 632 option:-j, option:--jul::
 633     Create or enable recording event rules in the `java.util.logging`
 634     (JUL) tracing domain.
 635
 636 option:-k, option:--kernel::
 637     Create or enable recording event rules in the Linux kernel tracing
 638     domain.
 639
 640 option:-l, option:--log4j::
 641     Create or enable recording event rules in the Apache log4j tracing
 642     domain.
 643
 644 option:-p, option:--python::
 645     Create or enable recording event rules in the Python tracing domain.
 646
 647 option:-u, option:--userspace::
 648     Create or enable recording event rules in the user space tracing
 649     domain.
 650
 651
 652 Recording target
 653 ~~~~~~~~~~~~~~~~
 654 option:-c 'CHANNEL', option:--channel='CHANNEL'::
 655     Create or enable recording event rules attached to the channel named
 656     'CHANNEL' instead of `channel0`.
 657
 658 option:-s 'SESSION', option:--session='SESSION'::
 659     Create or enable recording event rules in the tracing session named
 660     'SESSION' instead of the current tracing session.
 661
 662
 663 Instrumentation point type condition
 664 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 665 See the <<inst-point-type-cond,Instrumentation point type condition>>
 666 section above.
 667
 668 At most one of:
 669
 670 option:--function='LOC'::
 671     Only match Linux kretprobe events.
 672 +
 673 Only available with the option:--kernel option.
 674 +
 675 'LOC' is one of:
 676 +
 677 --
 678 * A function address (`0x` hexadecimal prefix supported).
 679 * A function symbol name.
 680 * A function symbol name and an offset
 681   (__SYMBOL__++pass:[+]++__OFFSET__ format).
 682 --
 683 +
 684 You must specify the event record name with 'RECORDNAME'. See the
 685 <<er-name,Event record name>> section above to learn more.
 686
 687 option:--probe='LOC'::
 688     Only match Linux kprobe events.
 689 +
 690 Only available with the option:--kernel option.
 691 +
 692 'LOC' is one of:
 693 +
 694 --
 695 * An address (`0x` hexadecimal prefix supported).
 696 * A symbol name.
 697 * A symbol name and an offset (__SYMBOL__++pass:[+]++__OFFSET__ format).
 698 --
 699 +
 700 You must specify the event record name with 'RECORDNAME'. See the
 701 <<er-name,Event record name>> section above to learn more.
 702
 703 option:--userspace-probe='LOC'::
 704     Only match Linux user space probe events.
 705 +
 706 Only available with the option:--kernel option.
 707 +
 708 'LOC' is one of:
 709 +
 710 --
 711 \[++elf:++]__PATH__++:++__SYMBOL__::
 712     Probe an available symbol within a user space application or
 713     library.
 714 +
 715 --
 716 'PATH'::
 717     Application or library path.
 718 +
 719 One of:
 720 +
 721 * An absolute path.
 722 * A relative path.
 723 * The name of an application as found in the directories listed in the
 724   `PATH` environment variable.
 725
 726 'SYMBOL'::
 727     Symbol name of the function of which to instrument the entry.
 728 +
 729 'SYMBOL' can be any defined code symbol in the output of the man:nm(1)
 730 command, including with its nloption:--dynamic option, which lists
 731 dynamic symbols.
 732 --
 733 +
 734 As of LTTng{nbsp}{lttng_version}, not specifying `elf:` is equivalent to
 735 specifying it, but this default may change in the future.
 736 +
 737 Examples:
 738 +
 739 * `--userspace-probe=/usr/lib/libc.so.6:malloc`
 740 * `--userspace-probe=./myapp:createUser`
 741 * `--userspace-probe=elf:httpd:ap_run_open_htaccess`
 742
 743 ++sdt:++__PATH__++:++__PROVIDER__++:++__NAME__::
 744     Use a SystemTap User-level Statically Defined Tracing (USDT) probe
 745     within a user space application or library.
 746 +
 747 --
 748 'PATH'::
 749     Application or library path.
 750 +
 751 This can be:
 752 +
 753 * An absolute path.
 754 * A relative path.
 755 * The name of an application as found in the directories listed in the
 756   `PATH` environment variable.
 757
 758 'PROVIDER'::
 759 'NAME'::
 760     USDT provider and probe names.
 761 +
 762 For example, with the following USDT probe:
 763 +
 764 [source,c]
 765 ----
 766 DTRACE_PROBE2("server", "accept_request",
 767               request_id, ip_addr);
 768 ----
 769 +
 770 The provider/probe name pair is `server:accept_request`.
 771 --
 772 +
 773 Example: `--userspace-probe=sdt:./build/server:server:accept_request`
 774 --
 775 +
 776 You must specify the event record name with 'RECORDNAME'. See the
 777 <<er-name,Event record name>> section above to learn more.
 778
 779 option:--syscall::
 780     Only match Linux system call events.
 781 +
 782 Only available with the option:--kernel option.
 783
 784 option:--tracepoint::
 785     Only match:
 786 +
 787 With the option:--kernel or option:--userspace option:::
 788     LTTng tracepoint events.
 789 With the option:--jul, option:--log4j, or option:--python option:::
 790     Logging events.
 791
 792 With the option:--kernel, not specifying any of the instrumentation
 793 point type options is equivalent to specifying the option:--tracepoint
 794 option, but this default may change in the future.
 795
 796 With the option:--userspace, option:--jul, option:--log4j, and
 797 option:--python options, not specifying the option:--tracepoint option
 798 is equivalent to specifying it, but this default may change in the
 799 future.
 800
 801
 802 Event name condition
 803 ~~~~~~~~~~~~~~~~~~~~
 804 See the <<event-name-cond,Event name condition>> section above.
 805
 806 option:-a, option:--all::
 807     Equivalent to a single 'NAME' argument (LTTng tracepoint or logger
 808     name) set to `*` (match anything).
 809 +
 810 You may :not: use this option with a 'NAME' argument.
 811
 812 option:-x 'XNAME'[,'XNAME']..., option:--exclude='XNAME'[,'XNAME']...::
 813     Only match events of which none of the 'XNAME' arguments
 814     matches the full name of the LTTng user space tracepoint.
 815 +
 816 Only available with the option:--userspace option.
 817 +
 818 'XNAME' is a globbing pattern: the `*` character means ``match
 819 anything''. To match a literal `*` character, use :escwc:. To match
 820 a literal `,` character, use :esccomma:.
 821
 822
 823 Instrumentation point log level condition
 824 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 825 See the <<inst-point-log-level-cond,Instrumentation point log level
 826 condition>> section above.
 827
 828 At most one of:
 829
 830 option:--loglevel='LOGLEVEL'::
 831     Only match events of which the log level of the LTTng tracepoint or
 832     logging statement is at least as severe as 'LOGLEVEL'.
 833
 834 option:--loglevel-only='LOGLEVEL'::
 835     Only match events of which the log level of the LTTng tracepoint or
 836     logging statement is exactly 'LOGLEVEL'.
 837
 838 The instrumentation point log level options above are :not: available
 839 with the option:--kernel option.
 840
 841
 842 Event payload and context filter condition
 843 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 844 See the <<filter-cond,Event payload and context filter condition>>
 845 section above.
 846
 847 option:-f 'EXPR', option:--filter='EXPR'::
 848     Only match events of which 'EXPR', which can contain references to
 849     event payload and current context fields, is _true_.
 850 +
 851 This option is only available with the option:--tracepoint or
 852 option:--syscall option.
 853
 854
 855 include::common-lttng-cmd-help-options.txt[]
 856
 857
 858 include::common-lttng-cmd-after-options.txt[]
 859
 860
 861 include::common-footer.txt[]
 862
 863
 864 SEE ALSO
 865 --------
 866 man:lttng(1),
 867 man:lttng-disable-event(1),
 868 man:lttng-enable-channel(1),
 869 man:lttng-list(1),
 870 man:lttng-start(1),
 871 man:lttng-track(1),
 872 man:lttng-concepts(7)