1LTTNG-ENABLE-EVENT(1)            LTTng Manual            LTTNG-ENABLE-EVENT(1)
2
3
4

NAME

6       lttng-enable-event - Create or enable LTTng recording event rules
7

SYNOPSIS

9       Create or enable one or more recording event rules to match Linux
10       kernel tracepoint or system call events:
11
12       lttng [GENERAL OPTIONS] enable-event --kernel [--tracepoint | --syscall]
13             (--all | NAME[,NAME]...) [--filter=EXPR]
14             [--session=SESSION] [--channel=CHANNEL]
15
16       Create or enable a recording event rule to match Linux kernel events
17       created from a dynamic instrumentation point:
18
19       lttng [GENERAL OPTIONS] enable-event --kernel
20             (--probe=LOC | --function=LOC | --userspace-probe=LOC) RECORDNAME
21             [--session=SESSION] [--channel=CHANNEL]
22
23       Create or enable one or more recording event rules to match user space
24       tracepoint events:
25
26       lttng [GENERAL OPTIONS] enable-event --userspace [--tracepoint]
27             (--all | NAME[,NAME]...) [--exclude=XNAME[,XNAME]...]
28             [--loglevel=LOGLEVEL | --loglevel-only=LOGLEVEL] [--filter=EXPR]
29             [--session=SESSION] [--channel=CHANNEL]
30
31       Create or enable one or more recording event rules to match Java/Python
32       logging events:
33
34       lttng [GENERAL OPTIONS] enable-event (--jul | --log4j | --python)
35             [--tracepoint] (--all | NAME[,NAME]...)
36             [--loglevel=LOGLEVEL | --loglevel-only=LOGLEVEL] [--filter=EXPR]
37             [--session=SESSION] [--channel=CHANNEL]
38

DESCRIPTION

