lttng-enable-event(1)

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

NAME

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

SYNOPSIS

9       Create or enable Linux kernel event rules:
10
11       lttng [GENERAL OPTIONS] enable-event --kernel
12             [--probe=SOURCE | --function=SOURCE | --syscall]
13             [--filter=EXPR] [--session=SESSION]
14             [--channel=CHANNEL] EVENT[,EVENT]...
15
16       Create or enable an "all" Linux kernel event rule:
17
18       lttng [GENERAL OPTIONS] enable-event --kernel --all [--syscall]
19             [--filter=EXPR] [--session=SESSION] [--channel=CHANNEL]
20
21       Create or enable application event rules:
22
23       lttng [GENERAL OPTIONS] enable-event
24             (--userspace | --jul | --log4j | --python)
25             [--filter=EXPR] [--exclude=EVENT[,EVENT]...]
26             [--loglevel=LOGLEVEL | --loglevel-only=LOGLEVEL]
27             [--session=SESSION] [--channel=CHANNEL] (--all | EVENT[,EVENT]...)
28

DESCRIPTION

30       The lttng enable-event command can create a new event rule, or enable
31       one or more existing and disabled ones.
32
33       An event rule created by lttng enable-event is a set of conditions that
34       must be satisfied in order for an actual event to be emitted by an
35       LTTng tracer when the execution of an application or the Linux kernel
36       reaches an event source (tracepoint, system call, dynamic probe). Event
37       sources can be listed with the lttng-list(1) command.
38
39       The lttng-disable-event(1) command can be used to disable existing
40       event rules.
41
42       Event rules are always assigned to a channel when they are created. If
43       the --channel option is omitted, a default channel named channel0 is
44       used (and created automatically if it does not exist for the specified
45       domain in the selected tracing session).
46
47       If the --session option is omitted, the chosen channel is picked from
48       the current tracing session.
49
50       Events can be enabled while tracing is active (use lttng-start(1) to
51       make a tracing session active).
52
53   Event source types
54       Four types of event sources are available in the Linux kernel tracing
55       domain (--kernel option):
56
57       Tracepoint (--tracepoint option; default)
58           A Linux kernel tracepoint, that is, a static instrumentation point
59           placed in the kernel source code. Standard tracepoints are designed
60           and placed in the source code by developers and record useful
61           payload fields.
62
63       Dynamic probe (--probe option)
64           A Linux kernel kprobe, that is, an instrumentation point placed
65           dynamically in the compiled kernel code. Dynamic probe events do
66           not record any payload field.
67
68       Function probe (--function option)
69           A Linux kernel kretprobe, that is, two instrumentation points
70           placed dynamically where a function is entered and where it returns
71           in the compiled kernel code. Function probe events do not record
72           any payload field.
73
74       System call (--syscall option)
75           A Linux kernel system call. Two instrumentation points are
76           statically placed where a system call function is entered and where
77           it returns in the compiled kernel code. System call event sources
78           record useful payload fields.
79
80       The application tracing domains (--userspace, --jul, --log4j, or
81       --python options) only support tracepoints. In the cases of the JUL,
82       Apache log4j, and Python domains, the event names correspond to logger
83       names.
84
85   Understanding event rule conditions
86       When creating an event rule with lttng enable-event, conditions are
87       specified using options. The logical conjunction (logical AND) of all
88       those conditions must be true when an event source is reached by an
89       application or by the Linux kernel in order for an actual event to be
90       emitted by an LTTng tracer.
91
92       Any condition that is not explicitly specified on creation is
93       considered a don’t care.
94
95       For example, consider the following commands:
96
97           $ lttng enable-event --userspace hello:world
98           $ lttng enable-event --userspace hello:world --loglevel=TRACE_INFO
99
100       Here, two event rules are created. The first one has a single
101       condition: the tracepoint name must match hello:world. The second one
102       has two conditions:
103
104       ·   The tracepoint name must match hello:world, and
105
106       ·   The tracepoint’s defined log level must be at least as severe as
107           the TRACE_INFO level.
108
109       In this case, the second event rule is pointless because the first one
110       is more general: it does not care about the tracepoint’s log level. If
111       an event source matching both event rules is reached by the
112       application’s execution, only one event is emitted.
113
114       The available conditions for the Linux kernel domain are:
115
116       ·   Tracepoint/system call name (EVENT argument with --tracepoint or
117           --syscall options) or dynamic probe/function name/address (--probe
118           or --function option’s argument) which must match event source’s
119           equivalent.
120
121           You can use * characters at any place in the tracepoint or system
122           call name as wildcards to match zero or more characters. To use a
123           literal * character, use \*.
124
125       ·   Filter expression (--filter option) executed against the dynamic
126           values of event fields at execution time that must evaluate to
127           true. See the Filter expression syntax section below for more
128           information.
129
130       The available conditions for the application domains are:
131
132       ·   Tracepoint name (EVENT with --tracepoint option) which must match
133           event source’s equivalent.
134
135           You can use * characters at any place in the tracepoint name as
136           wildcards to match zero or more characters. To use a literal *
137           character, use \*. When you create an event rule with a tracepoint
138           name containing a wildcard, you can exclude specific tracepoint
139           names from the match with the --exclude option.
140
141       ·   Filter expression (--filter option) executed against the dynamic
142           values of event fields at execution time that must evaluate to
143           true. See the Filter expression syntax section below for more
144           information.
145
146       ·   Event’s log level that must be at least as severe as a given log
147           level (--loglevel option) or match exactly a given log level
148           (--loglevel-only option).
149
150       When using lttng enable-event with a set of conditions that does not
151       currently exist for the chosen tracing session, domain, and channel, a
152       new event rule is created. Otherwise, the existing event rule is
153       enabled if it is currently disabled (see lttng-disable-event(1)).
154
155       The --all option can be used alongside the --tracepoint or --syscall
156       options. When this option is used, no EVENT argument must be specified.
157       This option defines a single event rule matching all the possible
158       events of a given tracing domain for the chosen channel and tracing
159       session. It is the equivalent of an EVENT argument named * (wildcard).
160
161   Filter expression syntax
162       A filter expression can be specified with the --filter option when
163       creating a new event rule. If the filter expression evaluates to true
164       when executed against the dynamic values of an event’s fields when
165       tracing, the filtering condition passes.
166
167           Note
168           Make sure to single-quote the filter expression when running the
169           command from a shell, as filter expressions typically include
170           characters having a special meaning for most shells.
171
172       The filter expression syntax is very similar to C language conditional
173       expressions (expressions that can be evaluated by an if statement).
174
175       The following logical operators are supported:
176
177       ┌──────────────────────────┬────────┐
178       │Name                      │ Syntax │
179       ├──────────────────────────┼────────┤
180       │                          │        │
181       │Logical negation (NOT)    │ !a     │
182       ├──────────────────────────┼────────┤
183       │                          │        │
184       │Logical conjunction (AND) │ a && b │
185       ├──────────────────────────┼────────┤
186       │                          │        │
187       │Logical disjunction (OR)  │ a || b │
188       └──────────────────────────┴────────┘
189
190       The following comparison operators/relational operators are supported:
191
192       ┌─────────────────────────┬────────┐
193       │Name                     │ Syntax │
194       ├─────────────────────────┼────────┤
195       │                         │        │
196       │Equal to                 │ a == b │
197       ├─────────────────────────┼────────┤
198       │                         │        │
199       │Not equal to             │ a != b │
200       ├─────────────────────────┼────────┤
201       │                         │        │
202       │Greater than             │ a > b  │
203       ├─────────────────────────┼────────┤
204       │                         │        │
205       │Less than                │ a < b  │
206       ├─────────────────────────┼────────┤
207       │                         │        │
208       │Greater than or equal to │ a >= b │
209       ├─────────────────────────┼────────┤
210       │                         │        │
211       │Less than or equal to    │ a <= b │
212       └─────────────────────────┴────────┘
213
214       The arithmetic and bitwise operators are NOT supported.
215
216       The precedence table of the operators above is the same as the one of
217       the C language. Parentheses are supported to bypass this.
218
219       The dynamic value of an event field is read by using its name as a C
220       identifier.
221
222       The dynamic value of a statically-known context field is read by
223       prefixing its name with $ctx.. Statically-known context fields are
224       context fields added to channels without the $app. prefix using the
225       lttng-add-context(1) command. $ctx.cpu_id is also available as the ID
226       of the CPU which emits the event.
227
228       The dynamic value of an application-specific context field is read by
229       prefixing its name with $app. (follows the format used to add such a
230       context field with the lttng-add-context(1) command).
231
232       When a comparison includes a non existent event field, the whole filter
233       expression evaluates to false (the event is discarded).
234
235       C integer and floating point number constants are supported, as well as
236       literal strings between double quotes ("). You can use * characters at
237       any place in a literal string as wildcards to match zero or more
238       characters. To use a literal * character, use \*.
239
240       LTTng-UST enumeration fields can be compared to integer values (fields
241       or constants).
242
243           Note
244           Although it is possible to filter the process ID of an event when
245           the pid context has been added to its channel using, for example,
246           $ctx.pid == 2832, it is recommended to use the PID tracker instead,
247           which is much more efficient (see lttng-track(1)).
248
249       Examples:
250
251           msg_id == 23 && size >= 2048
252
253           $ctx.procname == "lttng*" && (!flag || poel < 34)
254
255           $app.my_provider:my_context == 17.34e9 || some_enum >= 14
256
257           $ctx.cpu_id == 2 && filename != "*.log"
258
259   Log levels
260       Tracepoints and log statements in applications have an attached log
261       level. Application event rules can contain a log level condition.
262
263       With the --loglevel option, the event source’s log level must be at
264       least as severe as the option’s argument. With the --loglevel-only
265       option, the event source’s log level must match the option’s argument.
266
267       The available log levels are:
268
269       User space domain (--userspace option)
270           Shortcuts such as system are allowed.
271
272           ·   TRACE_EMERG (0)
273
274           ·   TRACE_ALERT (1)
275
276           ·   TRACE_CRIT (2)
277
278           ·   TRACE_ERR (3)
279
280           ·   TRACE_WARNING (4)
281
282           ·   TRACE_NOTICE (5)
283
284           ·   TRACE_INFO (6)
285
286           ·   TRACE_DEBUG_SYSTEM (7)
287
288           ·   TRACE_DEBUG_PROGRAM (8)
289
290           ·   TRACE_DEBUG_PROCESS (9)
291
292           ·   TRACE_DEBUG_MODULE (10)
293
294           ·   TRACE_DEBUG_UNIT (11)
295
296           ·   TRACE_DEBUG_FUNCTION (12)
297
298           ·   TRACE_DEBUG_LINE (13)
299
300           ·   TRACE_DEBUG (14)
301
302       java.util.logging domain (--jul option)
303           Shortcuts such as severe are allowed.
304
305           ·   JUL_OFF (INT32_MAX)
306
307           ·   JUL_SEVERE (1000)
308
309           ·   JUL_WARNING (900)
310
311           ·   JUL_INFO (800)
312
313           ·   JUL_CONFIG (700)
314
315           ·   JUL_FINE (500)
316
317           ·   JUL_FINER (400)
318
319           ·   JUL_FINEST (300)
320
321           ·   JUL_ALL (INT32_MIN)
322
323       Apache log4j domain (--log4j option)
324           Shortcuts such as severe are allowed.
325
326           ·   LOG4J_OFF (INT32_MAX)
327
328           ·   LOG4J_FATAL (50000)
329
330           ·   LOG4J_ERROR (40000)
331
332           ·   LOG4J_WARN (30000)
333
334           ·   LOG4J_INFO (20000)
335
336           ·   LOG4J_DEBUG (10000)
337
338           ·   LOG4J_TRACE (5000)
339
340           ·   LOG4J_ALL (INT32_MIN)
341
342       Python domain (--python option)
343           Shortcuts such as critical are allowed.
344
345           ·   PYTHON_CRITICAL (50)
346
347           ·   PYTHON_ERROR (40)
348
349           ·   PYTHON_WARNING (30)
350
351           ·   PYTHON_INFO (20)
352
353           ·   PYTHON_DEBUG (10)
354
355           ·   PYTHON_NOTSET (0)
356

OPTIONS

358       General options are described in lttng(1).
359
360   Domain
361       One of:
362
363       -j, --jul
364           Create or enable event rules in the java.util.logging (JUL) domain.
365
366       -k, --kernel
367           Create or enable event rules in the Linux kernel domain.
368
369       -l, --log4j
370           Create or enable event rules in the Apache log4j domain.
371
372       -p, --python
373           Create or enable event rules in the Python domain.
374
375       -u, --userspace
376           Create or enable event rules in the user space domain.
377
378   Target
379       -c CHANNEL, --channel=CHANNEL
380           Create or enable event rules in the channel named CHANNEL instead
381           of the default channel name channel0.
382
383       -s SESSION, --session=SESSION
384           Create or enable event rules in the tracing session named SESSION
385           instead of the current tracing session.
386
387   Event source type
388       One of:
389
390       --function=SOURCE
391           Linux kernel kretprobe. Only available with the --kernel domain
392           option.  SOURCE is one of:
393
394           ·   Function address (0x prefix supported)
395
396           ·   Function symbol
397
398           ·   Function symbol and offset (SYMBOL+OFFSET format)
399
400       --probe=SOURCE
401           Linux kernel kprobe. Only available with the --kernel domain
402           option.  SOURCE is one of:
403
404           ·   Address (0x prefix supported)
405
406           ·   Symbol
407
408           ·   Symbol and offset (SYMBOL+OFFSET format)
409
410       --syscall
411           Linux kernel system call. Only available with the --kernel domain
412           option.
413
414       --tracepoint
415           Linux kernel or application tracepoint (default).
416
417   Log level
418       One of:
419
420       --loglevel=LOGLEVEL
421           Add log level condition to the event rule: the event source’s
422           defined log level must be at least as severe as LOGLEVEL. See the
423           Log levels section above for the available log levels. Only
424           available with application domains.
425
426       --loglevel-only=LOGLEVEL
427           Add log level condition to the event rule: the event source’s
428           defined log level must match LOGLEVEL. See the Log levels section
429           above for the available log levels. Only available with application
430           domains.
431
432   Filtering and exclusion
433       -x EVENT[,EVENT]..., --exclude=EVENT[,EVENT]...
434           Exclude events named EVENT from the event rule. This option can be
435           used when the command’s EVENT argument contains at least one
436           wildcard star (*) to exclude specific names.  EVENT can also
437           contain wildcard stars. To use a literal , character, use \,. Only
438           available with the --userspace domain.
439
440       -f EXPR, --filter=EXPR
441           Add filter expression condition to the event rule. Expression EXPR
442           must evaluate to true when executed against the dynamic values of
443           event fields. See the Filter expression syntax section above for
444           more information.
445
446   Shortcuts
447       -a, --all
448           Equivalent to an EVENT argument named * (wildcard) when also using
449           the --tracepoint (default) or --syscall option.
450
451   Program information
452       -h, --help
453           Show command help.
454
455           This option, like lttng-help(1), attempts to launch /usr/bin/man to
456           view the command’s man page. The path to the man pager can be
457           overridden by the LTTNG_MAN_BIN_PATH environment variable.
458
459       --list-options
460           List available command options.
461

ENVIRONMENT VARIABLES

463       LTTNG_ABORT_ON_ERROR
464           Set to 1 to abort the process after the first error is encountered.
465
466       LTTNG_HOME
467           Overrides the $HOME environment variable. Useful when the user
468           running the commands has a non-writable home directory.
469
470       LTTNG_MAN_BIN_PATH
471           Absolute path to the man pager to use for viewing help information
472           about LTTng commands (using lttng-help(1) or lttng COMMAND --help).
473
474       LTTNG_SESSION_CONFIG_XSD_PATH
475           Path in which the session.xsd session configuration XML schema may
476           be found.
477
478       LTTNG_SESSIOND_PATH
479           Full session daemon binary path.
480
481           The --sessiond-path option has precedence over this environment
482           variable.
483
484       Note that the lttng-create(1) command can spawn an LTTng session daemon
485       automatically if none is running. See lttng-sessiond(8) for the
486       environment variables influencing the execution of the session daemon.
487

FILES

489       $LTTNG_HOME/.lttngrc
490           User LTTng runtime configuration.
491
492           This is where the per-user current tracing session is stored
493           between executions of lttng(1). The current tracing session can be
494           set with lttng-set-session(1). See lttng-create(1) for more
495           information about tracing sessions.
496
497       $LTTNG_HOME/lttng-traces
498           Default output directory of LTTng traces. This can be overridden
499           with the --output option of the lttng-create(1) command.
500
501       $LTTNG_HOME/.lttng
502           User LTTng runtime and configuration directory.
503
504       $LTTNG_HOME/.lttng/sessions
505           Default location of saved user tracing sessions (see lttng-save(1)
506           and lttng-load(1)).
507
508       /usr/local/etc/lttng/sessions
509           System-wide location of saved tracing sessions (see lttng-save(1)
510           and lttng-load(1)).
511
512           Note
513           $LTTNG_HOME defaults to $HOME when not explicitly set.
514

EXIT STATUS

516       0
517           Success
518
519       1
520           Command error
521
522       2
523           Undefined command
524
525       3
526           Fatal error
527
528       4
529           Command warning (something went wrong during the command)
530

BUGS

532       If you encounter any issue or usability problem, please report it on
533       the LTTng bug tracker <https://bugs.lttng.org/projects/lttng-tools>.
534

RESOURCES

536       ·   LTTng project website <http://lttng.org>
537
538       ·   LTTng documentation <http://lttng.org/docs>
539
540       ·   Git repositories <http://git.lttng.org>
541
542       ·   GitHub organization <http://github.com/lttng>
543
544       ·   Continuous integration <http://ci.lttng.org/>
545
546       ·   Mailing list <http://lists.lttng.org> for support and development:
547           lttng-dev@lists.lttng.org
548
549       ·   IRC channel <irc://irc.oftc.net/lttng>: #lttng on irc.oftc.net
550

COPYRIGHTS

552       This program is part of the LTTng-tools project.
553
554       LTTng-tools is distributed under the GNU General Public License version
555       2 <http://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html>. See the
556       LICENSE <https://github.com/lttng/lttng-tools/blob/master/LICENSE> file
557       for details.
558

THANKS

560       Special thanks to Michel Dagenais and the DORSAL laboratory
561       <http://www.dorsal.polymtl.ca/> at École Polytechnique de Montréal for
562       the LTTng journey.
563
564       Also thanks to the Ericsson teams working on tracing which helped us
565       greatly with detailed bug reports and unusual test cases.
566

AUTHORS

568       LTTng-tools was originally written by Mathieu Desnoyers, Julien
569       Desfossez, and David Goulet. More people have since contributed to it.
570
571       LTTng-tools is currently maintained by Jérémie Galarneau
572       <mailto:jeremie.galarneau@efficios.com>.
573