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