40       The lttng enable-event command does one of:
41
42       •   Create one or more recording event rules.
43
44       •   Enable one or more disabled recording event rules.
45
46           See the “Enable a disabled recording event rule” section below.
47
48       See lttng-concepts(7) to learn more about instrumentation points,
49       events, recording event rules, and event records.
50
51       The recording event rule(s) to create or enable belong to:
52
53       With the --session=SESSION option
54           The recording session named SESSION.
55
56       Without the --session option
57           The current recording session (see lttng-concepts(7) to learn more
58           about the current recording session).
59
60       With the --channel=CHANNEL option
61           The channel named CHANNEL.
62
63       Without the --channel option
64           The channel named channel0.
65
66           If there’s already a channel for the selected recording session and
67           domain which isn’t named channel0, the enable-event command fails.
68           Otherwise, it automatically creates it.
69
70       See the “EXAMPLES” section below for usage examples.
71
72       List the recording event rules of a specific recording session and/or
73       channel with the lttng-list(1) and lttng-status(1) commands.
74
75       Disable an enabled recording event rule with the lttng-disable-event(1)
76       command.
77
78   Overview of recording event rule conditions
79       For LTTng to emit and record an event E, E must satisfy all the
80       conditions of a recording event rule ER, that is:
81
82       Explicit conditions
83           You set the following conditions when you create or enable ER with
84           the enable-event command:
85
86           •   The instrumentation point type from which LTTng creates E has a
87               specific type.
88
89               See the “Instrumentation point type condition” section below.
90
91           •   A pattern matches the name of E while another pattern doesn’t.
92
93               See the “Event name condition” section below.
94
95           •   The log level of the instrumentation point from which LTTng
96               creates E is at least as severe as some value, or is exactly
97               some value.
98
99               See the “Instrumentation point log level condition” section
100               below.
101
102           •   The fields of the payload of E and the current context fields
103               satisfy a filter expression.
104
105               See the “Event payload and context filter condition” section
106               below.
107
108       Implicit conditions
109
110ER itself is enabled.
111
112               A recording event rule is enabled on creation.
113
114               Enable a disabled recording event rule with the enable-event
115               command.
116
117           •   The channel to which ER is attached is enabled.
118
119               A channel is enabled on creation.
120
121               Enable a disabled channel with the lttng-enable-channel(1)
122               command.
123
124           •   The recording session of ER is active (started).
125
126               A recording session is inactive (stopped) on creation.
127
128               Start an inactive recording session with the lttng-start(1)
129               command.
130
131           •   The process for which LTTng creates E is allowed to record
132               events.
133
134               All processes are allowed to record events on recording session
135               creation.
136
137               Use the lttng-track(1) and lttng-untrack(1) commands to select
138               which processes are allowed to record events based on specific
139               process attributes.
140
141       The dedicated command-line options of most conditions are optional: if
142       you don’t specify the option, the associated condition is always
143       satisfied.
144
145   Instrumentation point type condition
146       An event E satisfies the instrumentation point type condition of a
147       recording event rule if the instrumentation point from which LTTng
148       creates E is:
149
150       For the Linux kernel tracing domain (--kernel option)
151
152           With the --tracepoint option or without any other instrumentation
153           point type option
154               An LTTng kernel tracepoint, that is, a statically defined point
155               in the source code of the kernel image or of a kernel module
156               with LTTng kernel tracer macros.
157
158               As of LTTng 2.13.10, this is the default instrumentation point
159               type of the Linux kernel tracing domain, but this may change in
160               the future.
161
162               List the available Linux kernel tracepoints with lttng list
163               --kernel. See lttng-list(1) to learn more.
164
165           With the --syscall option
166               The entry and exit of a Linux kernel system call.
167
168               List the available Linux kernel system call instrumentation
169               points with lttng list --kernel --syscall. See lttng-list(1) to
170               learn more.
171
172           With the --probe option
173               A Linux kprobe, that is, a single probe dynamically placed in
174               the compiled kernel code.
175
176               The argument of the --probe option is the location of the
177               kprobe to insert, either a symbol or a memory address, while
178               RECORDNAME is the name of the record of E (see the “Event
179               record name” section below).
180
181               The payload of a Linux kprobe event is empty.
182
183           With the --userspace-probe option
184               A Linux user space probe, that is, a single probe dynamically
185               placed at the entry of a compiled user space
186               application/library function through the kernel.
187
188               The argument of the --userspace-probe option is the location of
189               the user space probe to insert, one of:
190
191               •   A path and symbol (ELF method).
192
193               •   A path, provider name, and probe name (SystemTap User-level
194                   Statically Defined Tracing (USDT) method; a DTrace-style
195                   marker).
196
197                   As of LTTng 2.13.10, LTTng only supports USDT probes which
198                   are NOT reference-counted.
199
200               RECORDNAME is the name of the record of E (see the “Event
201               record name” section below).
202
203               The payload of a Linux user space probe event is empty.
204
205           With the --function option
206               A Linux kretprobe, that is, two probes dynamically placed at
207               the entry and exit of a function in the compiled kernel code.
208
209               The argument of the --function option is the location of the
210               Linux kretprobe to insert, either a symbol or a memory address,
211               while RECORDNAME is the name of the record of E (see the “Event
212               record name” section below).
213
214               The payload of a Linux kretprobe event is empty.
215
216       For the user space tracing domain (--userspace option)
217
218           With or without the --tracepoint option
219               An LTTng user space tracepoint, that is, a statically defined
220               point in the source code of a C/C++ application/library with
221               LTTng user space tracer macros.
222
223               As of LTTng 2.13.10, this is the default and sole
224               instrumentation point type of the user space tracing domain,
225               but this may change in the future.
226
227               List the available user space tracepoints with lttng list
228               --userspace. See lttng-list(1) to learn more.
229
230       For the java.util.logging (--jul option), Apache log4j (--log4j
231       option), and Python (--python option) tracing domains
232
233           With or without the --tracepoint option
234               A logging statement.
235
236               As of LTTng 2.13.10, this is the default and sole
237               instrumentation point type of the java.util.logging, Apache
238               log4j, and Python tracing domains, but this may change in the
239               future.
240
241               List the available Java and Python loggers with lttng list
242               --jul, lttng list --log4j, and lttng list --python. See lttng-
243               list(1) to learn more.
244
245   Event name condition
246       An event E satisfies the event name condition of a recording event
247       rule ER if the two following statements are true:
248
249       •   You specify the --all option or, depending on the instrumentation
250           type condition (see the “Instrumentation point type condition”
251           section above) of ER, NAME matches:
252
253           LTTng tracepoint
254               The full name of the tracepoint from which LTTng creates E.
255
256               Note that the full name of a user space tracepoint is
257               PROVIDER:NAME, where PROVIDER is the tracepoint provider name
258               and NAME is the tracepoint name.
259
260           Logging statement
261               The name of the Java or Python logger from which LTTng
262               creates E.
263
264           Linux system call
265               The name of the system call, without any sys_ prefix, from
266               which LTTng creates E.
267
268       •   You don’t specify the --exclude=XNAME[,XNAME]... option or,
269           depending on the instrumentation type condition of ER, none of the
270           XNAME arguments matches the full name of the user space tracepoint
271           from which LTTng creates E.
272
273           The --exclude option is only available with the --userspace option.
274
275       This condition is only meaningful for the LTTng tracepoint, logging
276       statement, and Linux system call instrumentation point types: it’s
277       always satisfied for the other types.
278
279       In all cases, NAME and XNAME are globbing patterns: the * character
280       means “match anything”. To match a literal * character, use \*. To
281       match a literal , character, use \,.
282
283       Important
284           Make sure to single-quote NAME and XNAME when they contain the *
285           character and when you run the enable-event command from a shell.
286
287       With the LTTng tracepoint, logging statement, and Linux system call
288       instrumentation point types, the enable-event command creates or
289       enables one independent recording event rule per NAME argument
290       (non-option, comma-separated). With the --all option, the enable-event
291       command creates or enables a single recording event rule.
292
293   Instrumentation point log level condition
294       An event E satisfies the instrumentation point log level condition of a
295       recording event rule if either:
296
297       •   The --loglevel and --loglevel-only options are missing.
298
299       •   The log level of the LTTng user space tracepoint or logging
300           statement which creates E is:
301
302           With the --loglevel=LOGLEVEL option
303               At least as severe as LOGLEVEL.
304
305           With the --loglevel-only=LOGLEVEL option
306               Exactly LOGLEVEL.
307
308       This condition is only meaningful for the LTTng user space tracepoint
309       and logging statement instrumentation point types: it’s always
310       satisfied for other types.
311
312       The available values of LOGLEVEL are, depending on the tracing domain,
313       from the most to the least severe:
314
315       User space (--userspace option)
316
317           •   EMERG (0)
318
319           •   ALERT (1)
320
321           •   CRIT (2)
322
323           •   ERR (3)
324
325           •   WARNING (4)
326
327           •   NOTICE (5)
328
329           •   INFO (6)
330
331           •   DEBUG_SYSTEM (7)
332
333           •   DEBUG_PROGRAM (8)
334
335           •   DEBUG_PROCESS (9)
336
337           •   DEBUG_MODULE (10)
338
339           •   DEBUG_UNIT (11)
340
341           •   DEBUG_FUNCTION (12)
342
343           •   DEBUG_LINE (13)
344
345           •   DEBUG (14)
346
347       java.util.logging (--jul option)
348
349OFF (INT32_MAX)
350
351           •   SEVERE (1000)
352
353           •   WARNING (900)
354
355           •   INFO (800)
356
357           •   CONFIG (700)
358
359           •   FINE (500)
360
361           •   FINER (400)
362
363           •   FINEST (300)
364
365ALL (INT32_MIN)
366
367       Apache log4j (--log4j option)
368
369OFF (INT32_MAX)
370
371           •   FATAL (50000)
372
373           •   ERROR (40000)
374
375           •   WARN (30000)
376
377           •   INFO (20000)
378
379           •   DEBUG (10000)
380
381           •   TRACE (5000)
382
383ALL (INT32_MIN)
384
385       Python (--python option)
386
387           •   CRITICAL (50)
388
389           •   ERROR (40)
390
391           •   WARNING (30)
392
393           •   INFO (20)
394
395           •   DEBUG (10)
396
397           •   NOTSET (0)
398
399   Event payload and context filter condition
400       An event E satisfies the event payload and context filter condition of
401       a recording event rule if the --filter=EXPR option is missing or if
402       EXPR is true.
403
404       This condition is only meaningful for the LTTng tracepoint and Linux
405       system call instrumentation point types: it’s always satisfied for
406       other types.
407
408       EXPR can contain references to the payload fields of E and to the
409       current context fields.
410
411       Important
412           Make sure to single-quote EXPR when you run the enable-event
413           command from a shell, as filter expressions typically include
414           characters having a special meaning for most shells.
415
416       The expected syntax of EXPR is similar to the syntax of a C language
417       conditional expression (an expression which an if statement can
418       evaluate), but there are a few differences:
419
420       •   A NAME expression identifies an event payload field named NAME (a
421           C identifier).
422
423           Use the C language dot and square bracket notations to access
424           nested structure and array/sequence fields. You can only use a
425           constant, positive integer number within square brackets. If the
426           index is out of bounds, EXPR is false.
427
428           The value of an enumeration field is an integer.
429
430           When a field expression doesn’t exist, EXPR is false.
431
432           Examples: my_field, target_cpu, seq[7], msg.user[1].data[2][17].
433
434       •   A $ctx.TYPE expression identifies the statically-known context
435           field having the type TYPE (a C identifier).
436
437           List the available statically-known context field names with the
438           lttng-add-context(1) command.
439
440           When a field expression doesn’t exist, EXPR is false.
441
442           Examples: $ctx.prio, $ctx.preemptible, $ctx.perf:cpu:stalled-
443           cycles-frontend.
444
445       •   A $app.PROVIDER:TYPE expression identifies the application-specific
446           context field having the type TYPE (a C identifier) from the
447           provider PROVIDER (a C identifier).
448
449           When a field expression doesn’t exist, EXPR is false.
450
451           Example: $app.server:cur_user.
452
453       •   Compare strings, either string fields or string literals
454           (double-quoted), with the == and != operators.
455
456           When comparing to a string literal, the * character means “match
457           anything”. To match a literal * character, use \*.
458
459           Examples: my_field == "user34", my_field == my_other_field,
460           my_field == "192.168.*".
461
462       •   The precedence table of the operators which are supported in EXPR
463           is as follows. In this table, the highest precedence is 1:
464
465           ┌───────────┬──────────┬─────────────────┬───────────────┐
466Precedence Operator Description     Associativity 
467           ├───────────┼──────────┼─────────────────┼───────────────┤
468           │1          │ -        │ Unary minus     │ Right-to-left │
469           ├───────────┼──────────┼─────────────────┼───────────────┤
470           │1          │ +        │ Unary plus      │ Right-to-left │
471           ├───────────┼──────────┼─────────────────┼───────────────┤
472           │1          │ !        │ Logical NOT     │ Right-to-left │
473           ├───────────┼──────────┼─────────────────┼───────────────┤
474           │1          │ ~        │ Bitwise NOT     │ Right-to-left │
475           ├───────────┼──────────┼─────────────────┼───────────────┤
476           │2          │ <<       │ Bitwise left    │ Left-to-right │
477           │           │          │ shift           │               │
478           ├───────────┼──────────┼─────────────────┼───────────────┤
479           │2          │ >>       │ Bitwise right   │ Left-to-right │
480           │           │          │ shift           │               │
481           ├───────────┼──────────┼─────────────────┼───────────────┤
482           │3          │ &        │ Bitwise AND     │ Left-to-right │
483           ├───────────┼──────────┼─────────────────┼───────────────┤
484           │4          │ ^        │ Bitwise XOR     │ Left-to-right │
485           ├───────────┼──────────┼─────────────────┼───────────────┤
486           │5          │ |        │ Bitwise OR      │ Left-to-right │
487           ├───────────┼──────────┼─────────────────┼───────────────┤
488           │6          │ <        │ Less than       │ Left-to-right │
489           ├───────────┼──────────┼─────────────────┼───────────────┤
490           │6          │ <=       │ Less than or    │ Left-to-right │
491           │           │          │ equal to        │               │
492           ├───────────┼──────────┼─────────────────┼───────────────┤
493           │6          │ >        │ Greater than    │ Left-to-right │
494           ├───────────┼──────────┼─────────────────┼───────────────┤
495           │6          │ >=       │ Greater than or │ Left-to-right │
496           │           │          │ equal to        │               │
497           ├───────────┼──────────┼─────────────────┼───────────────┤
498           │7          │ ==       │ Equal to        │ Left-to-right │
499           ├───────────┼──────────┼─────────────────┼───────────────┤
500           │7          │ !=       │ Not equal to    │ Left-to-right │
501           ├───────────┼──────────┼─────────────────┼───────────────┤
502           │8          │ &&       │ Logical AND     │ Left-to-right │
503           ├───────────┼──────────┼─────────────────┼───────────────┤
504           │9          │ ||       │ Logical OR      │ Left-to-right │
505           └───────────┴──────────┴─────────────────┴───────────────┘
506           Parentheses are supported to bypass the default order.
507
508           Important
509               Unlike the C language, the bitwise AND and OR operators (& and
510               |) in EXPR take precedence over relational operators (<, <=, >,
511               >=, ==, and !=). This means the expression 2 & 2 == 2 is true
512               while the equivalent C expression is false.
513           The arithmetic operators are NOT supported.
514
515           LTTng first casts all integer constants and fields to signed 64-bit
516           integers. The representation of negative integers is two’s
517           complement. This means that, for example, the signed 8-bit integer
518           field 0xff (-1) becomes 0xffffffffffffffff (still -1) once casted.
519
520           Before a bitwise operator is applied, LTTng casts all its operands
521           to unsigned 64-bit integers, and then casts the result back to a
522           signed 64-bit integer. For the bitwise NOT operator, it’s the
523           equivalent of this C expression:
524
525               (int64_t) ~((uint64_t) val)
526
527           For the binary bitwise operators, it’s the equivalent of those
528           C expressions:
529
530               (int64_t) ((uint64_t) lhs >> (uint64_t) rhs)
531               (int64_t) ((uint64_t) lhs << (uint64_t) rhs)
532               (int64_t) ((uint64_t) lhs & (uint64_t) rhs)
533               (int64_t) ((uint64_t) lhs ^ (uint64_t) rhs)
534               (int64_t) ((uint64_t) lhs | (uint64_t) rhs)
535
536           If the right-hand side of a bitwise shift operator (<< and >>) is
537           not in the [0, 63] range, then EXPR is false.
538
539       Note
540           Use the lttng-track(1) and lttng-untrack(1) commands to allow or
541           disallow processes to record LTTng events based on their attributes
542           instead of using equivalent statically-known context fields in EXPR
543           like $ctx.pid.
544
545           The former method is much more efficient.
546
547       EXPR examples:
548
549           msg_id == 23 && size >= 2048
550
551           $ctx.procname == "lttng*" && (!flag || poel < 34)
552
553           $app.my_provider:my_context == 17.34e9 || some_enum >= 14
554
555           $ctx.cpu_id == 2 && filename != "*.log"
556
557           eax_reg & 0xff7 == 0x240 && x[4] >> 12 <= 0x1234
558
559   Event record name
560       When LTTng records an event E, the resulting event record has a name
561       which depends on the instrumentation point type condition (see the
562       “Instrumentation point type condition” section above) of the recording
563       event rule which matched E:
564
565       LTTng tracepoint (--kernel/--userspace and --tracepoint options)
566           Full name of the tracepoint from which LTTng creates E.
567
568           Note that the full name of a user space tracepoint is
569           PROVIDER:NAME, where PROVIDER is the tracepoint provider name and
570           NAME is the tracepoint name.
571
572       java.util.logging logging statement (--jul and --tracepoint options)
573           lttng_jul:event
574
575           Such an event record has a string field logger_name which contains
576           the name of the java.util.logging logger from which LTTng
577           creates E.
578
579       Apache log4j logging statement (--log4j and --tracepoint options)
580           lttng_log4j:event
581
582           Such an event record has a string field logger_name which contains
583           the name of the Apache log4j logger from which LTTng creates E.
584
585       Python logging statement (--python and --tracepoint options)
586           lttng_python:event
587
588           Such an event record has a string field logger_name which contains
589           the name of the Python logger from which LTTng creates E.
590
591       Linux system call (--kernel and --syscall options)
592
593           Entry
594               syscall_entry_NAME, where NAME is the name of the system call
595               from which LTTng creates E, without any sys_ prefix.
596
597           Exit
598               syscall_exit_NAME, where NAME is the name of the system call
599               from which LTTng creates E, without any sys_ prefix.
600
601       Linux kprobe (--kernel and --probe options), Linux user space probe
602       (--kernel and --userspace-probe options)
603           RECORDNAME (first non-option argument).
604
605       Linux kretprobe (--kernel and --function options)
606
607           Entry
608               RECORDNAME_entry
609
610           Exit
611               RECORDNAME_exit
612
613   Enable a disabled recording event rule
614       The enable-event command can enable a disabled recording event rule, as
615       listed in the output of the lttng-list(1) command.
616
617       You may enable a disabled recording event rule regardless of the
618       activity (started or stopped) of its recording session (see lttng-
619       start(1) and lttng-stop(1)).
620
621       To enable a disabled recording event rule, run the enable-event command
622       with the exact same options and arguments that you used to create it.
623       In particular, with the --filter=EXPR option, EXPR must be the exact
624       same string as the one you used on creation.
625

