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