doc/man: create lttng-enable-event(1) and update/fix content
[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]
15*lttng* ['GENERAL OPTIONS'] *enable-event* option:--kernel
16 [option:--probe='SOURCE' | option:--function='SOURCE' | option:--syscall]
17 [option:--filter='EXPR'] [option:--session='SESSION']
18 [option:--channel='CHANNEL'] 'EVENT'[,'EVENT']...
19
20Create or enable an "all" Linux kernel event rule:
21
22[verse]
23*lttng* ['GENERAL OPTIONS'] *enable-event* option:--kernel option:--all [option:--syscall]
24 [option:--filter='EXPR'] [option:--session='SESSION'] [option:--channel='CHANNEL']
25
26Create or enable application event rules:
27
28[verse]
29*lttng* ['GENERAL OPTIONS'] *enable-event*
30 (option:--userspace | option:--jul | option:--log4j | option:--python)
31 [option:--filter='EXPR'] [option:--exclude='EVENT'[,'EVENT']...]
32 [option:--loglevel='LOGLEVEL' | option:--loglevel-only='LOGLEVEL']
33 [option:--session='SESSION'] [option:--channel='CHANNEL'] (option:--all | 'EVENT'[,'EVENT']...)
34
35
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).
45Event sources can be listed with the linklttng:lttng-list(1) command.
46
47The linklttng:lttng-disable-event(1) command can be used to disable
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
59(use linklttng:lttng-start(1) to make a tracing session active).
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
109----------------------------------------------------------------
110lttng enable-event --userspace hello:world
111lttng enable-event --userspace hello:world --loglevel=TRACE_INFO
112----------------------------------------------------------------
113
114Here, two event rules are created. The first one has a single condition:
115the tracepoint name must match `hello:world`. The second one has two
116conditions:
117
118* The tracepoint name must match `hello:world`, _and_
119* The tracepoint's defined log level must be at least as severe as
120 the `TRACE_INFO` level.
121
122In this case, the second event rule is pointless because the first one
123is more general: it does not care about the tracepoint's log level.
124If an event source matching both event rules is reached by the
125application's execution, only one event is emitted.
126
127The available conditions for the Linux kernel domain are:
128
129* Tracepoint/system call name ('EVENT' argument with
130 option:--tracepoint or option:--syscall options) or
131 dynamic probe/function name/address
132 (option:--probe or option:--function option's argument) which must
133 match event source's equivalent.
134+
135Wildcard using the `*` character are supported _at the end_ of
136tracepoint and system call names.
137
138* Filter expression (option:--filter option) executed against the
139 dynamic values of event fields at execution time that must evaluate
140 to true. See the <<filter-syntax,Filter expression syntax>> section
141 below for more information.
142
143The available conditions for the application domains are:
144
145* Tracepoint name ('EVENT' with option:--tracepoint option) which must
146 match event source's equivalent.
147+
148Wildcard using the `*` character are supported _at the end_ of
149tracepoint names. When creating an event rule with a tracepoint name
150containing a wildcard, specific tracepoint names can be excluded from
151the match using the option:--exclude option.
152
153* Filter expression (option:--filter option) executed against the
154 dynamic values of event fields at execution time that must evaluate
155 to true. See the <<filter-syntax,Filter expression syntax>> section
156 below for more information.
157* Event's log level that must be at least as severe as a given
158 log level (option:--loglevel option) or match exactly a given log
159 level (option:--loglevel-only option).
160
161When using `lttng enable-event` with a set of conditions that does not
162currently exist for the chosen tracing session, domain, and channel,
163a new event rule is created. Otherwise, the existing event rule is
164enabled if it is currently disabled
165(see linklttng:lttng-disable-event(1)).
166
167The option:--all option can be used alongside the option:--tracepoint
168or option:--syscall options. When this option is used, no 'EVENT'
169argument must be specified. This option defines a single event rule
170matching _all_ the possible events of a given tracing domain for the
171chosen channel and tracing session. It is the equivalent of an 'EVENT'
172argument named `*` (wildcard).
173
174
175[[filter-syntax]]
176Filter expression syntax
177~~~~~~~~~~~~~~~~~~~~~~~~
178Filter expressions can be specified with the option:--filter option
179when creating a new event rule. If the filter expression evaluates
180to true when executed against the dynamic values of an event's fields
181when tracing, the filtering condition passes.
182
183The filter expression syntax is very similar to C language conditional
184expressions (expressions that can be evaluated by an `if` statement).
185
186The following logical operators are supported:
187
188[width="40%",options="header"]
189|=====================================
190| Name | Syntax
191| Logical negation (NOT) | `!a`
192| Logical conjunction (AND) | `a && b`
193| Logical disjunction (OR) | `a \|\| b`
194|=====================================
195
196The following comparison operators/relational operators are supported:
197
198[width="40%",options="header"]
199|====================================
200| Name | Syntax
201| Equal to | `a == b`
202| Not equal to | `a != b`
203| Greater than | `a > b`
204| Less than | `a < b`
205| Greater than or equal to | `a >= b`
206| Less than or equal to | `a <= b`
207|====================================
208
209The arithmetic and bitwise operators are :not: supported.
210
211The precedence table of the operators above is the same as the one of
212the C language. Parentheses are supported to bypass this.
213
214The dynamic value of an event field is read by using its name as
215a C identifier.
216
217The dynamic value of a statically-known context field is read by
218prefixing its name with `$ctx.`. Statically-known context fields are
219context fields added to channels without the `$app.` prefix using the
220linklttng:lttng-add-context(1) command.
221
222The dynamic value of an application-specific context field is read by
223prefixing its name with `$app.` (follows the format used to add such a
224context field with the linklttng:lttng-add-context(1) command).
225
226When a comparison includes a non existent event field, the whole filter
227expression evaluates to false (the event is discarded).
228
229C integer and floating point number constants are supported, as well as
230literal strings between double quotes (`"`). Literal strings can contain
231a wildcard character (`*`) at the end to match more than one string.
232This wildcard can be escaped using `\\*`.
233
234LTTng-UST enumeration fields can be compared to integer values (fields
235or constants).
236
237NOTE: Although it is possible to filter the process ID of an event when
238the `pid` context has been added to its channel using, for example,
239`$ctx.pid == 2832`, it is recommended to use the PID tracker instead,
240which is much more efficient (see linklttng:lttng-track(1)).
241
242Examples:
243
244----------------------------
245msg_id == 23 && size >= 2048
246----------------------------
247
248-------------------------------------------------
249$ctx.procname == "lttng*" && (!flag || poel < 34)
250-------------------------------------------------
251
252---------------------------------------------------------
253$app.my_provider:my_context == 17.34e9 || some_enum >= 14
254---------------------------------------------------------
255
256
257[[log-levels]]
258Log levels
259~~~~~~~~~~
260Tracepoints and log statements in applications have an attached log
261level. Application event rules can contain a _log level_ condition.
262
263With the option:--loglevel option, the event source's log level must
264be at least as severe as the option's argument. With the
265option:--loglevel-only option, the event source's log level must match
266the option's argument.
267
268The available log levels are:
269
270User space domain (option:--userspace option)::
271 Shortcuts such as `system` are allowed.
272+
273* `TRACE_EMERG` (0)
274* `TRACE_ALERT` (1)
275* `TRACE_CRIT` (2)
276* `TRACE_ERR` (3)
277* `TRACE_WARNING` (4)
278* `TRACE_NOTICE` (5)
279* `TRACE_INFO` (6)
280* `TRACE_DEBUG_SYSTEM` (7)
281* `TRACE_DEBUG_PROGRAM` (8)
282* `TRACE_DEBUG_PROCESS` (9)
283* `TRACE_DEBUG_MODULE` (10)
284* `TRACE_DEBUG_UNIT` (11)
285* `TRACE_DEBUG_FUNCTION` (12)
286* `TRACE_DEBUG_LINE` (13)
287* `TRACE_DEBUG` (14)
288
289`java.util.logging` domain (option:--jul option)::
290 Shortcuts such as `severe` are allowed.
291+
292* `JUL_OFF` (`INT32_MAX`)
293* `JUL_SEVERE` (1000)
294* `JUL_WARNING` (900)
295* `JUL_INFO` (800)
296* `JUL_CONFIG` (700)
297* `JUL_FINE` (500)
298* `JUL_FINER` (400)
299* `JUL_FINEST` (300)
300* `JUL_ALL` (`INT32_MIN`)
301
302Apache log4j domain (option:--log4j option)::
303 Shortcuts such as `severe` are allowed.
304+
305* `LOG4J_OFF` (`INT32_MAX`)
306* `LOG4J_FATAL` (50000)
307* `LOG4J_ERROR` (40000)
308* `LOG4J_WARN` (30000)
309* `LOG4J_INFO` (20000)
310* `LOG4J_DEBUG` (10000)
311* `LOG4J_TRACE` (5000)
312* `LOG4J_ALL` (`INT32_MIN`)
313
314Python domain (option:--python option)::
315 Shortcuts such as `critical` are allowed.
316+
317* `PYTHON_CRITICAL` (50)
318* `PYTHON_ERROR` (40)
319* `PYTHON_WARNING` (30)
320* `PYTHON_INFO` (20)
321* `PYTHON_DEBUG` (10)
322* `PYTHON_NOTSET` (0)
323
324
325include::common-cmd-options-head.txt[]
326
327
328Domain
329~~~~~~
330One of:
331
332option:-j, option:--jul::
333 Create or enable event rules in the `java.util.logging`
334 (JUL) domain.
335
336option:-k, option:--kernel::
337 Create or enable event rules in the Linux kernel domain.
338
339option:-l, option:--log4j::
340 Create or enable event rules in the Apache log4j domain.
341
342option:-p, option:--python::
343 Create or enable event rules in the Python domain.
344
345option:-u, option:--userspace::
346 Create or enable event rules in the user space domain.
347
348
349Target
350~~~~~~
351option:-c, option:--channel='CHANNEL'::
352 Create or enable event rules in the channel named 'CHANNEL' instead
353 of the default channel name `channel0`.
354
355option:-s, option:--session='SESSION'::
356 Create or enable event rules in the tracing session named 'SESSION'
357 instead of the current tracing session.
358
359
360Event source type
361~~~~~~~~~~~~~~~~~
362One of:
363
364option:--function='SOURCE'::
365 Linux kernel kretprobe. Only available with the option:--kernel
366 domain option. 'SOURCE' is one of:
367+
368* Function address (`0x` prefix supported)
369* Function symbol
370* Function symbol and offset (`SYMBOL+OFFSET` format)
371
372option:--probe='SOURCE'::
373 Linux kernel kprobe. Only available with the option:--kernel
374 domain option. 'SOURCE' is one of:
375+
376* Address (`0x` prefix supported)
377* Symbol
378* Symbol and offset (`SYMBOL+OFFSET` format)
379
380option:--syscall::
381 Linux kernel system call. Only available with the option:--kernel
382 domain option.
383
384option:--tracepoint::
385 Linux kernel or application tracepoint (default).
386
387
388Log level
389~~~~~~~~~
390One of:
391
392option:--loglevel='LOGLEVEL'::
393 Add log level condition to the event rule: the event source's
394 defined log level must be at least as severe as 'LOGLEVEL'.
395 See the <<log-levels,Log levels>> section above for the available
396 log levels. Only available with application domains.
397
398option:--loglevel-only='LOGLEVEL'::
399 Add log level condition to the event rule: the event source's
400 defined log level must match 'LOGLEVEL'. See the
401 <<log-levels,Log levels>> section above for the available log
402 levels. Only available with application domains.
403
404
405Filtering and exclusion
406~~~~~~~~~~~~~~~~~~~~~~~
407option:-x, option:--exclude='EVENT'[,'EVENT']...::
408 Exclude events named 'EVENT' from the event rule. This option
409 can be used when the command's 'EVENT' argument contains a wildcard
410 (`*`) to exclude specific names. Only available with application
411 domains.
412
413option:-f, option:--filter='EXPR'::
414 Add filter expression condition to the event rule. Expression 'EXPR'
415 must evaluate to true when executed against the dynamic values of
416 event fields. See the <<filter-syntax,Filter expression syntax>>
417 section above for more information.
418
419
420Shortcuts
421~~~~~~~~~
422option:-a, option:--all::
423 Equivalent to an 'EVENT' argument named `*` (wildcard) when also
424 using the option:--tracepoint (default) or option:--syscall option.
425
426
427include::common-cmd-help-options.txt[]
428
429
430include::common-cmd-footer.txt[]
431
432
433SEE ALSO
434--------
435linklttng:lttng-disable-event(1),
436linklttng:lttng(1)
This page took 0.060467 seconds and 4 git commands to generate.