lttng-enable-event(1): add usage examples
[lttng-tools.git] / doc / man / lttng-enable-event.1.txt
1 lttng-enable-event(1)
2 =====================
3 :revdate: 25 May 2021
4
5
6 NAME
7 ----
8 lttng-enable-event - Create or enable LTTng recording event rules
9
10
11 SYNOPSIS
12 --------
13 Create or enable one or more recording event rules to match Linux kernel
14 tracepoint or system call events:
15
16 [verse]
17 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-event* option:--kernel [option:--tracepoint | option:--syscall]
18 (option:--all | 'NAME'[,'NAME']...) [option:--filter='EXPR']
19 [option:--session='SESSION'] [option:--channel='CHANNEL']
20
21 Create or enable a recording event rule to match Linux kernel events
22 created from a dynamic instrumentation point:
23
24 [verse]
25 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-event* option:--kernel
26 (option:--probe='LOC' | option:--function='LOC' | option:--userspace-probe='LOC') 'RECORDNAME'
27 [option:--session='SESSION'] [option:--channel='CHANNEL']
28
29 Create or enable one or more recording event rules to match
30 user space tracepoint events:
31
32 [verse]
33 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-event* option:--userspace [option:--tracepoint]
34 (option:--all | 'NAME'[,'NAME']...) [option:--exclude='XNAME'[,'XNAME']...]
35 [option:--loglevel='LOGLEVEL' | option:--loglevel-only='LOGLEVEL'] [option:--filter='EXPR']
36 [option:--session='SESSION'] [option:--channel='CHANNEL']
37
38 Create or enable one or more recording event rules to match
39 Java/Python logging events:
40
41 [verse]
42 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-event* (option:--jul | option:--log4j | option:--python)
43 [option:--tracepoint] (option:--all | 'NAME'[,'NAME']...)
44 [option:--loglevel='LOGLEVEL' | option:--loglevel-only='LOGLEVEL'] [option:--filter='EXPR']
45 [option:--session='SESSION'] [option:--channel='CHANNEL']
46
47 DESCRIPTION
48 -----------
49 The `lttng enable-event` command does one of:
50
51 * Create one or more recording event rules.
52
53 * Enable one or more disabled recording event rules.
54 +
55 See the <<enable,Enable a disabled recording event rule>> section
56 below.
57
58 See man:lttng-concepts(7) to learn more about instrumentation points,
59 events, recording event rules, and event records.
60
61 The recording event rule(s) to create or enable belong to:
62
63 With the option:--session='SESSION' option::
64 The tracing session named 'SESSION'.
65
66 Without the option:--session option::
67 The current tracing session (see man:lttng-concepts(7) to learn more
68 about the current tracing session).
69
70 With the option:--channel='CHANNEL' option::
71 The channel named 'CHANNEL'.
72
73 Without the option:--channel option::
74 The channel named `channel0`.
75 +
76 If there's already a channel for the selected tracing session and domain
77 which isn't named `channel0`, the `enable-event` command fails.
78 Otherwise, it automatically creates it.
79
80 See the <<examples,EXAMPLES>> section below for usage examples.
81
82 List the recording event rules of a specific tracing session
83 and/or channel with the man:lttng-list(1) and man:lttng-status(1)
84 commands.
85
86 Disable an enabled recording event rule with the
87 man:lttng-disable-event(1) command.
88
89
90 Overview of recording event rule conditions
91 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
92 For LTTng to emit and record an event{nbsp}__E__,{nbsp}__E__ must
93 satisfy *all* the conditions of a recording event rule{nbsp}__ER__, that
94 is:
95
96 Explicit conditions::
97 You set the following conditions when you create or
98 enable{nbsp}__ER__ with the `enable-event` command:
99 +
100 --
101 * The instrumentation point type from which LTTng creates{nbsp}__E__
102 has a specific type.
103 +
104 See the <<inst-point-type-cond,Instrumentation point type condition>>
105 section below.
106
107 * A pattern matches the name of{nbsp}__E__ while another pattern
108 doesn't.
109 +
110 See the <<event-name-cond,Event name condition>> section below.
111
112 * The log level of the instrumentation point from which LTTng
113 creates{nbsp}__E__ is at least as severe as some value, or is exactly
114 some value.
115 +
116 See the <<inst-point-log-level-cond,Instrumentation point log level condition>>
117 section below.
118
119 * The fields of the payload of{nbsp}__E__ and the current context fields
120 satisfy a filter expression.
121 +
122 See the <<filter-cond,Event payload and context filter condition>>
123 section below.
124 --
125
126 Implicit conditions::
127 +
128 --
129 * _ER_ itself is enabled.
130 +
131 A recording event rule is enabled on creation.
132 +
133 Enable a disabled recording event rule with the `enable-event` command.
134
135 * The channel to which{nbsp}__ER__ is attached is enabled.
136 +
137 A channel is enabled on creation.
138 +
139 Enable a disabled channel with the man:lttng-enable-channel(1) command.
140
141 * The tracing session of{nbsp}__ER__ is active (started).
142 +
143 A tracing session is inactive (stopped) on creation.
144 +
145 Start an inactive tracing session with the man:lttng-start(1) command.
146
147 * The process for which LTTng creates{nbsp}__E__ is allowed to record
148 events.
149 +
150 All processes are allowed to record events on tracing session
151 creation.
152 +
153 Use the man:lttng-track(1) and man:lttng-untrack(1) commands to select
154 which processes are allowed to record events based on specific process
155 attributes.
156 --
157
158 The dedicated command-line options of most conditions are optional: if
159 you don't specify the option, the associated condition is always
160 satisfied.
161
162
163 [[inst-point-type-cond]]
164 Instrumentation point type condition
165 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
166 An event{nbsp}__E__ satisfies the instrumentation point type condition
167 of a recording event rule if the instrumentation point from which LTTng
168 creates{nbsp}__E__ is:
169
170 For the Linux kernel tracing domain (option:--kernel option)::
171 With the option:--tracepoint option or without any other instrumentation point type option:::
172 An LTTng kernel tracepoint, that is, a statically defined point
173 in the source code of the kernel image or of a kernel module
174 with LTTng kernel tracer macros.
175 +
176 As of LTTng{nbsp}{lttng_version}, this is the default instrumentation
177 point type of the Linux kernel tracing domain, but this may change in
178 the future.
179 +
180 List the available Linux kernel tracepoints with `lttng list --kernel`.
181 See man:lttng-list(1) to learn more.
182
183 With the option:--syscall option:::
184 The entry and exit of a Linux kernel system call.
185 +
186 List the available Linux kernel system call instrumentation points with
187 `lttng list --kernel --syscall`. See man:lttng-list(1) to learn more.
188
189 With the option:--probe option:::
190 A Linux kprobe, that is, a single probe dynamically placed in
191 the compiled kernel code.
192 +
193 The argument of the option:--probe option is the location of the
194 kprobe to insert, either a symbol or a
195 memory address, while 'RECORDNAME' is the name of the record
196 of{nbsp}__E__ (see the <<er-name,Event record name>> section below).
197 +
198 The payload of a Linux kprobe event is empty.
199
200 With the option:--userspace-probe option:::
201 A Linux user space probe, that is, a single probe dynamically
202 placed at the entry of a compiled user space application/library
203 function through the kernel.
204 +
205 The argument of the option:--userspace-probe option is the location
206 of the user space probe to insert, one of:
207 +
208 --
209 * A path and symbol (ELF method).
210 * A path, provider name, and probe name (SystemTap User-level Statically
211 Defined Tracing (USDT) method; a DTrace-style marker).
212 +
213 As of LTTng{nbsp}{lttng_version}, LTTng only supports USDT probes which
214 are :not: reference-counted.
215 --
216 +
217 'RECORDNAME' is the name of the record of{nbsp}__E__ (see the
218 <<er-name,Event record name>> section below).
219 +
220 The payload of a Linux user space probe event is empty.
221
222 With the option:--function option:::
223 A Linux kretprobe, that is, two probes dynamically placed at the
224 entry and exit of a function in the compiled kernel code.
225 +
226 The argument of the option:--function option is the location of the
227 Linux kretprobe to insert, either a symbol or
228 a memory address, while 'RECORDNAME' is the name of the record
229 of{nbsp}__E__ (see the <<er-name,Event record name>> section below).
230 +
231 The payload of a Linux kretprobe event is empty.
232
233 For the user space tracing domain (option:--userspace option)::
234 With or without the option:--tracepoint option:::
235 An LTTng user space tracepoint, that is, a statically defined
236 point in the source code of a C/$$C++$$ application/library with
237 LTTng user space tracer macros.
238 +
239 As of LTTng{nbsp}{lttng_version}, this is the default and sole
240 instrumentation point type of the user space tracing domain, but this
241 may change in the future.
242 +
243 List the available user space tracepoints with `lttng list --userspace`.
244 See man:lttng-list(1) to learn more.
245
246 For the `java.util.logging` (option:--jul option), Apache log4j (option:--log4j option), and Python (option:--python option) tracing domains::
247 With or without the option:--tracepoint option:::
248 A logging statement.
249 +
250 As of LTTng{nbsp}{lttng_version}, this is the default and sole
251 instrumentation point type of the `java.util.logging`, Apache log4j, and
252 Python tracing domains, but this may change in the future.
253 +
254 List the available Java and Python loggers with `lttng list --jul`,
255 `lttng list --log4j`, and `lttng list --python`. See man:lttng-list(1)
256 to learn more.
257
258
259 [[event-name-cond]]
260 Event name condition
261 ~~~~~~~~~~~~~~~~~~~~
262 An event{nbsp}__E__ satisfies the event name condition of a recording
263 event rule{nbsp}__ER__ if the two following statements are true:
264
265 * You specify the option:--all option or, depending on the
266 instrumentation type condition (see the
267 <<inst-point-type-cond,Instrumentation point type condition>> section
268 above) of{nbsp}__ER__, 'NAME' matches:
269 +
270 --
271 LTTng tracepoint::
272 The full name of the tracepoint from which LTTng creates{nbsp}__E__.
273 +
274 Note that the full name of a user space tracepoint is
275 __PROVIDER__++:++__NAME__, where __PROVIDER__ is the tracepoint provider
276 name and __NAME__ is the tracepoint name.
277
278 Logging statement::
279 The name of the Java or Python logger from which LTTng
280 creates{nbsp}__E__.
281
282 Linux system call::
283 The name of the system call, without any `sys_` prefix, from which
284 LTTng creates{nbsp}__E__.
285 --
286
287 * You don't specify the option:--exclude=__XNAME__[++,++__XNAME__]...
288 option or, depending on the instrumentation type condition
289 of{nbsp}__ER__, none of the 'XNAME' arguments matches the full name of
290 the user space tracepoint from which LTTng creates{nbsp}__E__.
291 +
292 The option:--exclude option is only available with the option:--userspace
293 option.
294
295 This condition is only meaningful for the LTTng tracepoint, logging
296 statement, and Linux system call instrumentation point types: it's
297 always satisfied for the other types.
298
299 In all cases, 'NAME' and 'XNAME' are globbing patterns: the `*`
300 character means ``match anything''. To match a literal `*` character,
301 use :escwc:. To match a literal `,` character, use
302 :esccomma:.
303
304 IMPORTANT: Make sure to **single-quote** 'NAME' and 'XNAME' when they
305 contain the `*` character and when you run the `enable-event` command
306 from a shell.
307
308 With the LTTng tracepoint, logging statement, and Linux system call
309 instrumentation point types, the `enable-event` command creates or
310 enables one independent recording event rule per 'NAME' argument
311 (non-option, comma-separated). With the option:--all option, the
312 `enable-event` command creates or enables a single recording event rule.
313
314
315 [[inst-point-log-level-cond]]
316 Instrumentation point log level condition
317 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
318 An event{nbsp}__E__ satisfies the instrumentation point log level
319 condition of a recording event rule if either:
320
321 * The option:--loglevel and option:--loglevel-only options are
322 missing.
323
324 * The log level of the LTTng user space tracepoint or logging statement
325 which creates{nbsp}__E__ is:
326 With the option:--loglevel='LOGLEVEL' option::
327 At least as severe as 'LOGLEVEL'.
328
329 With the option:--loglevel-only='LOGLEVEL' option::
330 Exactly 'LOGLEVEL'.
331
332 This condition is only meaningful for the LTTng user space tracepoint
333 and logging statement instrumentation point types: it's always satisfied
334 for other types.
335
336 The available values of 'LOGLEVEL' are, depending on the tracing domain,
337 from the most to the least severe:
338
339 User space (option:--userspace option)::
340 +
341 * `EMERG` (0)
342 * `ALERT` (1)
343 * `CRIT` (2)
344 * `ERR` (3)
345 * `WARNING` (4)
346 * `NOTICE` (5)
347 * `INFO` (6)
348 * `DEBUG_SYSTEM` (7)
349 * `DEBUG_PROGRAM` (8)
350 * `DEBUG_PROCESS` (9)
351 * `DEBUG_MODULE` (10)
352 * `DEBUG_UNIT` (11)
353 * `DEBUG_FUNCTION` (12)
354 * `DEBUG_LINE` (13)
355 * `DEBUG` (14)
356
357 `java.util.logging` (option:--jul option)::
358 +
359 * `OFF` (`INT32_MAX`)
360 * `SEVERE` (1000)
361 * `WARNING` (900)
362 * `INFO` (800)
363 * `CONFIG` (700)
364 * `FINE` (500)
365 * `FINER` (400)
366 * `FINEST` (300)
367 * `ALL` (`INT32_MIN`)
368
369 Apache log4j (option:--log4j option)::
370 +
371 * `OFF` (`INT32_MAX`)
372 * `FATAL` (50000)
373 * `ERROR` (40000)
374 * `WARN` (30000)
375 * `INFO` (20000)
376 * `DEBUG` (10000)
377 * `TRACE` (5000)
378 * `ALL` (`INT32_MIN`)
379
380 Python (option:--python option)::
381 +
382 * `CRITICAL` (50)
383 * `ERROR` (40)
384 * `WARNING` (30)
385 * `INFO` (20)
386 * `DEBUG` (10)
387 * `NOTSET` (0)
388
389
390 [[filter-cond]]
391 Event payload and context filter condition
392 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
393 An event{nbsp}__E__ satisfies the event payload and context filter
394 condition of a recording event rule if the option:--filter='EXPR'
395 option is missing or if 'EXPR' is _true_.
396
397 This condition is only meaningful for the LTTng tracepoint and Linux
398 system call instrumentation point types: it's always satisfied for other
399 types.
400
401 'EXPR' can contain references to the payload fields of{nbsp}__E__ and
402 to the current context fields.
403
404 IMPORTANT: Make sure to **single-quote** 'EXPR' when you run the
405 `enable-event` command from a shell, as filter expressions typically
406 include characters having a special meaning for most shells.
407
408 The expected syntax of 'EXPR' is similar to the syntax of a
409 C{nbsp}language conditional expression (an expression which an `if`
410 statement can evaluate), but there are a few differences:
411
412 * A _NAME_ expression identifies an event payload field named
413 _NAME_ (a C{nbsp}identifier).
414 +
415 Use the C{nbsp}language dot and square bracket notations to access
416 nested structure and array/sequence fields. You can only use a constant,
417 positive integer number within square brackets. If the index is out of
418 bounds, 'EXPR' is _false_.
419 +
420 The value of an enumeration field is an integer.
421 +
422 When a field expression doesn't exist, 'EXPR' is _false_.
423 +
424 Examples: `my_field`, `target_cpu`, `seq[7]`, `msg.user[1].data[2][17]`.
425
426 * A ++$ctx.++__TYPE__ expression identifies the statically-known context
427 field having the type _TYPE_ (a C{nbsp}identifier).
428 +
429 List the available statically-known context field names with the
430 man:lttng-add-context(1) command.
431 +
432 When a field expression doesn't exist, 'EXPR' is _false_.
433 +
434 Examples: `$ctx.prio`, `$ctx.preemptible`,
435 `$ctx.perf:cpu:stalled-cycles-frontend`.
436
437 * A ++$app.++__PROVIDER__++:++__TYPE__ expression identifies the
438 application-specific context field having the type _TYPE_ (a
439 C{nbsp}identifier) from the provider _PROVIDER_ (a C{nbsp}identifier).
440 +
441 When a field expression doesn't exist, 'EXPR' is _false_.
442 +
443 Example: `$app.server:cur_user`.
444
445 * Compare strings, either string fields or string literals
446 (double-quoted), with the `==` and `!=` operators.
447 +
448 When comparing to a string literal, the `*` character means ``match
449 anything''. To match a literal `*` character, use :escwc:.
450 +
451 Examples: `my_field == "user34"`, `my_field == my_other_field`,
452 `my_field == "192.168.*"`.
453
454 * The precedence table of the operators which are supported in 'EXPR'
455 is as follows. In this table, the highest precedence is{nbsp}1:
456 +
457 [options="header"]
458 |===
459 |Precedence |Operator |Description |Associativity
460 |1 |`-` |Unary minus |Right-to-left
461 |1 |`+` |Unary plus |Right-to-left
462 |1 |`!` |Logical NOT |Right-to-left
463 |1 |`~` |Bitwise NOT |Right-to-left
464 |2 |`<<` |Bitwise left shift |Left-to-right
465 |2 |`>>` |Bitwise right shift |Left-to-right
466 |3 |`&` |Bitwise AND |Left-to-right
467 |4 |`^` |Bitwise XOR |Left-to-right
468 |5 |`\|` |Bitwise OR |Left-to-right
469 |6 |`<` |Less than |Left-to-right
470 |6 |`<=` |Less than or equal to |Left-to-right
471 |6 |`>` |Greater than |Left-to-right
472 |6 |`>=` |Greater than or equal to |Left-to-right
473 |7 |`==` |Equal to |Left-to-right
474 |7 |`!=` |Not equal to |Left-to-right
475 |8 |`&&` |Logical AND |Left-to-right
476 |9 |`\|\|` |Logical OR |Left-to-right
477 |===
478 +
479 Parentheses are supported to bypass the default order.
480 +
481 IMPORTANT: Unlike the C{nbsp}language, the bitwise AND and OR operators
482 (`&` and `|`) in 'EXPR' take precedence over relational operators (`<`,
483 `<=`, `>`, `>=`, `==`, and `!=`). This means the expression `2 & 2 == 2`
484 is _true_ while the equivalent C{nbsp}expression is _false_.
485 +
486 The arithmetic operators are :not: supported.
487 +
488 LTTng first casts all integer constants and fields to signed 64-bit
489 integers. The representation of negative integers is two's complement.
490 This means that, for example, the signed 8-bit integer field 0xff (-1)
491 becomes 0xffffffffffffffff (still -1) once casted.
492 +
493 Before a bitwise operator is applied, LTTng casts all its operands to
494 unsigned 64-bit integers, and then casts the result back to a signed
495 64-bit integer. For the bitwise NOT operator, it's the equivalent of
496 this C{nbsp}expression:
497 +
498 [source,c]
499 ----
500 (int64_t) ~((uint64_t) val)
501 ----
502 +
503 For the binary bitwise operators, it's the equivalent of those
504 C{nbsp}expressions:
505 +
506 [source,c]
507 ----
508 (int64_t) ((uint64_t) lhs >> (uint64_t) rhs)
509 (int64_t) ((uint64_t) lhs << (uint64_t) rhs)
510 (int64_t) ((uint64_t) lhs & (uint64_t) rhs)
511 (int64_t) ((uint64_t) lhs ^ (uint64_t) rhs)
512 (int64_t) ((uint64_t) lhs | (uint64_t) rhs)
513 ----
514 +
515 If the right-hand side of a bitwise shift operator (`<<` and `>>`) is
516 not in the [0,{nbsp}63] range, then 'EXPR' is _false_.
517
518 [NOTE]
519 ====
520 Use the man:lttng-track(1) and man:lttng-untrack(1) commands to allow or
521 disallow processes to record LTTng events based on their attributes
522 instead of using equivalent statically-known context fields in 'EXPR'
523 like `$ctx.pid`.
524
525 The former method is much more efficient.
526 ====
527
528 'EXPR' examples:
529
530 ----------------------------
531 msg_id == 23 && size >= 2048
532 ----------------------------
533
534 -------------------------------------------------
535 $ctx.procname == "lttng*" && (!flag || poel < 34)
536 -------------------------------------------------
537
538 ---------------------------------------------------------
539 $app.my_provider:my_context == 17.34e9 || some_enum >= 14
540 ---------------------------------------------------------
541
542 ---------------------------------------
543 $ctx.cpu_id == 2 && filename != "*.log"
544 ---------------------------------------
545
546 ------------------------------------------------
547 eax_reg & 0xff7 == 0x240 && x[4] >> 12 <= 0x1234
548 ------------------------------------------------
549
550
551 [[er-name]]
552 Event record name
553 ~~~~~~~~~~~~~~~~~
554 When LTTng records an event{nbsp}__E__, the resulting event record has a
555 name which depends on the instrumentation point type condition (see the
556 <<inst-point-type-cond,Instrumentation point type condition>> section
557 above) of the recording event rule which matched{nbsp}__E__:
558
559 LTTng tracepoint (option:--kernel/option:--userspace and option:--tracepoint options)::
560 Full name of the tracepoint from which LTTng creates{nbsp}__E__.
561 +
562 Note that the full name of a user space tracepoint is
563 __PROVIDER__++:++__NAME__, where __PROVIDER__ is the tracepoint provider
564 name and __NAME__ is the tracepoint name.
565
566 `java.util.logging` logging statement (option:--jul and option:--tracepoint options)::
567 `lttng_jul:event`
568 +
569 Such an event record has a string field `logger_name` which contains the
570 name of the `java.util.logging` logger from which LTTng
571 creates{nbsp}__E__.
572
573 Apache log4j logging statement (option:--log4j and option:--tracepoint options)::
574 `lttng_log4j:event`
575 +
576 Such an event record has a string field `logger_name` which contains the
577 name of the Apache log4j logger from which LTTng creates{nbsp}__E__.
578
579 Python logging statement (option:--python and option:--tracepoint options)::
580 `lttng_python:event`
581 +
582 Such an event record has a string field `logger_name` which contains the
583 name of the Python logger from which LTTng creates{nbsp}__E__.
584
585 Linux system call (option:--kernel and option:--syscall options)::
586 Entry:::
587 ++syscall_entry_++__NAME__, where _NAME_ is the name of the
588 system call from which LTTng creates{nbsp}__E__, without any
589 `sys_` prefix.
590
591 Exit:::
592 ++syscall_exit_++__NAME__, where _NAME_ is the name of the
593 system call from which LTTng creates{nbsp}__E__, without any
594 `sys_` prefix.
595
596 Linux kprobe (option:--kernel and option:--probe options)::
597 Linux user space probe (option:--kernel and option:--userspace-probe options)::
598 'RECORDNAME' (first non-option argument).
599
600 Linux kretprobe (option:--kernel and option:--function options)::
601 Entry:::
602 __RECORDNAME__++_entry++
603
604 Exit:::
605 __RECORDNAME__++_exit++
606
607
608 [[enable]]
609 Enable a disabled recording event rule
610 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
611 The `enable-event` command can enable a disabled recording event rule,
612 as listed in the output of the man:lttng-list(1) command.
613
614 You may enable a disabled recording event rule regardless of the
615 activity (started or stopped) of its tracing session (see
616 man:lttng-start(1) and man:lttng-stop(1)).
617
618 To enable a disabled recording event rule, run the `enable-event`
619 command with the exact same options and arguments that you used to
620 create it. In particular, with the option:--filter='EXPR' option, 'EXPR'
621 must be the exact same string as the one you used on creation.
622
623
624 include::common-lttng-cmd-options-head.txt[]
625
626
627 Tracing domain
628 ~~~~~~~~~~~~~~
629 One of:
630
631 option:-j, option:--jul::
632 Create or enable recording event rules in the `java.util.logging`
633 (JUL) tracing domain.
634
635 option:-k, option:--kernel::
636 Create or enable recording event rules in the Linux kernel tracing
637 domain.
638
639 option:-l, option:--log4j::
640 Create or enable recording event rules in the Apache log4j tracing
641 domain.
642
643 option:-p, option:--python::
644 Create or enable recording event rules in the Python tracing domain.
645
646 option:-u, option:--userspace::
647 Create or enable recording event rules in the user space tracing
648 domain.
649
650
651 Recording target
652 ~~~~~~~~~~~~~~~~
653 option:-c 'CHANNEL', option:--channel='CHANNEL'::
654 Create or enable recording event rules attached to the channel named
655 'CHANNEL' instead of `channel0`.
656
657 option:-s 'SESSION', option:--session='SESSION'::
658 Create or enable recording event rules in the tracing session named
659 'SESSION' instead of the current tracing session.
660
661
662 Instrumentation point type condition
663 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
664 See the <<inst-point-type-cond,Instrumentation point type condition>>
665 section above.
666
667 At most one of:
668
669 option:--function='LOC'::
670 Only match Linux kretprobe events.
671 +
672 Only available with the option:--kernel option.
673 +
674 'LOC' is one of:
675 +
676 --
677 * A function address (`0x` hexadecimal prefix supported).
678 * A function symbol name.
679 * A function symbol name and an offset
680 (__SYMBOL__++pass:[+]++__OFFSET__ format).
681 --
682 +
683 You must specify the event record name with 'RECORDNAME'. See the
684 <<er-name,Event record name>> section above to learn more.
685
686 option:--probe='LOC'::
687 Only match Linux kprobe events.
688 +
689 Only available with the option:--kernel option.
690 +
691 'LOC' is one of:
692 +
693 --
694 * An address (`0x` hexadecimal prefix supported).
695 * A symbol name.
696 * A symbol name and an offset (__SYMBOL__++pass:[+]++__OFFSET__ format).
697 --
698 +
699 You must specify the event record name with 'RECORDNAME'. See the
700 <<er-name,Event record name>> section above to learn more.
701
702 option:--userspace-probe='LOC'::
703 Only match Linux user space probe events.
704 +
705 Only available with the option:--kernel option.
706 +
707 'LOC' is one of:
708 +
709 --
710 \[++elf:++]__PATH__++:++__SYMBOL__::
711 Probe an available symbol within a user space application or
712 library.
713 +
714 --
715 'PATH'::
716 Application or library path.
717 +
718 One of:
719 +
720 * An absolute path.
721 * A relative path.
722 * The name of an application as found in the directories listed in the
723 `PATH` environment variable.
724
725 'SYMBOL'::
726 Symbol name of the function of which to instrument the entry.
727 +
728 'SYMBOL' can be any defined code symbol in the output of the man:nm(1)
729 command, including with its nloption:--dynamic option, which lists
730 dynamic symbols.
731 --
732 +
733 As of LTTng{nbsp}{lttng_version}, not specifying `elf:` is equivalent to
734 specifying it, but this default may change in the future.
735 +
736 Examples:
737 +
738 * `--userspace-probe=/usr/lib/libc.so.6:malloc`
739 * `--userspace-probe=./myapp:createUser`
740 * `--userspace-probe=elf:httpd:ap_run_open_htaccess`
741
742 ++sdt:++__PATH__++:++__PROVIDER__++:++__NAME__::
743 Use a SystemTap User-level Statically Defined Tracing (USDT) probe
744 within a user space application or library.
745 +
746 --
747 'PATH'::
748 Application or library path.
749 +
750 This can be:
751 +
752 * An absolute path.
753 * A relative path.
754 * The name of an application as found in the directories listed in the
755 `PATH` environment variable.
756
757 'PROVIDER'::
758 'NAME'::
759 USDT provider and probe names.
760 +
761 For example, with the following USDT probe:
762 +
763 [source,c]
764 ----
765 DTRACE_PROBE2("server", "accept_request",
766 request_id, ip_addr);
767 ----
768 +
769 The provider/probe name pair is `server:accept_request`.
770 --
771 +
772 Example: `--userspace-probe=sdt:./build/server:server:accept_request`
773 --
774 +
775 You must specify the event record name with 'RECORDNAME'. See the
776 <<er-name,Event record name>> section above to learn more.
777
778 option:--syscall::
779 Only match Linux system call events.
780 +
781 Only available with the option:--kernel option.
782
783 option:--tracepoint::
784 Only match:
785 +
786 With the option:--kernel or option:--userspace option:::
787 LTTng tracepoint events.
788 With the option:--jul, option:--log4j, or option:--python option:::
789 Logging events.
790
791 With the option:--kernel, not specifying any of the instrumentation
792 point type options is equivalent to specifying the option:--tracepoint
793 option, but this default may change in the future.
794
795 With the option:--userspace, option:--jul, option:--log4j, and
796 option:--python options, not specifying the option:--tracepoint option
797 is equivalent to specifying it, but this default may change in the
798 future.
799
800
801 Event name condition
802 ~~~~~~~~~~~~~~~~~~~~
803 See the <<event-name-cond,Event name condition>> section above.
804
805 option:-a, option:--all::
806 Equivalent to a single 'NAME' argument (LTTng tracepoint or logger
807 name) set to `*` (match anything).
808 +
809 You may :not: use this option with a 'NAME' argument.
810
811 option:-x 'XNAME'[,'XNAME']..., option:--exclude='XNAME'[,'XNAME']...::
812 Only match events of which none of the 'XNAME' arguments
813 matches the full name of the LTTng user space tracepoint.
814 +
815 Only available with the option:--userspace option.
816 +
817 'XNAME' is a globbing pattern: the `*` character means ``match
818 anything''. To match a literal `*` character, use :escwc:. To match
819 a literal `,` character, use :esccomma:.
820
821
822 Instrumentation point log level condition
823 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
824 See the <<inst-point-log-level-cond,Instrumentation point log level
825 condition>> section above.
826
827 At most one of:
828
829 option:--loglevel='LOGLEVEL'::
830 Only match events of which the log level of the LTTng tracepoint or
831 logging statement is at least as severe as 'LOGLEVEL'.
832
833 option:--loglevel-only='LOGLEVEL'::
834 Only match events of which the log level of the LTTng tracepoint or
835 logging statement is exactly 'LOGLEVEL'.
836
837 The instrumentation point log level options above are :not: available
838 with the option:--kernel option.
839
840
841 Event payload and context filter condition
842 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
843 See the <<filter-cond,Event payload and context filter condition>>
844 section above.
845
846 option:-f 'EXPR', option:--filter='EXPR'::
847 Only match events of which 'EXPR', which can contain references to
848 event payload and current context fields, is _true_.
849 +
850 This option is only available with the option:--tracepoint or
851 option:--syscall option.
852
853
854 include::common-lttng-cmd-help-options.txt[]
855
856
857 include::common-lttng-cmd-after-options.txt[]
858
859
860 [[examples]]
861 EXAMPLES
862 --------
863 .Create a recording event rule which matches all Linux system call events (current tracing session, default channel).
864 ====
865 See the option:--all and option:--syscall options.
866
867 [role="term"]
868 ----
869 $ lttng enable-event --kernel --all --syscall
870 ----
871 ====
872
873 .Create a recording event rule which matches user space tracepoint events named specifically (current tracing session, default channel).
874 ====
875 The recording event rule below matches all user space tracepoint events
876 of which the name starts with `my_provider:msg`.
877
878 [role="term"]
879 ----
880 $ lttng enable-event --userspace 'my_provider:msg*'
881 ----
882 ====
883
884 .Create three recording event rules which match Python logging events named specifically (current tracing session, default channel).
885 ====
886 [role="term"]
887 ----
888 $ lttng enable-event --python server3,ui.window,user-mgmt
889 ----
890 ====
891
892 .Create a recording event rule which matches Apache log4j logging events with a specific log level range (current tracing session, specific channel).
893 ====
894 See the option:--channel, option:--all, and option:--loglevel options.
895
896 [role="term"]
897 ----
898 $ lttng enable-event --log4j --channel=my-loggers \
899 --all --loglevel=INFO
900 ----
901 ====
902
903 .Create a recording event rule which matches specific Linux kprobe events (current tracing session, default channel).
904 ====
905 The recording event rule below matches the entry of `usb_disconnect()`
906 Linux kernel function calls. The records of such events are named `usbd`
907 (see the <<er-name,Event record name>> section above).
908
909 See the option:--probe option.
910
911 [role="term"]
912 ----
913 $ lttng enable-event --kernel --probe=usb_disconnect usbd
914 ----
915 ====
916
917 .Create a recording event rule which matches Linux kernel tracepoint events which satisfy an event payload and context filter (specific tracing session, default channel).
918 ====
919 See the option:--session and option:--filter options.
920
921 [role="term"]
922 ----
923 $ lttng enable-event --kernel --session=my-session 'sched_*' \
924 --filter='$ctx.preemptible && comm != "systemd*"'
925 ----
926 ====
927
928 .Enable two Linux kernel tracepoint recording event rules (current tracing session, specific channel).
929 ====
930 See the option:--channel option.
931
932 [role="term"]
933 ----
934 $ lttng enable-event --kernel --channel=tva ja,wendy
935 ----
936 ====
937
938
939 include::common-footer.txt[]
940
941
942 SEE ALSO
943 --------
944 man:lttng(1),
945 man:lttng-disable-event(1),
946 man:lttng-enable-channel(1),
947 man:lttng-list(1),
948 man:lttng-start(1),
949 man:lttng-track(1),
950 man:lttng-concepts(7)
This page took 0.050779 seconds and 6 git commands to generate.