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