| 1 | lttng-enable-event(1) |
| 2 | ===================== |
| 3 | |
| 4 | |
| 5 | NAME |
| 6 | ---- |
| 7 | lttng-enable-event - Create or enable LTTng event rules |
| 8 | |
| 9 | |
| 10 | SYNOPSIS |
| 11 | -------- |
| 12 | Create or enable Linux kernel event rules: |
| 13 | |
| 14 | [verse] |
| 15 | *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-event* option:--kernel |
| 16 | [option:--probe='SOURCE' | option:--function='SOURCE' | option:--syscall | |
| 17 | option:--userspace-probe='SOURCE'] |
| 18 | [option:--filter='EXPR'] [option:--session='SESSION'] |
| 19 | [option:--channel='CHANNEL'] 'EVENT'[,'EVENT']... |
| 20 | |
| 21 | Create or enable an "all" Linux kernel event rule: |
| 22 | |
| 23 | [verse] |
| 24 | *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-event* option:--kernel option:--all [option:--syscall] |
| 25 | [option:--filter='EXPR'] [option:--session='SESSION'] [option:--channel='CHANNEL'] |
| 26 | |
| 27 | Create or enable application/library event rules: |
| 28 | |
| 29 | [verse] |
| 30 | *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-event* |
| 31 | (option:--userspace | option:--jul | option:--log4j | option:--python) |
| 32 | [option:--filter='EXPR'] [option:--exclude='EVENT'[,'EVENT']...] |
| 33 | [option:--loglevel='LOGLEVEL' | option:--loglevel-only='LOGLEVEL'] |
| 34 | [option:--session='SESSION'] [option:--channel='CHANNEL'] (option:--all | 'EVENT'[,'EVENT']...) |
| 35 | |
| 36 | |
| 37 | DESCRIPTION |
| 38 | ----------- |
| 39 | The `lttng enable-event` command can create a new event rule, or enable |
| 40 | one or more existing and disabled ones. |
| 41 | |
| 42 | An event rule created by `lttng enable-event` is a set of conditions |
| 43 | that must be satisfied in order for an actual event to be emitted by an |
| 44 | LTTng tracer when the execution of an application or a library or the |
| 45 | Linux kernel reaches an event source (tracepoint, system call, dynamic |
| 46 | probe). Event sources can be listed with the man:lttng-list(1) command. |
| 47 | |
| 48 | The man:lttng-disable-event(1) command can be used to disable |
| 49 | existing event rules. |
| 50 | |
| 51 | Event rules are always assigned to a channel when they are created. If |
| 52 | the option:--channel option is omitted, a default channel named |
| 53 | `channel0` is used (and created automatically if it does not exist for |
| 54 | the specified domain in the selected tracing session). |
| 55 | |
| 56 | If the option:--session option is omitted, the chosen channel is picked |
| 57 | from the current tracing session. |
| 58 | |
| 59 | Events can be enabled while tracing is active |
| 60 | (use man:lttng-start(1) to make a tracing session active). |
| 61 | |
| 62 | |
| 63 | Event source types |
| 64 | ~~~~~~~~~~~~~~~~~~ |
| 65 | Five types of event sources are available in the Linux kernel tracing |
| 66 | domain (option:--kernel option): |
| 67 | |
| 68 | Tracepoint (option:--tracepoint option; default):: |
| 69 | A Linux kernel tracepoint, that is, a static instrumentation point |
| 70 | placed in the kernel source code. Standard tracepoints are designed |
| 71 | and placed in the source code by developers and record useful |
| 72 | payload fields. |
| 73 | |
| 74 | Dynamic kernel probe (option:--probe option):: |
| 75 | A Linux kernel kprobe, that is, an instrumentation point placed |
| 76 | dynamically in the compiled kernel code. Dynamic probe events do not |
| 77 | record any payload field. |
| 78 | |
| 79 | Dynamic user space probe (option:--userspace-probe option):: |
| 80 | A Linux kernel uprobe, that is, an instrumentation point placed |
| 81 | dynamically in the compiled user space application/library through |
| 82 | the kernel. Dynamic user space probe events do not record any |
| 83 | payload field. |
| 84 | + |
| 85 | See the <<userspace-probe,Dynamic user space probes>> section for more |
| 86 | information. |
| 87 | |
| 88 | Function probe (option:--function option):: |
| 89 | A Linux kernel kretprobe, that is, two instrumentation points placed |
| 90 | dynamically where a function is entered and where it returns in the |
| 91 | compiled kernel code. Function probe events do not record any |
| 92 | payload field. |
| 93 | |
| 94 | System call (option:--syscall option):: |
| 95 | A Linux kernel system call. Two instrumentation points are |
| 96 | statically placed where a system call function is entered and where |
| 97 | it returns in the compiled kernel code. System call event sources |
| 98 | record useful payload fields. |
| 99 | |
| 100 | The application tracing domains (option:--userspace, option:--jul, |
| 101 | option:--log4j, or option:--python options) only support tracepoints. |
| 102 | In the cases of the JUL, Apache log4j, and Python domains, the event |
| 103 | names correspond to _logger_ names. |
| 104 | |
| 105 | |
| 106 | Understanding event rule conditions |
| 107 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 108 | When creating an event rule with `lttng enable-event`, conditions are |
| 109 | specified using options. The logical conjunction (logical AND) of all |
| 110 | those conditions must be true when an event source is reached by an |
| 111 | application or by the Linux kernel in order for an actual event |
| 112 | to be emitted by an LTTng tracer. |
| 113 | |
| 114 | Any condition that is not explicitly specified on creation is considered |
| 115 | a _don't care_. |
| 116 | |
| 117 | For example, consider the following commands: |
| 118 | |
| 119 | [role="term"] |
| 120 | ---- |
| 121 | $ lttng enable-event --userspace hello:world |
| 122 | $ lttng enable-event --userspace hello:world --loglevel=TRACE_INFO |
| 123 | ---- |
| 124 | |
| 125 | Here, two event rules are created. The first one has a single condition: |
| 126 | the tracepoint name must match `hello:world`. The second one has two |
| 127 | conditions: |
| 128 | |
| 129 | * The tracepoint name must match `hello:world`, _and_ |
| 130 | * The tracepoint's defined log level must be at least as severe as |
| 131 | the `TRACE_INFO` level. |
| 132 | |
| 133 | In this case, the second event rule is pointless because the first one |
| 134 | is more general: it does not care about the tracepoint's log level. |
| 135 | If an event source matching both event rules is reached by the |
| 136 | application's execution, only one event is emitted. |
| 137 | |
| 138 | The available conditions for the Linux kernel domain are: |
| 139 | |
| 140 | * Tracepoint/system call name ('EVENT' argument with option:--tracepoint |
| 141 | or option:--syscall options) or dynamic probe/function name/address |
| 142 | (option:--probe, option:--userspace-probe, and option:--function |
| 143 | option's argument) which must match event source's equivalent. |
| 144 | + |
| 145 | You can use `*` characters at any place in the tracepoint or system |
| 146 | call name as wildcards to match zero or more characters. To use a |
| 147 | literal `*` character, use :escwc:. |
| 148 | |
| 149 | * Filter expression (option:--filter option) executed against the |
| 150 | dynamic values of event fields at execution time that must evaluate |
| 151 | to true. See the <<filter-expr,Filter expression>> section |
| 152 | below for more information. |
| 153 | |
| 154 | The available conditions for the application domains are: |
| 155 | |
| 156 | * Tracepoint name ('EVENT' with option:--tracepoint option) which must |
| 157 | match event source's equivalent. |
| 158 | + |
| 159 | You can use `*` characters at any place in the tracepoint name as |
| 160 | wildcards to match zero or more characters. To use a literal `*` |
| 161 | character, use :escwc:. When you create an event rule with a tracepoint |
| 162 | name containing a wildcard, you can exclude specific tracepoint names |
| 163 | from the match with the option:--exclude option. |
| 164 | |
| 165 | * Filter expression (option:--filter option) executed against the |
| 166 | dynamic values of event fields at execution time that must evaluate |
| 167 | to true. See the <<filter-expr,Filter expression>> section |
| 168 | below for more information. |
| 169 | * Event's log level that must be at least as severe as a given |
| 170 | log level (option:--loglevel option) or match exactly a given log |
| 171 | level (option:--loglevel-only option). |
| 172 | |
| 173 | When using `lttng enable-event` with a set of conditions that does not |
| 174 | currently exist for the chosen tracing session, domain, and channel, |
| 175 | a new event rule is created. Otherwise, the existing event rule is |
| 176 | enabled if it is currently disabled |
| 177 | (see man:lttng-disable-event(1)). |
| 178 | |
| 179 | The option:--all option can be used alongside the option:--tracepoint |
| 180 | or option:--syscall options. When this option is used, no 'EVENT' |
| 181 | argument must be specified. This option defines a single event rule |
| 182 | matching _all_ the possible events of a given tracing domain for the |
| 183 | chosen channel and tracing session. It is the equivalent of an 'EVENT' |
| 184 | argument named `*` (wildcard). |
| 185 | |
| 186 | |
| 187 | [[filter-expr]] |
| 188 | Filter expression |
| 189 | ~~~~~~~~~~~~~~~~~ |
| 190 | A filter expression can be specified with the option:--filter option |
| 191 | when creating a new event rule. If the filter expression evaluates |
| 192 | to true when executed against the dynamic values of an event's fields |
| 193 | when tracing, the filtering condition passes. |
| 194 | |
| 195 | NOTE: Make sure to **single-quote** the filter expression when running |
| 196 | the command from a shell, as filter expressions typically include |
| 197 | characters having a special meaning for most shells. |
| 198 | |
| 199 | The filter expression syntax is similar to C language conditional |
| 200 | expressions (expressions that can be evaluated by an `if` statement), |
| 201 | albeit with a few differences: |
| 202 | |
| 203 | * C integer and floating point number constants are supported, as well |
| 204 | as literal strings between double quotes (`"`). You can use `*` |
| 205 | characters at any place in a literal string as wildcards to match zero |
| 206 | or more characters. To use a literal `*` character, use :escwc:. |
| 207 | + |
| 208 | Examples: `32`, `-0x17`, `0755`, `12.34`, |
| 209 | +"a :escbs:"literal string:escbs:""+, `"src/*/*.h"`. |
| 210 | |
| 211 | * The dynamic value of an event field is read by using its name as a C |
| 212 | identifier. |
| 213 | + |
| 214 | The dot and square bracket notations are available, like in the C |
| 215 | language, to access nested structure and array/sequence fields. |
| 216 | Only a constant, positive integer number can be used within square |
| 217 | brackets. If the index is out of bounds, the whole filter expression |
| 218 | evaluates to false (the event is discarded). |
| 219 | + |
| 220 | An enumeration field's value is an integer. |
| 221 | + |
| 222 | When the expression's field does not exist, the whole filter expression |
| 223 | evaluates to false. |
| 224 | + |
| 225 | Examples: `my_field`, `target_cpu`, `seq[7]`, `msg.user[1].data[2][17]`. |
| 226 | |
| 227 | * The dynamic value of a statically-known context field is read by |
| 228 | prefixing its name with `$ctx.`. Statically-known context fields are |
| 229 | context fields added to channels without the `$app.` prefix using the |
| 230 | man:lttng-add-context(1) command. |
| 231 | + |
| 232 | When the expression's statically-known context field does not exist, |
| 233 | the whole filter expression evaluates to false. |
| 234 | + |
| 235 | Examples: `$ctx.prio`, `$ctx.preemptible`, |
| 236 | `$ctx.perf:cpu:stalled-cycles-frontend`. |
| 237 | |
| 238 | * The dynamic value of an application-specific context field is read by |
| 239 | prefixing its name with `$app.` (follows the format used to add such a |
| 240 | context field with the man:lttng-add-context(1) command). |
| 241 | + |
| 242 | When the expression's application-specific context field does not exist, |
| 243 | the whole filter expression evaluates to false. |
| 244 | + |
| 245 | Example: `$app.server:cur_user`. |
| 246 | |
| 247 | The following precedence table shows the operators which are supported |
| 248 | in a filter expression. In this table, the highest precedence is 1. |
| 249 | Parentheses are supported to bypass the default order. |
| 250 | |
| 251 | IMPORTANT: Unlike the C language, the `lttng enable-event` filter |
| 252 | expression syntax's bitwise AND and OR operators (`&` and `|`) take |
| 253 | precedence over relational operators (`<`, `<=`, `>`, `>=`, `==`, and |
| 254 | `!=`). This means the filter expression `2 & 2 == 2` is true while the |
| 255 | equivalent C expression is false. |
| 256 | |
| 257 | [options="header"] |
| 258 | |=== |
| 259 | |Precedence |Operator |Description |Associativity |
| 260 | |1 |`-` |Unary minus |Right-to-left |
| 261 | |1 |`+` |Unary plus |Right-to-left |
| 262 | |1 |`!` |Logical NOT |Right-to-left |
| 263 | |1 |`~` |Bitwise NOT |Right-to-left |
| 264 | |2 |`<<` |Bitwise left shift |Left-to-right |
| 265 | |2 |`>>` |Bitwise right shift |Left-to-right |
| 266 | |3 |`&` |Bitwise AND |Left-to-right |
| 267 | |4 |`^` |Bitwise XOR |Left-to-right |
| 268 | |5 |`\|` |Bitwise OR |Left-to-right |
| 269 | |6 |`<` |Less than |Left-to-right |
| 270 | |6 |`<=` |Less than or equal to |Left-to-right |
| 271 | |6 |`>` |Greater than |Left-to-right |
| 272 | |6 |`>=` |Greater than or equal to |Left-to-right |
| 273 | |7 |`==` |Equal to |Left-to-right |
| 274 | |7 |`!=` |Not equal to |Left-to-right |
| 275 | |8 |`&&` |Logical AND |Left-to-right |
| 276 | |9 |`\|\|` |Logical OR |Left-to-right |
| 277 | |=== |
| 278 | |
| 279 | The arithmetic operators are :not: supported. |
| 280 | |
| 281 | All integer constants and fields are first casted to signed 64-bit |
| 282 | integers. The representation of negative integers is two's complement. |
| 283 | This means that, for example, the signed 8-bit integer field 0xff (-1) |
| 284 | becomes 0xffffffffffffffff (still -1) once casted. |
| 285 | |
| 286 | Before a bitwise operator is applied, all its operands are casted to |
| 287 | unsigned 64-bit integers, and the result is casted back to a signed |
| 288 | 64-bit integer. For the bitwise NOT operator, it is the equivalent of |
| 289 | this C expression: |
| 290 | |
| 291 | [source,c] |
| 292 | ---- |
| 293 | (int64_t) ~((uint64_t) val) |
| 294 | ---- |
| 295 | |
| 296 | For the binary bitwise operators, it is the equivalent of those C |
| 297 | expressions: |
| 298 | |
| 299 | [source,c] |
| 300 | ---- |
| 301 | (int64_t) ((uint64_t) lhs >> (uint64_t) rhs) |
| 302 | (int64_t) ((uint64_t) lhs << (uint64_t) rhs) |
| 303 | (int64_t) ((uint64_t) lhs & (uint64_t) rhs) |
| 304 | (int64_t) ((uint64_t) lhs ^ (uint64_t) rhs) |
| 305 | (int64_t) ((uint64_t) lhs | (uint64_t) rhs) |
| 306 | ---- |
| 307 | |
| 308 | If the right-hand side of a bitwise shift operator (`<<` and `>>`) is |
| 309 | not in the [0,{nbsp}63] range, the whole filter expression evaluates to |
| 310 | false. |
| 311 | |
| 312 | NOTE: Although it is possible to filter the process ID of an event when |
| 313 | the `pid` context has been added to its channel using, for example, |
| 314 | `$ctx.pid == 2832`, it is recommended to use the PID tracker instead, |
| 315 | which is much more efficient (see man:lttng-track(1)). |
| 316 | |
| 317 | Filter expression examples: |
| 318 | |
| 319 | ---------------------------- |
| 320 | msg_id == 23 && size >= 2048 |
| 321 | ---------------------------- |
| 322 | |
| 323 | ------------------------------------------------- |
| 324 | $ctx.procname == "lttng*" && (!flag || poel < 34) |
| 325 | ------------------------------------------------- |
| 326 | |
| 327 | --------------------------------------------------------- |
| 328 | $app.my_provider:my_context == 17.34e9 || some_enum >= 14 |
| 329 | --------------------------------------------------------- |
| 330 | |
| 331 | --------------------------------------- |
| 332 | $ctx.cpu_id == 2 && filename != "*.log" |
| 333 | --------------------------------------- |
| 334 | |
| 335 | ------------------------------------------------ |
| 336 | eax_reg & 0xff7 == 0x240 && x[4] >> 12 <= 0x1234 |
| 337 | ------------------------------------------------ |
| 338 | |
| 339 | |
| 340 | [[log-levels]] |
| 341 | Log levels |
| 342 | ~~~~~~~~~~ |
| 343 | Tracepoints and log statements in applications have an attached log |
| 344 | level. Application event rules can contain a _log level_ condition. |
| 345 | |
| 346 | With the option:--loglevel option, the event source's log level must |
| 347 | be at least as severe as the option's argument. With the |
| 348 | option:--loglevel-only option, the event source's log level must match |
| 349 | the option's argument. |
| 350 | |
| 351 | The available log levels are: |
| 352 | |
| 353 | User space domain (option:--userspace option):: |
| 354 | Shortcuts such as `system` are allowed. |
| 355 | + |
| 356 | * `TRACE_EMERG` (0) |
| 357 | * `TRACE_ALERT` (1) |
| 358 | * `TRACE_CRIT` (2) |
| 359 | * `TRACE_ERR` (3) |
| 360 | * `TRACE_WARNING` (4) |
| 361 | * `TRACE_NOTICE` (5) |
| 362 | * `TRACE_INFO` (6) |
| 363 | * `TRACE_DEBUG_SYSTEM` (7) |
| 364 | * `TRACE_DEBUG_PROGRAM` (8) |
| 365 | * `TRACE_DEBUG_PROCESS` (9) |
| 366 | * `TRACE_DEBUG_MODULE` (10) |
| 367 | * `TRACE_DEBUG_UNIT` (11) |
| 368 | * `TRACE_DEBUG_FUNCTION` (12) |
| 369 | * `TRACE_DEBUG_LINE` (13) |
| 370 | * `TRACE_DEBUG` (14) |
| 371 | |
| 372 | `java.util.logging` domain (option:--jul option):: |
| 373 | Shortcuts such as `severe` are allowed. |
| 374 | + |
| 375 | * `JUL_OFF` (`INT32_MAX`) |
| 376 | * `JUL_SEVERE` (1000) |
| 377 | * `JUL_WARNING` (900) |
| 378 | * `JUL_INFO` (800) |
| 379 | * `JUL_CONFIG` (700) |
| 380 | * `JUL_FINE` (500) |
| 381 | * `JUL_FINER` (400) |
| 382 | * `JUL_FINEST` (300) |
| 383 | * `JUL_ALL` (`INT32_MIN`) |
| 384 | |
| 385 | Apache log4j domain (option:--log4j option):: |
| 386 | Shortcuts such as `severe` are allowed. |
| 387 | + |
| 388 | * `LOG4J_OFF` (`INT32_MAX`) |
| 389 | * `LOG4J_FATAL` (50000) |
| 390 | * `LOG4J_ERROR` (40000) |
| 391 | * `LOG4J_WARN` (30000) |
| 392 | * `LOG4J_INFO` (20000) |
| 393 | * `LOG4J_DEBUG` (10000) |
| 394 | * `LOG4J_TRACE` (5000) |
| 395 | * `LOG4J_ALL` (`INT32_MIN`) |
| 396 | |
| 397 | Python domain (option:--python option):: |
| 398 | Shortcuts such as `critical` are allowed. |
| 399 | + |
| 400 | * `PYTHON_CRITICAL` (50) |
| 401 | * `PYTHON_ERROR` (40) |
| 402 | * `PYTHON_WARNING` (30) |
| 403 | * `PYTHON_INFO` (20) |
| 404 | * `PYTHON_DEBUG` (10) |
| 405 | * `PYTHON_NOTSET` (0) |
| 406 | |
| 407 | |
| 408 | [[userspace-probe]] |
| 409 | Dynamic user space probes |
| 410 | ~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 411 | With the option:--userspace-probe option, you can instrument function |
| 412 | entries of any user space binary (application or library) using either |
| 413 | an available symbol name or a SystemTap SDT probe's provider and probe |
| 414 | names. |
| 415 | |
| 416 | The option:--userspace-probe option must be specified with the |
| 417 | option:--kernel option because it uses Linux's uprobe feature to |
| 418 | dynamically instrument a user space application or library. |
| 419 | |
| 420 | As of this version, dynamic probe events do not record any payload |
| 421 | field. |
| 422 | |
| 423 | The two available option:--userspace-probe option's argument formats |
| 424 | are: |
| 425 | |
| 426 | option:--userspace-probe=`[elf:]PATH:SYMBOL`:: |
| 427 | Dynamically instrument an available symbol within a user space |
| 428 | executable. |
| 429 | + |
| 430 | -- |
| 431 | 'PATH':: |
| 432 | Application or library path. |
| 433 | + |
| 434 | This can be: |
| 435 | + |
| 436 | * An absolute path. |
| 437 | * A relative path. |
| 438 | * An executable's name as found in the directories listed in the |
| 439 | `PATH` environment variable. |
| 440 | |
| 441 | 'SYMBOL':: |
| 442 | Symbol name of the function of which to instrument the entry. |
| 443 | + |
| 444 | This can be any defined code symbol listed by the man:nm(1) command |
| 445 | (including with its nloption:--dynamic option which lists dynamic |
| 446 | symbols). |
| 447 | -- |
| 448 | + |
| 449 | As of this version, not specifying `elf:` is equivalent to specifying |
| 450 | it. |
| 451 | + |
| 452 | Examples: |
| 453 | + |
| 454 | * `--userspace-probe=/usr/lib/libc.so.6:malloc` |
| 455 | * `--userspace-probe=./myapp:createUser` |
| 456 | * `--userspace-probe=httpd:ap_run_open_htaccess` |
| 457 | |
| 458 | option:--userspace-probe=`sdt:PATH:PROVIDER:NAME`:: |
| 459 | Dynamically instrument an SDT probe within a user space executable. |
| 460 | + |
| 461 | -- |
| 462 | 'PATH':: |
| 463 | Application or library path. |
| 464 | + |
| 465 | This can be: |
| 466 | + |
| 467 | * An absolute path. |
| 468 | * A relative path. |
| 469 | * An executable's name as found in the directories listed in the |
| 470 | `PATH` environment variable. |
| 471 | |
| 472 | __PROVIDER__:__NAME__:: |
| 473 | SDT provider and probe names. |
| 474 | + |
| 475 | For example, with the following SDT probe: |
| 476 | + |
| 477 | [source,c] |
| 478 | ---- |
| 479 | DTRACE_PROBE2("server", "accept_request", |
| 480 | request_id, ip_addr); |
| 481 | ---- |
| 482 | + |
| 483 | The provider/probe name pair is `server:accept_request`. |
| 484 | -- |
| 485 | + |
| 486 | Example: |
| 487 | + |
| 488 | * `--userspace-probe=sdt:./build/server:server:accept_request` |
| 489 | |
| 490 | |
| 491 | include::common-cmd-options-head.txt[] |
| 492 | |
| 493 | |
| 494 | Domain |
| 495 | ~~~~~~ |
| 496 | One of: |
| 497 | |
| 498 | option:-j, option:--jul:: |
| 499 | Create or enable event rules in the `java.util.logging` |
| 500 | (JUL) domain. |
| 501 | |
| 502 | option:-k, option:--kernel:: |
| 503 | Create or enable event rules in the Linux kernel domain. |
| 504 | |
| 505 | option:-l, option:--log4j:: |
| 506 | Create or enable event rules in the Apache log4j domain. |
| 507 | |
| 508 | option:-p, option:--python:: |
| 509 | Create or enable event rules in the Python domain. |
| 510 | |
| 511 | option:-u, option:--userspace:: |
| 512 | Create or enable event rules in the user space domain. |
| 513 | |
| 514 | |
| 515 | Target |
| 516 | ~~~~~~ |
| 517 | option:-c 'CHANNEL', option:--channel='CHANNEL':: |
| 518 | Create or enable event rules in the channel named 'CHANNEL' instead |
| 519 | of the default channel name `channel0`. |
| 520 | |
| 521 | option:-s 'SESSION', option:--session='SESSION':: |
| 522 | Create or enable event rules in the tracing session named 'SESSION' |
| 523 | instead of the current tracing session. |
| 524 | |
| 525 | |
| 526 | Event source type |
| 527 | ~~~~~~~~~~~~~~~~~ |
| 528 | One of: |
| 529 | |
| 530 | option:--function='SOURCE':: |
| 531 | Linux kernel kretprobe. Only available with the option:--kernel |
| 532 | domain option. 'SOURCE' is one of: |
| 533 | + |
| 534 | * Function address (`0x` prefix supported) |
| 535 | * Function symbol |
| 536 | * Function symbol and offset (`SYMBOL+OFFSET` format) |
| 537 | |
| 538 | option:--probe='SOURCE':: |
| 539 | Linux kernel kprobe. Only available with the option:--kernel |
| 540 | domain option. 'SOURCE' is one of: |
| 541 | + |
| 542 | * Address (`0x` prefix supported) |
| 543 | * Symbol |
| 544 | * Symbol and offset (`SYMBOL+OFFSET` format) |
| 545 | |
| 546 | option:--userspace-probe='SOURCE':: |
| 547 | Linux kernel uprobe. Only available with the option:--kernel |
| 548 | domain option. |
| 549 | + |
| 550 | See the <<userspace-probe,Dynamic user space probes>> section for more |
| 551 | information about the option's argument 'SOURCE'. |
| 552 | |
| 553 | option:--syscall:: |
| 554 | Linux kernel system call. Only available with the option:--kernel |
| 555 | domain option. |
| 556 | |
| 557 | option:--tracepoint:: |
| 558 | Linux kernel or application tracepoint (default). |
| 559 | |
| 560 | |
| 561 | Log level |
| 562 | ~~~~~~~~~ |
| 563 | One of: |
| 564 | |
| 565 | option:--loglevel='LOGLEVEL':: |
| 566 | Add log level condition to the event rule: the event source's |
| 567 | defined log level must be at least as severe as 'LOGLEVEL'. |
| 568 | See the <<log-levels,Log levels>> section above for the available |
| 569 | log levels. Only available with application domains. |
| 570 | |
| 571 | option:--loglevel-only='LOGLEVEL':: |
| 572 | Add log level condition to the event rule: the event source's |
| 573 | defined log level must match 'LOGLEVEL'. See the |
| 574 | <<log-levels,Log levels>> section above for the available log |
| 575 | levels. Only available with application domains. |
| 576 | |
| 577 | |
| 578 | Filtering and exclusion |
| 579 | ~~~~~~~~~~~~~~~~~~~~~~~ |
| 580 | option:-x 'EVENT'[,'EVENT']..., option:--exclude='EVENT'[,'EVENT']...:: |
| 581 | Exclude events named 'EVENT' from the event rule. This option |
| 582 | can be used when the command's 'EVENT' argument contains at least |
| 583 | one wildcard star (`*`) to exclude specific names. 'EVENT' can also |
| 584 | contain wildcard stars. To use a |
| 585 | literal `,` character, use :esccomma:. |
| 586 | Only available with the option:--userspace domain. |
| 587 | |
| 588 | option:-f 'EXPR', option:--filter='EXPR':: |
| 589 | Add filter expression condition to the event rule. Expression 'EXPR' |
| 590 | must evaluate to true when executed against the dynamic values of |
| 591 | event fields. See the <<filter-expr,Filter expression>> |
| 592 | section above for more information. |
| 593 | |
| 594 | |
| 595 | Shortcuts |
| 596 | ~~~~~~~~~ |
| 597 | option:-a, option:--all:: |
| 598 | Equivalent to an 'EVENT' argument named `*` (wildcard) when also |
| 599 | using the option:--tracepoint (default) or option:--syscall option. |
| 600 | |
| 601 | |
| 602 | include::common-cmd-help-options.txt[] |
| 603 | |
| 604 | |
| 605 | include::common-cmd-footer.txt[] |
| 606 | |
| 607 | |
| 608 | SEE ALSO |
| 609 | -------- |
| 610 | man:lttng-disable-event(1), |
| 611 | man:lttng(1) |