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