doc/man/lttng-event-rule.7.txt

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