OPTIONS

627       See lttng(1) for GENERAL OPTIONS.
628
629   Tracing domain
630       One of:
631
632       -j, --jul
633           Create or enable recording event rules in the java.util.logging
634           (JUL) tracing domain.
635
636       -k, --kernel
637           Create or enable recording event rules in the Linux kernel tracing
638           domain.
639
640       -l, --log4j
641           Create or enable recording event rules in the Apache log4j tracing
642           domain.
643
644       -p, --python
645           Create or enable recording event rules in the Python tracing
646           domain.
647
648       -u, --userspace
649           Create or enable recording event rules in the user space tracing
650           domain.
651
652   Recording target
653       -c CHANNEL, --channel=CHANNEL
654           Create or enable recording event rules attached to the channel
655           named CHANNEL instead of channel0.
656
657       -s SESSION, --session=SESSION
658           Create or enable recording event rules in the recording session
659           named SESSION instead of the current recording session.
660
661   Instrumentation point type condition
662       See the “Instrumentation point type condition” section above.
663
664       At most one of:
665
666       --function=LOC
667           Only match Linux kretprobe events.
668
669           Only available with the --kernel option.
670
671           LOC is one of:
672
673           •   A function address (0x hexadecimal prefix supported).
674
675           •   A function symbol name.
676
677           •   A function symbol name and an offset (SYMBOL+OFFSET format).
678
679           You must specify the event record name with RECORDNAME. See the
680           “Event record name” section above to learn more.
681
682       --probe=LOC
683           Only match Linux kprobe events.
684
685           Only available with the --kernel option.
686
687           LOC is one of:
688
689           •   An address (0x hexadecimal prefix supported).
690
691           •   A symbol name.
692
693           •   A symbol name and an offset (SYMBOL+OFFSET format).
694
695           You must specify the event record name with RECORDNAME. See the
696           “Event record name” section above to learn more.
697
698       --userspace-probe=LOC
699           Only match Linux user space probe events.
700
701           Only available with the --kernel option.
702
703           LOC is one of:
704
705           [elf:]PATH:SYMBOL
706               Probe an available symbol within a user space application or
707               library.
708
709               PATH
710                   Application or library path.
711
712                   One of:
713
714                   •   An absolute path.
715
716                   •   A relative path.
717
718                   •   The name of an application as found in the directories
719                       listed in the PATH environment variable.
720
721               SYMBOL
722                   Symbol name of the function of which to instrument the
723                   entry.
724
725                   SYMBOL can be any defined code symbol in the output of the
726                   nm(1) command, including with its --dynamic option, which
727                   lists dynamic symbols.
728
729               As of LTTng 2.13.10, not specifying elf: is equivalent to
730               specifying it, but this default may change in the future.
731
732               Examples:
733
734--userspace-probe=/usr/lib/libc.so.6:malloc
735
736--userspace-probe=./myapp:createUser
737
738--userspace-probe=elf:httpd:ap_run_open_htaccess
739
740           sdt:PATH:PROVIDER:NAME
741               Use a SystemTap User-level Statically Defined Tracing (USDT)
742               probe within a user space application or library.
743
744               PATH
745                   Application or library path.
746
747                   This can be:
748
749                   •   An absolute path.
750
751                   •   A relative path.
752
753                   •   The name of an application as found in the directories
754                       listed in the PATH environment variable.
755
756               PROVIDER, NAME
757                   USDT provider and probe names.
758
759                   For example, with the following USDT probe:
760
761                       DTRACE_PROBE2("server", "accept_request",
762                                     request_id, ip_addr);
763
764                   The provider/probe name pair is server:accept_request.
765
766               Example: --userspace-
767               probe=sdt:./build/server:server:accept_request
768
769           You must specify the event record name with RECORDNAME. See the
770           “Event record name” section above to learn more.
771
772       --syscall
773           Only match Linux system call events.
774
775           Only available with the --kernel option.
776
777       --tracepoint
778           Only match:
779
780           With the --kernel or --userspace option
781               LTTng tracepoint events.
782
783           With the --jul, --log4j, or --python option
784               Logging events.
785
786       With the --kernel, not specifying any of the instrumentation point type
787       options is equivalent to specifying the --tracepoint option, but this
788       default may change in the future.
789
790       With the --userspace, --jul, --log4j, and --python options, not
791       specifying the --tracepoint option is equivalent to specifying it, but
792       this default may change in the future.
793
794   Event name condition
795       See the “Event name condition” section above.
796
797       -a, --all
798           Equivalent to a single NAME argument (LTTng tracepoint or logger
799           name) set to * (match anything).
800
801           You may NOT use this option with a NAME argument.
802
803       -x XNAME[,XNAME]..., --exclude=XNAME[,XNAME]...
804           Only match events of which none of the XNAME arguments matches the
805           full name of the LTTng user space tracepoint.
806
807           Only available with the --userspace option.
808
809           XNAME is a globbing pattern: the * character means “match
810           anything”. To match a literal * character, use \*. To match a
811           literal , character, use \,.
812
813   Instrumentation point log level condition
814       See the “Instrumentation point log level condition” section above.
815
816       At most one of:
817
818       --loglevel=LOGLEVEL
819           Only match events of which the log level of the LTTng tracepoint or
820           logging statement is at least as severe as LOGLEVEL.
821
822       --loglevel-only=LOGLEVEL
823           Only match events of which the log level of the LTTng tracepoint or
824           logging statement is exactly LOGLEVEL.
825
826       The instrumentation point log level options above are NOT available
827       with the --kernel option.
828
829   Event payload and context filter condition
830       See the “Event payload and context filter condition” section above.
831
832       -f EXPR, --filter=EXPR
833           Only match events of which EXPR, which can contain references to
834           event payload and current context fields, is true.
835
836           This option is only available with the --tracepoint or --syscall
837           option.
838
839   Program information
840       -h, --help
841           Show help.
842
843           This option attempts to launch /usr/bin/man to view this manual
844           page. Override the manual pager path with the LTTNG_MAN_BIN_PATH
845           environment variable.
846
847       --list-options
848           List available command options and quit.
849

