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