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