EXIT STATUS

851       0
852           Success
853
854       1
855           Command error
856
857       2
858           Undefined command
859
860       3
861           Fatal error
862
863       4
864           Command warning (something went wrong during the command)
865

ENVIRONMENT

867       LTTNG_ABORT_ON_ERROR
868           Set to 1 to abort the process after the first error is encountered.
869
870       LTTNG_HOME
871           Path to the LTTng home directory.
872
873           Defaults to $HOME.
874
875           Useful when the Unix user running the commands has a non-writable
876           home directory.
877
878       LTTNG_MAN_BIN_PATH
879           Absolute path to the manual pager to use to read the LTTng
880           command-line help (with lttng-help(1) or with the --help option)
881           instead of /usr/bin/man.
882
883       LTTNG_SESSION_CONFIG_XSD_PATH
884           Path to the directory containing the session.xsd recording session
885           configuration XML schema.
886
887       LTTNG_SESSIOND_PATH
888           Absolute path to the LTTng session daemon binary (see lttng-
889           sessiond(8)) to spawn from the lttng-create(1) command.
890
891           The --sessiond-path general option overrides this environment
892           variable.
893

FILES

895       $LTTNG_HOME/.lttngrc
896           Unix user’s LTTng runtime configuration.
897
898           This is where LTTng stores the name of the Unix user’s current
899           recording session between executions of lttng(1).  lttng-create(1)
900           and lttng-set-session(1) set the current recording session.
901
902       $LTTNG_HOME/lttng-traces
903           Default output directory of LTTng traces in local and snapshot
904           modes.
905
906           Override this path with the --output option of the lttng-create(1)
907           command.
908
909       $LTTNG_HOME/.lttng
910           Unix user’s LTTng runtime and configuration directory.
911
912       $LTTNG_HOME/.lttng/sessions
913           Default directory containing the Unix user’s saved recording
914           session configurations (see lttng-save(1) and lttng-load(1)).
915
916       /usr/local/etc/lttng/sessions
917           Directory containing the system-wide saved recording session
918           configurations (see lttng-save(1) and lttng-load(1)).
919
920       Note
921           $LTTNG_HOME defaults to the value of the HOME environment variable.
922

