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