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

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