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

   1 lttng-enable-event(1)
   2 =====================
   3 :revdate: 4 April 2019
   4
   5
   6 NAME
   7 ----
   8 lttng-enable-event - Create or enable LTTng event rules
   9
  10
  11 SYNOPSIS
  12 --------
  13 Create or enable Linux kernel event rules:
  14
  15 [verse]
  16 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-event* option:--kernel
  17       [option:--probe='SOURCE' | option:--function='SOURCE' | option:--syscall |
  18        option:--userspace-probe='SOURCE']
  19       [option:--filter='EXPR'] [option:--session='SESSION']
  20       [option:--channel='CHANNEL'] 'EVENT'[,'EVENT']...
  21
  22 Create or enable an "all" Linux kernel event rule:
  23
  24 [verse]
  25 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-event* option:--kernel option:--all [option:--syscall]
  26       [option:--filter='EXPR'] [option:--session='SESSION'] [option:--channel='CHANNEL']
  27
  28 Create or enable application/library event rules:
  29
  30 [verse]
  31 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-event*
  32       (option:--userspace | option:--jul | option:--log4j | option:--python)
  33       [option:--filter='EXPR'] [option:--exclude='EVENT'[,'EVENT']...]
  34       [option:--loglevel='LOGLEVEL' | option:--loglevel-only='LOGLEVEL']
  35       [option:--session='SESSION'] [option:--channel='CHANNEL'] (option:--all | 'EVENT'[,'EVENT']...)
  36
  37
  38 DESCRIPTION
  39 -----------
  40 The `lttng enable-event` command can create a new event rule, or enable
  41 one or more existing and disabled ones.
  42
  43 An event rule created by `lttng enable-event` is a set of conditions
  44 that must be satisfied in order for an actual event to be emitted by an
  45 LTTng tracer when the execution of an application or a library or the
  46 Linux kernel reaches an event source (tracepoint, system call, dynamic
  47 probe). Event sources can be listed with the man:lttng-list(1) command.
  48
  49 The man:lttng-disable-event(1) command can be used to disable
  50 existing event rules.
  51
  52 Event rules are always assigned to a channel when they are created. If
  53 the option:--channel option is omitted, a default channel named
  54 `channel0` is used (and created automatically if it does not exist for
  55 the specified domain in the selected tracing session).
  56
  57 If the option:--session option is omitted, the chosen channel is picked
  58 from the current tracing session.
  59
  60 Events can be enabled while tracing is active
  61 (use man:lttng-start(1) to make a tracing session active).
  62
  63
  64 Event source types
  65 ~~~~~~~~~~~~~~~~~~
  66 Five types of event sources are available in the Linux kernel tracing
  67 domain (option:--kernel option):
  68
  69 Tracepoint (option:--tracepoint option; default)::
  70     A Linux kernel tracepoint, that is, a static instrumentation point
  71     placed in the kernel source code. Standard tracepoints are designed
  72     and placed in the source code by developers and record useful
  73     payload fields.
  74
  75 Dynamic kernel probe (option:--probe option)::
  76     A Linux kernel kprobe, that is, an instrumentation point placed
  77     dynamically in the compiled kernel code. Dynamic probe events do not
  78     record any payload field.
  79
  80 Dynamic user space probe (option:--userspace-probe option)::
  81     A Linux kernel uprobe, that is, an instrumentation point placed
  82     dynamically in the compiled user space application/library through
  83     the kernel. Dynamic user space probe events do not record any
  84     payload field.
  85 +
  86 See the <<userspace-probe,Dynamic user space probes>> section for more
  87 information.
  88
  89 Function probe (option:--function option)::
  90     A Linux kernel kretprobe, that is, two instrumentation points placed
  91     dynamically where a function is entered and where it returns in the
  92     compiled kernel code. Function probe events do not record any
  93     payload field.
  94
  95 System call (option:--syscall option)::
  96     A Linux kernel system call. Two instrumentation points are
  97     statically placed where a system call function is entered and where
  98     it returns in the compiled kernel code. System call event sources
  99     record useful payload fields.
 100
 101 The application tracing domains (option:--userspace, option:--jul,
 102 option:--log4j, or option:--python options) only support tracepoints.
 103 In the cases of the JUL, Apache log4j, and Python domains, the event
 104 names correspond to _logger_ names.
 105
 106
 107 Understanding event rule conditions
 108 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 109 When creating an event rule with `lttng enable-event`, conditions are
 110 specified using options. The logical conjunction (logical AND) of all
 111 those conditions must be true when an event source is reached by an
 112 application or by the Linux kernel in order for an actual event
 113 to be emitted by an LTTng tracer.
 114
 115 Any condition that is not explicitly specified on creation is considered
 116 a _don't care_.
 117
 118 For example, consider the following commands:
 119
 120 [role="term"]
 121 ----
 122 $ lttng enable-event --userspace hello:world
 123 $ lttng enable-event --userspace hello:world --loglevel=TRACE_INFO
 124 ----
 125
 126 Here, two event rules are created. The first one has a single condition:
 127 the tracepoint name must match `hello:world`. The second one has two
 128 conditions:
 129
 130 * The tracepoint name must match `hello:world`, _and_
 131 * The tracepoint's defined log level must be at least as severe as
 132   the `TRACE_INFO` level.
 133
 134 In this case, the second event rule is pointless because the first one
 135 is more general: it does not care about the tracepoint's log level.
 136 If an event source matching both event rules is reached by the
 137 application's execution, only one event is emitted.
 138
 139 The available conditions for the Linux kernel domain are:
 140
 141 * Tracepoint/system call name ('EVENT' argument with option:--tracepoint
 142   or option:--syscall options) or dynamic probe/function name/address
 143   (option:--probe, option:--userspace-probe, and option:--function
 144   option's argument) which must match event source's equivalent.
 145 +
 146 You can use `*` characters at any place in the tracepoint or system
 147 call name as wildcards to match zero or more characters. To use a
 148 literal `*` character, use :escwc:.
 149
 150 * Filter expression (option:--filter option) executed against the
 151   dynamic values of event fields at execution time that must evaluate
 152   to true. See the <<filter-expr,Filter expression>> section
 153   below for more information.
 154
 155 The available conditions for the application domains are:
 156
 157 * Tracepoint name ('EVENT' with option:--tracepoint option) which must
 158   match event source's equivalent.
 159 +
 160 You can use `*` characters at any place in the tracepoint name as
 161 wildcards to match zero or more characters. To use a literal `*`
 162 character, use :escwc:. When you create an event rule with a tracepoint
 163 name containing a wildcard, you can exclude specific tracepoint names
 164 from the match with the option:--exclude option.
 165
 166 * Filter expression (option:--filter option) executed against the
 167   dynamic values of event fields at execution time that must evaluate
 168   to true. See the <<filter-expr,Filter expression>> section
 169   below for more information.
 170 * Event's log level that must be at least as severe as a given
 171   log level (option:--loglevel option) or match exactly a given log
 172   level (option:--loglevel-only option).
 173
 174 When using `lttng enable-event` with a set of conditions that does not
 175 currently exist for the chosen tracing session, domain, and channel,
 176 a new event rule is created. Otherwise, the existing event rule is
 177 enabled if it is currently disabled
 178 (see man:lttng-disable-event(1)).
 179
 180 The option:--all option can be used alongside the option:--tracepoint
 181 or option:--syscall options. When this option is used, no 'EVENT'
 182 argument must be specified. This option defines a single event rule
 183 matching _all_ the possible events of a given tracing domain for the
 184 chosen channel and tracing session. It is the equivalent of an 'EVENT'
 185 argument named `*` (wildcard).
 186
 187
 188 [[filter-expr]]
 189 Filter expression
 190 ~~~~~~~~~~~~~~~~~
 191 A filter expression can be specified with the option:--filter option
 192 when creating a new event rule. If the filter expression evaluates
 193 to true when executed against the dynamic values of an event's fields
 194 when tracing, the filtering condition passes.
 195
 196 NOTE: Make sure to **single-quote** the filter expression when running
 197 the command from a shell, as filter expressions typically include
 198 characters having a special meaning for most shells.
 199
 200 The filter expression syntax is similar to C language conditional
 201 expressions (expressions that can be evaluated by an `if` statement),
 202 albeit with a few differences:
 203
 204 * C integer and floating point number constants are supported, as well
 205   as literal strings between double quotes (`"`). You can use `*`
 206   characters at any place in a literal string as wildcards to match zero
 207   or more characters. To use a literal `*` character, use :escwc:.
 208 +
 209 Examples: `32`, `-0x17`, `0755`, `12.34`,
 210 +"a :escbs:"literal string:escbs:""+, `"src/*/*.h"`.
 211
 212 * The dynamic value of an event field is read by using its name as a C
 213   identifier.
 214 +
 215 The dot and square bracket notations are available, like in the C
 216 language, to access nested structure and array/sequence fields.
 217 Only a constant, positive integer number can be used within square
 218 brackets. If the index is out of bounds, the whole filter expression
 219 evaluates to false (the event is discarded).
 220 +
 221 An enumeration field's value is an integer.
 222 +
 223 When the expression's field does not exist, the whole filter expression
 224 evaluates to false.
 225 +
 226 Examples: `my_field`, `target_cpu`, `seq[7]`, `msg.user[1].data[2][17]`.
 227
 228 * The dynamic value of a statically-known context field is read by
 229   prefixing its name with `$ctx.`. Statically-known context fields are
 230   context fields added to channels without the `$app.` prefix using the
 231   man:lttng-add-context(1) command.
 232 +
 233 When the expression's statically-known context field does not exist,
 234 the whole filter expression evaluates to false.
 235 +
 236 Examples: `$ctx.prio`, `$ctx.preemptible`,
 237 `$ctx.perf:cpu:stalled-cycles-frontend`.
 238
 239 * The dynamic value of an application-specific context field is read by
 240   prefixing its name with `$app.` (follows the format used to add such a
 241   context field with the man:lttng-add-context(1) command).
 242 +
 243 When the expression's application-specific context field does not exist,
 244 the whole filter expression evaluates to false.
 245 +
 246 Example: `$app.server:cur_user`.
 247
 248 The following precedence table shows the operators which are supported
 249 in a filter expression. In this table, the highest precedence is 1.
 250 Parentheses are supported to bypass the default order.
 251
 252 IMPORTANT: Unlike the C language, the `lttng enable-event` filter
 253 expression syntax's bitwise AND and OR operators (`&` and `|`) take
 254 precedence over relational operators (`<`, `<=`, `>`, `>=`, `==`, and
 255 `!=`). This means the filter expression `2 & 2 == 2` is true while the
 256 equivalent C expression is false.
 257
 258 [options="header"]
 259 |===
 260 |Precedence |Operator |Description |Associativity
 261 |1 |`-` |Unary minus |Right-to-left
 262 |1 |`+` |Unary plus |Right-to-left
 263 |1 |`!` |Logical NOT |Right-to-left
 264 |1 |`~` |Bitwise NOT |Right-to-left
 265 |2 |`<<` |Bitwise left shift |Left-to-right
 266 |2 |`>>` |Bitwise right shift |Left-to-right
 267 |3 |`&` |Bitwise AND |Left-to-right
 268 |4 |`^` |Bitwise XOR |Left-to-right
 269 |5 |`\|` |Bitwise OR |Left-to-right
 270 |6 |`<` |Less than |Left-to-right
 271 |6 |`<=` |Less than or equal to |Left-to-right
 272 |6 |`>` |Greater than |Left-to-right
 273 |6 |`>=` |Greater than or equal to |Left-to-right
 274 |7 |`==` |Equal to |Left-to-right
 275 |7 |`!=` |Not equal to |Left-to-right
 276 |8 |`&&` |Logical AND |Left-to-right
 277 |9 |`\|\|` |Logical OR |Left-to-right
 278 |===
 279
 280 The arithmetic operators are :not: supported.
 281
 282 All integer constants and fields are first casted to signed 64-bit
 283 integers. The representation of negative integers is two's complement.
 284 This means that, for example, the signed 8-bit integer field 0xff (-1)
 285 becomes 0xffffffffffffffff (still -1) once casted.
 286
 287 Before a bitwise operator is applied, all its operands are casted to
 288 unsigned 64-bit integers, and the result is casted back to a signed
 289 64-bit integer. For the bitwise NOT operator, it is the equivalent of
 290 this C expression:
 291
 292 [source,c]
 293 ----
 294 (int64_t) ~((uint64_t) val)
 295 ----
 296
 297 For the binary bitwise operators, it is the equivalent of those C
 298 expressions:
 299
 300 [source,c]
 301 ----
 302 (int64_t) ((uint64_t) lhs >> (uint64_t) rhs)
 303 (int64_t) ((uint64_t) lhs << (uint64_t) rhs)
 304 (int64_t) ((uint64_t) lhs & (uint64_t) rhs)
 305 (int64_t) ((uint64_t) lhs ^ (uint64_t) rhs)
 306 (int64_t) ((uint64_t) lhs | (uint64_t) rhs)
 307 ----
 308
 309 If the right-hand side of a bitwise shift operator (`<<` and `>>`) is
 310 not in the [0,{nbsp}63] range, the whole filter expression evaluates to
 311 false.
 312
 313 NOTE: Although it is possible to filter the process ID of an event when
 314 the `pid` context has been added to its channel using, for example,
 315 `$ctx.pid == 2832`, it is recommended to use the PID tracker instead,
 316 which is much more efficient (see man:lttng-track(1)).
 317
 318 Filter expression examples:
 319
 320 ----------------------------
 321 msg_id == 23 && size >= 2048
 322 ----------------------------
 323
 324 -------------------------------------------------
 325 $ctx.procname == "lttng*" && (!flag || poel < 34)
 326 -------------------------------------------------
 327
 328 ---------------------------------------------------------
 329 $app.my_provider:my_context == 17.34e9 || some_enum >= 14
 330 ---------------------------------------------------------
 331
 332 ---------------------------------------
 333 $ctx.cpu_id == 2 && filename != "*.log"
 334 ---------------------------------------
 335
 336 ------------------------------------------------
 337 eax_reg & 0xff7 == 0x240 && x[4] >> 12 <= 0x1234
 338 ------------------------------------------------
 339
 340
 341 [[log-levels]]
 342 Log levels
 343 ~~~~~~~~~~
 344 Tracepoints and log statements in applications have an attached log
 345 level. Application event rules can contain a _log level_ condition.
 346
 347 With the option:--loglevel option, the event source's log level must
 348 be at least as severe as the option's argument. With the
 349 option:--loglevel-only option, the event source's log level must match
 350 the option's argument.
 351
 352 The available log levels are:
 353
 354 User space domain (option:--userspace option)::
 355     Shortcuts such as `system` are allowed.
 356 +
 357 * `TRACE_EMERG` (0)
 358 * `TRACE_ALERT` (1)
 359 * `TRACE_CRIT` (2)
 360 * `TRACE_ERR` (3)
 361 * `TRACE_WARNING` (4)
 362 * `TRACE_NOTICE` (5)
 363 * `TRACE_INFO` (6)
 364 * `TRACE_DEBUG_SYSTEM` (7)
 365 * `TRACE_DEBUG_PROGRAM` (8)
 366 * `TRACE_DEBUG_PROCESS` (9)
 367 * `TRACE_DEBUG_MODULE` (10)
 368 * `TRACE_DEBUG_UNIT` (11)
 369 * `TRACE_DEBUG_FUNCTION` (12)
 370 * `TRACE_DEBUG_LINE` (13)
 371 * `TRACE_DEBUG` (14)
 372
 373 `java.util.logging` domain (option:--jul option)::
 374     Shortcuts such as `severe` are allowed.
 375 +
 376 * `JUL_OFF` (`INT32_MAX`)
 377 * `JUL_SEVERE` (1000)
 378 * `JUL_WARNING` (900)
 379 * `JUL_INFO` (800)
 380 * `JUL_CONFIG` (700)
 381 * `JUL_FINE` (500)
 382 * `JUL_FINER` (400)
 383 * `JUL_FINEST` (300)
 384 * `JUL_ALL` (`INT32_MIN`)
 385
 386 Apache log4j domain (option:--log4j option)::
 387     Shortcuts such as `severe` are allowed.
 388 +
 389 * `LOG4J_OFF` (`INT32_MAX`)
 390 * `LOG4J_FATAL` (50000)
 391 * `LOG4J_ERROR` (40000)
 392 * `LOG4J_WARN` (30000)
 393 * `LOG4J_INFO` (20000)
 394 * `LOG4J_DEBUG` (10000)
 395 * `LOG4J_TRACE` (5000)
 396 * `LOG4J_ALL` (`INT32_MIN`)
 397
 398 Python domain (option:--python option)::
 399     Shortcuts such as `critical` are allowed.
 400 +
 401 * `PYTHON_CRITICAL` (50)
 402 * `PYTHON_ERROR` (40)
 403 * `PYTHON_WARNING` (30)
 404 * `PYTHON_INFO` (20)
 405 * `PYTHON_DEBUG` (10)
 406 * `PYTHON_NOTSET` (0)
 407
 408
 409 [[userspace-probe]]
 410 Dynamic user space probes
 411 ~~~~~~~~~~~~~~~~~~~~~~~~~
 412 With the option:--userspace-probe option, you can instrument function
 413 entries of any user space binary (application or library) using either
 414 an available symbol name or a SystemTap User-level Statically Defined
 415 Tracing (USDT, a DTrace-style marker) probe's provider and probe names.
 416 As of this version, only USDT probes that are :not: surrounded by a
 417 reference counter (semaphore) are supported.
 418
 419 The option:--userspace-probe option must be specified with the
 420 option:--kernel option because it uses Linux's uprobe feature to
 421 dynamically instrument a user space application or library.
 422
 423 As of this version, dynamic probe events do not record any payload
 424 field.
 425
 426
 427 include::common-cmd-options-head.txt[]
 428
 429
 430 Domain
 431 ~~~~~~
 432 One of:
 433
 434 option:-j, option:--jul::
 435     Create or enable event rules in the `java.util.logging`
 436     (JUL) domain.
 437
 438 option:-k, option:--kernel::
 439     Create or enable event rules in the Linux kernel domain.
 440
 441 option:-l, option:--log4j::
 442     Create or enable event rules in the Apache log4j domain.
 443
 444 option:-p, option:--python::
 445     Create or enable event rules in the Python domain.
 446
 447 option:-u, option:--userspace::
 448     Create or enable event rules in the user space domain.
 449
 450
 451 Target
 452 ~~~~~~
 453 option:-c 'CHANNEL', option:--channel='CHANNEL'::
 454     Create or enable event rules in the channel named 'CHANNEL' instead
 455     of the default channel name `channel0`.
 456
 457 option:-s 'SESSION', option:--session='SESSION'::
 458     Create or enable event rules in the tracing session named 'SESSION'
 459     instead of the current tracing session.
 460
 461
 462 Event source type
 463 ~~~~~~~~~~~~~~~~~
 464 One of:
 465
 466 option:--function='SOURCE'::
 467     Dynamic kernel return probe (kretprobe). Only available with the
 468     option:--kernel domain option. 'SOURCE' is one of:
 469 +
 470 * Function address (`0x` prefix supported)
 471 * Function symbol name
 472 * Function symbol name and offset (__SYMBOL__++pass:[+]++__OFFSET__ format)
 473
 474 option:--probe='SOURCE'::
 475     Dynamic kernel probe (kprobe). Only available with the
 476     option:--kernel domain option. 'SOURCE' is one of:
 477 +
 478 * Address (`0x` prefix supported)
 479 * Symbol nane
 480 * Symbol name and offset (__SYMBOL__++pass:[+]++__OFFSET__ format)
 481
 482 option:--userspace-probe='SOURCE'::
 483     Dynamic user space probe (uprobe). Only available with the
 484     option:--kernel domain option. See the
 485     <<userspace-probe,Dynamic user space probes>> section.
 486 +
 487 'SOURCE' is one of:
 488 +
 489 --
 490 \[++elf:++]__PATH__++:++__SYMBOL__::
 491     Dynamically instrument an available symbol within a user space
 492     application or library.
 493 +
 494 --
 495 'PATH'::
 496     Application or library path.
 497 +
 498 This can be:
 499 +
 500 * An absolute path.
 501 * A relative path.
 502 * An application's name as found in the directories listed in the
 503   `PATH` environment variable.
 504
 505 'SYMBOL'::
 506     Symbol name of the function of which to instrument the entry.
 507 +
 508 This can be any defined code symbol listed by the man:nm(1) command
 509 (including with its nloption:--dynamic option which lists dynamic
 510 symbols).
 511 --
 512 +
 513 As of this version, not specifying `elf:` is equivalent to specifying
 514 it.
 515 +
 516 Examples:
 517 +
 518 * `--userspace-probe=/usr/lib/libc.so.6:malloc`
 519 * `--userspace-probe=./myapp:createUser`
 520 * `--userspace-probe=httpd:ap_run_open_htaccess`
 521
 522 ++sdt:++__PATH__++:++__PROVIDER__++:++__NAME__::
 523     Dynamically instrument a USDT probe within a user space application
 524     or library.
 525 +
 526 --
 527 'PATH'::
 528     Application or library path.
 529 +
 530 This can be:
 531 +
 532 * An absolute path.
 533 * A relative path.
 534 * An application's name as found in the directories listed in the
 535   `PATH` environment variable.
 536
 537 __PROVIDER__++:++__NAME__::
 538     USDT provider and probe names.
 539 +
 540 For example, with the following USDT probe:
 541 +
 542 [source,c]
 543 ----
 544 DTRACE_PROBE2("server", "accept_request",
 545               request_id, ip_addr);
 546 ----
 547 +
 548 The provider/probe name pair is `server:accept_request`.
 549 --
 550 +
 551 Example:
 552 +
 553 * `--userspace-probe=sdt:./build/server:server:accept_request`
 554 --
 555
 556 option:--syscall::
 557     Linux kernel system call. Only available with the option:--kernel
 558     domain option.
 559
 560 option:--tracepoint::
 561     Linux kernel or application tracepoint (default).
 562
 563
 564 Log level
 565 ~~~~~~~~~
 566 One of:
 567
 568 option:--loglevel='LOGLEVEL'::
 569     Add log level condition to the event rule: the event source's
 570     defined log level must be at least as severe as 'LOGLEVEL'.
 571     See the <<log-levels,Log levels>> section above for the available
 572     log levels. Only available with application domains.
 573
 574 option:--loglevel-only='LOGLEVEL'::
 575     Add log level condition to the event rule: the event source's
 576     defined log level must match 'LOGLEVEL'. See the
 577     <<log-levels,Log levels>> section above for the available log
 578     levels. Only available with application domains.
 579
 580
 581 Filtering and exclusion
 582 ~~~~~~~~~~~~~~~~~~~~~~~
 583 option:-x 'EVENT'[,'EVENT']..., option:--exclude='EVENT'[,'EVENT']...::
 584     Exclude events named 'EVENT' from the event rule. This option
 585     can be used when the command's 'EVENT' argument contains at least
 586     one wildcard star (`*`) to exclude specific names. 'EVENT' can also
 587     contain wildcard stars. To use a
 588     literal `,` character, use :esccomma:.
 589     Only available with the option:--userspace domain.
 590
 591 option:-f 'EXPR', option:--filter='EXPR'::
 592     Add filter expression condition to the event rule. Expression 'EXPR'
 593     must evaluate to true when executed against the dynamic values of
 594     event fields. See the <<filter-expr,Filter expression>>
 595     section above for more information.
 596
 597
 598 Shortcuts
 599 ~~~~~~~~~
 600 option:-a, option:--all::
 601     Equivalent to an 'EVENT' argument named `*` (wildcard) when also
 602     using the option:--tracepoint (default) or option:--syscall option.
 603
 604
 605 include::common-cmd-help-options.txt[]
 606
 607
 608 include::common-cmd-footer.txt[]
 609
 610
 611 SEE ALSO
 612 --------
 613 man:lttng-disable-event(1),
 614 man:lttng(1)