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

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