doc/man/lttng-enable-event.1.txt

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