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