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