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 Wildcard using the `*` character are supported _at the end_ of
 137 tracepoint and system call names.
 138
 139 * Filter expression (option:--filter option) executed against the
 140   dynamic values of event fields at execution time that must evaluate
 141   to true. See the <<filter-syntax,Filter expression syntax>> section
 142   below for more information.
 143
 144 The available conditions for the application domains are:
 145
 146 * Tracepoint name ('EVENT' with option:--tracepoint option) which must
 147   match event source's equivalent.
 148 +
 149 Wildcard using the `*` character are supported _at the end_ of
 150 tracepoint names. When creating an event rule with a tracepoint name
 151 containing a wildcard, specific tracepoint names can be excluded from
 152 the match using the option:--exclude option.
 153
 154 * Filter expression (option:--filter option) executed against the
 155   dynamic values of event fields at execution time that must evaluate
 156   to true. See the <<filter-syntax,Filter expression syntax>> section
 157   below for more information.
 158 * Event's log level that must be at least as severe as a given
 159   log level (option:--loglevel option) or match exactly a given log
 160   level (option:--loglevel-only option).
 161
 162 When using `lttng enable-event` with a set of conditions that does not
 163 currently exist for the chosen tracing session, domain, and channel,
 164 a new event rule is created. Otherwise, the existing event rule is
 165 enabled if it is currently disabled
 166 (see man:lttng-disable-event(1)).
 167
 168 The option:--all option can be used alongside the option:--tracepoint
 169 or option:--syscall options. When this option is used, no 'EVENT'
 170 argument must be specified. This option defines a single event rule
 171 matching _all_ the possible events of a given tracing domain for the
 172 chosen channel and tracing session. It is the equivalent of an 'EVENT'
 173 argument named `*` (wildcard).
 174
 175
 176 [[filter-syntax]]
 177 Filter expression syntax
 178 ~~~~~~~~~~~~~~~~~~~~~~~~
 179 A filter expression can be specified with the option:--filter option
 180 when creating a new event rule. If the filter expression evaluates to
 181 true when executed against the dynamic values of an event's fields when
 182 tracing, the filtering condition passes.
 183
 184 NOTE: Make sure to **single-quote** the filter expression when running
 185 the command from a shell, as filter expressions typically include
 186 characters having a special meaning for most shells.
 187
 188 The filter expression syntax is very similar to C language conditional
 189 expressions (expressions that can be evaluated by an `if` statement).
 190
 191 The following logical operators are supported:
 192
 193 [width="40%",options="header"]
 194 |=====================================
 195 | Name                      | Syntax
 196 | Logical negation (NOT)    | `!a`
 197 | Logical conjunction (AND) | `a && b`
 198 | Logical disjunction (OR)  | `a \|\| b`
 199 |=====================================
 200
 201 The following comparison operators/relational operators are supported:
 202
 203 [width="40%",options="header"]
 204 |====================================
 205 | Name                     | Syntax
 206 | Equal to                 | `a == b`
 207 | Not equal to             | `a != b`
 208 | Greater than             | `a > b`
 209 | Less than                | `a < b`
 210 | Greater than or equal to | `a >= b`
 211 | Less than or equal to    | `a <= b`
 212 |====================================
 213
 214 The arithmetic and bitwise operators are :not: supported.
 215
 216 The precedence table of the operators above is the same as the one of
 217 the C language. Parentheses are supported to bypass this.
 218
 219 The dynamic value of an event field is read by using its name as a C
 220 identifier.
 221
 222 The dynamic value of a statically-known context field is read by
 223 prefixing its name with `$ctx.`. Statically-known context fields are
 224 context fields added to channels without the `$app.` prefix using the
 225 man:lttng-add-context(1) command. `$ctx.cpu_id` is also available as the
 226 ID of the CPU which emits the event.
 227
 228 The dynamic value of an application-specific context field is read by
 229 prefixing its name with `$app.` (follows the format used to add such a
 230 context field with the man:lttng-add-context(1) command).
 231
 232 When a comparison includes a non existent event field, the whole filter
 233 expression evaluates to false (the event is discarded).
 234
 235 C integer and floating point number constants are supported, as well as
 236 literal strings between double quotes (`"`). Literal strings can contain
 237 a wildcard character (`*`) at the end to match more than one string.
 238 This wildcard can be escaped using :escwc:.
 239
 240 LTTng-UST enumeration fields can be compared to integer values (fields
 241 or constants).
 242
 243 NOTE: Although it is possible to filter the process ID of an event when
 244 the `pid` context has been added to its channel using, for example,
 245 `$ctx.pid == 2832`, it is recommended to use the PID tracker instead,
 246 which is much more efficient (see man:lttng-track(1)).
 247
 248 Examples:
 249
 250 ----------------------------
 251 msg_id == 23 && size >= 2048
 252 ----------------------------
 253
 254 -------------------------------------------------
 255 $ctx.procname == "lttng*" && (!flag || poel < 34)
 256 -------------------------------------------------
 257
 258 ---------------------------------------------------------
 259 $app.my_provider:my_context == 17.34e9 || some_enum >= 14
 260 ---------------------------------------------------------
 261
 262
 263 [[log-levels]]
 264 Log levels
 265 ~~~~~~~~~~
 266 Tracepoints and log statements in applications have an attached log
 267 level. Application event rules can contain a _log level_ condition.
 268
 269 With the option:--loglevel option, the event source's log level must
 270 be at least as severe as the option's argument. With the
 271 option:--loglevel-only option, the event source's log level must match
 272 the option's argument.
 273
 274 The available log levels are:
 275
 276 User space domain (option:--userspace option)::
 277     Shortcuts such as `system` are allowed.
 278 +
 279 * `TRACE_EMERG` (0)
 280 * `TRACE_ALERT` (1)
 281 * `TRACE_CRIT` (2)
 282 * `TRACE_ERR` (3)
 283 * `TRACE_WARNING` (4)
 284 * `TRACE_NOTICE` (5)
 285 * `TRACE_INFO` (6)
 286 * `TRACE_DEBUG_SYSTEM` (7)
 287 * `TRACE_DEBUG_PROGRAM` (8)
 288 * `TRACE_DEBUG_PROCESS` (9)
 289 * `TRACE_DEBUG_MODULE` (10)
 290 * `TRACE_DEBUG_UNIT` (11)
 291 * `TRACE_DEBUG_FUNCTION` (12)
 292 * `TRACE_DEBUG_LINE` (13)
 293 * `TRACE_DEBUG` (14)
 294
 295 `java.util.logging` domain (option:--jul option)::
 296     Shortcuts such as `severe` are allowed.
 297 +
 298 * `JUL_OFF` (`INT32_MAX`)
 299 * `JUL_SEVERE` (1000)
 300 * `JUL_WARNING` (900)
 301 * `JUL_INFO` (800)
 302 * `JUL_CONFIG` (700)
 303 * `JUL_FINE` (500)
 304 * `JUL_FINER` (400)
 305 * `JUL_FINEST` (300)
 306 * `JUL_ALL` (`INT32_MIN`)
 307
 308 Apache log4j domain (option:--log4j option)::
 309     Shortcuts such as `severe` are allowed.
 310 +
 311 * `LOG4J_OFF` (`INT32_MAX`)
 312 * `LOG4J_FATAL` (50000)
 313 * `LOG4J_ERROR` (40000)
 314 * `LOG4J_WARN` (30000)
 315 * `LOG4J_INFO` (20000)
 316 * `LOG4J_DEBUG` (10000)
 317 * `LOG4J_TRACE` (5000)
 318 * `LOG4J_ALL` (`INT32_MIN`)
 319
 320 Python domain (option:--python option)::
 321     Shortcuts such as `critical` are allowed.
 322 +
 323 * `PYTHON_CRITICAL` (50)
 324 * `PYTHON_ERROR` (40)
 325 * `PYTHON_WARNING` (30)
 326 * `PYTHON_INFO` (20)
 327 * `PYTHON_DEBUG` (10)
 328 * `PYTHON_NOTSET` (0)
 329
 330
 331 include::common-cmd-options-head.txt[]
 332
 333
 334 Domain
 335 ~~~~~~
 336 One of:
 337
 338 option:-j, option:--jul::
 339     Create or enable event rules in the `java.util.logging`
 340     (JUL) domain.
 341
 342 option:-k, option:--kernel::
 343     Create or enable event rules in the Linux kernel domain.
 344
 345 option:-l, option:--log4j::
 346     Create or enable event rules in the Apache log4j domain.
 347
 348 option:-p, option:--python::
 349     Create or enable event rules in the Python domain.
 350
 351 option:-u, option:--userspace::
 352     Create or enable event rules in the user space domain.
 353
 354
 355 Target
 356 ~~~~~~
 357 option:-c 'CHANNEL', option:--channel='CHANNEL'::
 358     Create or enable event rules in the channel named 'CHANNEL' instead
 359     of the default channel name `channel0`.
 360
 361 option:-s 'SESSION', option:--session='SESSION'::
 362     Create or enable event rules in the tracing session named 'SESSION'
 363     instead of the current tracing session.
 364
 365
 366 Event source type
 367 ~~~~~~~~~~~~~~~~~
 368 One of:
 369
 370 option:--function='SOURCE'::
 371     Linux kernel kretprobe. Only available with the option:--kernel
 372     domain option. 'SOURCE' is one of:
 373 +
 374 * Function address (`0x` prefix supported)
 375 * Function symbol
 376 * Function symbol and offset (`SYMBOL+OFFSET` format)
 377
 378 option:--probe='SOURCE'::
 379     Linux kernel kprobe. Only available with the option:--kernel
 380     domain option. 'SOURCE' is one of:
 381 +
 382 * Address (`0x` prefix supported)
 383 * Symbol
 384 * Symbol and offset (`SYMBOL+OFFSET` format)
 385
 386 option:--syscall::
 387     Linux kernel system call. Only available with the option:--kernel
 388     domain option.
 389
 390 option:--tracepoint::
 391     Linux kernel or application tracepoint (default).
 392
 393
 394 Log level
 395 ~~~~~~~~~
 396 One of:
 397
 398 option:--loglevel='LOGLEVEL'::
 399     Add log level condition to the event rule: the event source's
 400     defined log level must be at least as severe as 'LOGLEVEL'.
 401     See the <<log-levels,Log levels>> section above for the available
 402     log levels. Only available with application domains.
 403
 404 option:--loglevel-only='LOGLEVEL'::
 405     Add log level condition to the event rule: the event source's
 406     defined log level must match 'LOGLEVEL'. See the
 407     <<log-levels,Log levels>> section above for the available log
 408     levels. Only available with application domains.
 409
 410
 411 Filtering and exclusion
 412 ~~~~~~~~~~~~~~~~~~~~~~~
 413 option:-x 'EVENT'[,'EVENT']..., option:--exclude='EVENT'[,'EVENT']...::
 414     Exclude events named 'EVENT' from the event rule. This option
 415     can be used when the command's 'EVENT' argument contains a wildcard
 416     (`*`) to exclude specific names. Only available with application
 417     domains.
 418
 419 option:-f 'EXPR', option:--filter='EXPR'::
 420     Add filter expression condition to the event rule. Expression 'EXPR'
 421     must evaluate to true when executed against the dynamic values of
 422     event fields. See the <<filter-syntax,Filter expression syntax>>
 423     section above for more information.
 424
 425
 426 Shortcuts
 427 ~~~~~~~~~
 428 option:-a, option:--all::
 429     Equivalent to an 'EVENT' argument named `*` (wildcard) when also
 430     using the option:--tracepoint (default) or option:--syscall option.
 431
 432
 433 include::common-cmd-help-options.txt[]
 434
 435
 436 include::common-cmd-footer.txt[]
 437
 438
 439 SEE ALSO
 440 --------
 441 man:lttng-disable-event(1),
 442 man:lttng(1)