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