EXAMPLES

924       Example 1. Create a recording event rule which matches all Linux system
925       call events (current recording session, default channel).
926
927           See the --all and --syscall options.
928
929               $ lttng enable-event --kernel --all --syscall
930
931       Example 2. Create a recording event rule which matches user space
932       tracepoint events named specifically (current recording session,
933       default channel).
934
935           The recording event rule below matches all user space tracepoint
936           events of which the name starts with my_provider:msg.
937
938               $ lttng enable-event --userspace 'my_provider:msg*'
939
940       Example 3. Create three recording event rules which match Python
941       logging events named specifically (current recording session, default
942       channel).
943
944               $ lttng enable-event --python server3,ui.window,user-mgmt
945
946       Example 4. Create a recording event rule which matches Apache log4j
947       logging events with a specific log level range (current recording
948       session, specific channel).
949
950           See the --channel, --all, and --loglevel options.
951
952               $ lttng enable-event --log4j --channel=my-loggers \
953                                    --all --loglevel=INFO
954
955       Example 5. Create a recording event rule which matches specific Linux
956       kprobe events (current recording session, default channel).
957
958           The recording event rule below matches the entry of
959           usb_disconnect() Linux kernel function calls. The records of such
960           events are named usbd (see the “Event record name” section above).
961
962           See the --probe option.
963
964               $ lttng enable-event --kernel --probe=usb_disconnect usbd
965
966       Example 6. Create a recording event rule which matches Linux kernel
967       tracepoint events which satisfy an event payload and context filter
968       (specific recording session, default channel).
969
970           See the --session and --filter options.
971
972               $ lttng enable-event --kernel --session=my-session 'sched_*' \
973                       --filter='$ctx.preemptible && comm != "systemd*"'
974
975       Example 7. Enable two Linux kernel tracepoint recording event rules
976       (current recording session, specific channel).
977
978           See the --channel option.
979
980               $ lttng enable-event --kernel --channel=tva ja,wendy
981

