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