RESOURCES

983       •   LTTng project website <https://lttng.org>
984
985       •   LTTng documentation <https://lttng.org/docs>
986
987       •   LTTng bug tracker <https://bugs.lttng.org>
988
989       •   Git repositories <https://git.lttng.org>
990
991       •   GitHub organization <https://github.com/lttng>
992
993       •   Continuous integration <https://ci.lttng.org/>
994
995       •   Mailing list <https://lists.lttng.org/> for support and
996           development: lttng-dev@lists.lttng.org
997
998       •   IRC channel <irc://irc.oftc.net/lttng>: #lttng on irc.oftc.net
999
1001       This program is part of the LTTng-tools project.
1002
1003       LTTng-tools is distributed under the GNU General Public License
1004       version 2 <http://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html>.
1005       See the LICENSE <https://github.com/lttng/lttng-
1006       tools/blob/master/LICENSE> file for details.
1007

THANKS

1009       Special thanks to Michel Dagenais and the DORSAL laboratory
1010       <http://www.dorsal.polymtl.ca/> at École Polytechnique de Montréal for
1011       the LTTng journey.
1012
1013       Also thanks to the Ericsson teams working on tracing which helped us
1014       greatly with detailed bug reports and unusual test cases.
1015

SEE ALSO

1017       lttng(1), lttng-disable-event(1), lttng-enable-channel(1), lttng-
1018       list(1), lttng-start(1), lttng-track(1), lttng-concepts(7)
1019
1020
1021
1022LTTng 2.13.10                    14 June 2021            LTTNG-ENABLE-EVENT(1)
Impressum