doc/man: lttng(1) command pages: always include `common-footer.txt`
[lttng-tools.git] / doc / man / lttng-enable-event.1.txt
1 lttng-enable-event(1)
2 =====================
3 :revdate: 3 May 2021
4
5
6 NAME
7 ----
8 lttng-enable-event - Create or enable LTTng recording event rules
9
10
11 SYNOPSIS
12 --------
13 Create or enable one or more recording event rules to match Linux kernel
14 tracepoint or system call events:
15
16 [verse]
17 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-event* option:--kernel [option:--tracepoint | option:--syscall]
18 (option:--all | 'NAME'[,'NAME']...) [option:--filter='EXPR']
19 [option:--session='SESSION'] [option:--channel='CHANNEL']
20
21 Create or enable a recording event rule to match Linux kernel events
22 created from a dynamic instrumentation point:
23
24 [verse]
25 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-event* option:--kernel
26 (option:--probe='LOC' | option:--function='LOC' | option:--userspace-probe='LOC') 'RECORDNAME'
27 [option:--filter='EXPR'] [option:--session='SESSION'] [option:--channel='CHANNEL']
28
29 Create or enable one or more recording event rules to match
30 user space tracepoint events:
31
32 [verse]
33 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-event* option:--userspace [option:--tracepoint]
34 (option:--all | 'NAME'[,'NAME']...) [option:--exclude='XNAME'[,'XNAME']...]
35 [option:--loglevel='LOGLEVEL' | option:--loglevel-only='LOGLEVEL'] [option:--filter='EXPR']
36 [option:--session='SESSION'] [option:--channel='CHANNEL']
37
38 Create or enable one or more recording event rules to match
39 Java/Python logging events:
40
41 [verse]
42 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-event* (option:--jul | option:--log4j | option:--python)
43 [option:--tracepoint] (option:--all | 'NAME'[,'NAME']...)
44 [option:--loglevel='LOGLEVEL' | option:--loglevel-only='LOGLEVEL'] [option:--filter='EXPR']
45 [option:--session='SESSION'] [option:--channel='CHANNEL']
46
47 DESCRIPTION
48 -----------
49 The `lttng enable-event` command does one of:
50
51 * Create one or more recording event rules.
52
53 * Enable one or more disabled recording event rules.
54 +
55 See the <<enable,Enable a disabled recording event rule>> section
56 below.
57
58 See man:lttng-concepts(7) to learn more about instrumentation points,
59 events, recording event rules, and event records.
60
61 The recording event rule(s) to create or enable belong to:
62
63 With the option:--session='SESSION' option::
64 The tracing session named 'SESSION'.
65
66 Without the option:--session option::
67 The current tracing session (see man:lttng-concepts(7) to learn more
68 about the current tracing session).
69
70 With the option:--channel='CHANNEL' option::
71 The channel named 'CHANNEL'.
72
73 Without the option:--channel option::
74 The channel named `channel0`.
75 +
76 If such a channel doesn't exist, the `enable-event` automatically
77 creates it.
78
79 List the recording event rules of a specific tracing session
80 and/or channel with the man:lttng-list(1) and man:lttng-status(1)
81 commands.
82
83 Disable an enabled recording event rule with the
84 man:lttng-disable-event(1) command.
85
86
87 Overview of recording event rule conditions
88 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
89 For LTTng to emit and record an event{nbsp}__E__,{nbsp}__E__ must
90 satisfy *all* the conditions of a recording event rule{nbsp}__ER__, that
91 is:
92
93 Explicit conditions::
94 You set the following conditions when you create or
95 enable{nbsp}__ER__ with the `enable-event` command:
96 +
97 --
98 * The instrumentation point type from which LTTng creates{nbsp}__E__
99 has a specific type.
100 +
101 See the <<inst-point-type-cond,Instrumentation point type condition>>
102 section below.
103
104 * A pattern matches the name of{nbsp}__E__ while another pattern
105 doesn't.
106 +
107 See the <<event-name-cond,Event name condition>> section below.
108
109 * The log level of the instrumentation point from which LTTng
110 creates{nbsp}__E__ is at least as severe as some value, or is exactly
111 some value.
112 +
113 See the <<inst-point-log-level-cond,Instrumentation point log level condition>>
114 section below.
115
116 * The fields of the payload of{nbsp}__E__ and the current context fields
117 satisfy a filter expression.
118 +
119 See the <<filter-cond,Event payload and context filter condition>>
120 section below.
121 --
122
123 Implicit conditions::
124 +
125 --
126 * _ER_ itself is enabled.
127 +
128 A recording event rule is enabled on creation.
129 +
130 Enable a disabled recording event rule with the `enable-event` command.
131
132 * The channel to which{nbsp}__ER__ is attached is enabled.
133 +
134 A channel is enabled on creation.
135 +
136 Enable a disabled channel with the man:lttng-enable-channel(1) command.
137
138 * The tracing session of{nbsp}__ER__ is active (started).
139 +
140 A tracing session is inactive (stopped) on creation.
141 +
142 Start an inactive tracing session with the man:lttng-start(1) command.
143
144 * The process for which LTTng creates{nbsp}__E__ is allowed to record
145 events.
146 +
147 All processes are allowed to record events on tracing session
148 creation.
149 +
150 Use the man:lttng-track(1) and man:lttng-untrack(1) commands to select
151 which processes are allowed to record events based on specific process
152 attributes.
153 --
154
155 The dedicated command-line options of most conditions are optional: if
156 you don't specify the option, the associated condition is always
157 satisfied.
158
159
160 [[inst-point-type-cond]]
161 Instrumentation point type condition
162 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
163 An event{nbsp}__E__ satisfies the instrumentation point type condition
164 of a recording event rule if the instrumentation point from which LTTng
165 creates{nbsp}__E__ is:
166
167 For the Linux kernel tracing domain (option:--kernel option)::
168 With the option:--tracepoint option or without any other instrumentation point type option:::
169 An LTTng kernel tracepoint, that is, a statically defined point
170 in the source code of the kernel image or of a kernel module
171 with LTTng kernel tracer macros.
172 +
173 As of LTTng{nbsp}{lttng_version}, this is the default instrumentation
174 point type of the Linux kernel tracing domain, but this may change in
175 the future.
176 +
177 List the available Linux kernel tracepoints with `lttng list --kernel`.
178 See man:lttng-list(1) to learn more.
179
180 With the option:--syscall option:::
181 The entry and exit of a Linux kernel system call.
182 +
183 List the available Linux kernel system call instrumentation points with
184 `lttng list --kernel --syscall`. See man:lttng-list(1) to learn more.
185
186 With the option:--probe option:::
187 A Linux kprobe, that is, a single probe dynamically placed in
188 the compiled kernel code.
189 +
190 The argument of the option:--probe option is the location of the
191 kprobe to insert, either a symbol or a
192 memory address, while 'RECORDNAME' is the name of the record
193 of{nbsp}__E__ (see the <<er-name,Event record name>> section below).
194 +
195 The payload of a Linux kprobe event is empty.
196
197 With the option:--userspace-probe option:::
198 A Linux user space probe, that is, a single probe dynamically
199 placed at the entry of a compiled user space application/library
200 function through the kernel.
201 +
202 The argument of the option:--userspace-probe option is the location
203 of the user space probe to insert, one of:
204 +
205 --
206 * A path and symbol (ELF method).
207 * A path, provider name, and probe name (SystemTap User-level Statically
208 Defined Tracing (USDT) method; a DTrace-style marker).
209 +
210 As of LTTng{nbsp}{lttng_version}, LTTng only supports USDT probes which
211 are :not: reference-counted.
212 --
213 +
214 'RECORDNAME' is the name of the record of{nbsp}__E__ (see the
215 <<er-name,Event record name>> section below).
216 +
217 The payload of a Linux user space probe event is empty.
218
219 With the option:--function option:::
220 A Linux kretprobe, that is, two probes dynamically placed at the
221 entry and exit of a function in the compiled kernel code.
222 +
223 The argument of the option:--function option is the location of the
224 Linux kretprobe to insert, either a symbol or
225 a memory address, while 'RECORDNAME' is the name of the record
226 of{nbsp}__E__ (see the <<er-name,Event record name>> section below).
227 +
228 The payload of a Linux kretprobe event is empty.
229
230 For the user space tracing domain (option:--userspace option)::
231 With or without the option:--tracepoint option:::
232 An LTTng user space tracepoint, that is, a statically defined
233 point in the source code of a C/$$C++$$ application/library with
234 LTTng user space tracer macros.
235 +
236 As of LTTng{nbsp}{lttng_version}, this is the default and sole
237 instrumentation point type of the user space tracing domain, but this
238 may change in the future.
239 +
240 List the available user space tracepoints with `lttng list --userspace`.
241 See man:lttng-list(1) to learn more.
242
243 For the `java.util.logging` (option:--jul option), Apache log4j (option:--log4j option), and Python (option:--python option) tracing domains::
244 With or without the option:--tracepoint option:::
245 A logging statement.
246 +
247 As of LTTng{nbsp}{lttng_version}, this is the default and sole
248 instrumentation point type of the `java.util.logging`, Apache log4j, and
249 Python tracing domains, but this may change in the future.
250 +
251 List the available Java and Python loggers with `lttng list --jul`,
252 `lttng list --log4j`, and `lttng list --python`. See man:lttng-list(1)
253 to learn more.
254
255
256 [[event-name-cond]]
257 Event name condition
258 ~~~~~~~~~~~~~~~~~~~~
259 An event{nbsp}__E__ satisfies the event name condition of a recording
260 event rule{nbsp}__ER__ if the two following statements are true:
261
262 * You specify the option:--all option or, depending on the
263 instrumentation type condition (see the
264 <<inst-point-type-cond,Instrumentation point type condition>> section
265 above) of{nbsp}__ER__, 'NAME' matches:
266 +
267 --
268 LTTng tracepoint::
269 The full name of the tracepoint from which LTTng creates{nbsp}__E__.
270 +
271 Note that the full name of a user space tracepoint is
272 __PROVIDER__++:++__NAME__, where __PROVIDER__ is the tracepoint provider
273 name and __NAME__ is the tracepoint name.
274
275 Logging statement::
276 The name of the Java or Python logger from which LTTng
277 creates{nbsp}__E__.
278
279 Linux system call::
280 The name of the system call, without any `sys_` prefix, from which
281 LTTng creates{nbsp}__E__.
282 --
283
284 * You don't specify the option:--exclude=__XNAME__[++,++__XNAME__]...
285 option or, depending on the instrumentation type condition
286 of{nbsp}__ER__, none of the 'XNAME' arguments matches the full name of
287 the user space tracepoint from which LTTng creates{nbsp}__E__.
288 +
289 The option:--exclude option is only available with the option:--userspace
290 option.
291
292 This condition is only meaningful for the LTTng tracepoint, logging
293 statement, and Linux system call instrumentation point types: it's
294 always satisfied for the other types.
295
296 In all cases, 'NAME' and 'XNAME' are globbing patterns: the `*`
297 character means ``match anything''. To match a literal `*` character,
298 use :escwc:. To match a literal `,` character, use
299 :esccomma:.
300
301 IMPORTANT: Make sure to **single-quote** 'NAME' and 'XNAME' when they
302 contain the `*` character and when you run the `enable-event` command
303 from a shell.
304
305 With the LTTng tracepoint, logging statement, and Linux system call
306 instrumentation point types, the `enable-event` command creates or
307 enables one independent recording event rule per 'NAME' argument
308 (non-option, comma-separated). With the option:--all option, the
309 `enable-event` command creates or enables a single recording event rule.
310
311
312 [[inst-point-log-level-cond]]
313 Instrumentation point log level condition
314 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
315 An event{nbsp}__E__ satisfies the instrumentation point log level
316 condition of a recording event rule if either:
317
318 * The option:--loglevel and option:--loglevel-only options are
319 missing.
320
321 * The log level of the LTTng user space tracepoint or logging statement
322 which creates{nbsp}__E__ is:
323 With the option:--loglevel='LOGLEVEL' option::
324 At least as severe as 'LOGLEVEL'.
325
326 With the option:--loglevel-only='LOGLEVEL' option::
327 Exactly 'LOGLEVEL'.
328
329 This condition is only meaningful for the LTTng user space tracepoint
330 and logging statement instrumentation point types: it's always satisfied
331 for other types.
332
333 The available values of 'LOGLEVEL' are, depending on the tracing domain,
334 from the most to the least severe:
335
336 User space (option:--userspace option)::
337 Shortcuts such as `system` are allowed.
338 +
339 * `TRACE_EMERG` (0)
340 * `TRACE_ALERT` (1)
341 * `TRACE_CRIT` (2)
342 * `TRACE_ERR` (3)
343 * `TRACE_WARNING` (4)
344 * `TRACE_NOTICE` (5)
345 * `TRACE_INFO` (6)
346 * `TRACE_DEBUG_SYSTEM` (7)
347 * `TRACE_DEBUG_PROGRAM` (8)
348 * `TRACE_DEBUG_PROCESS` (9)
349 * `TRACE_DEBUG_MODULE` (10)
350 * `TRACE_DEBUG_UNIT` (11)
351 * `TRACE_DEBUG_FUNCTION` (12)
352 * `TRACE_DEBUG_LINE` (13)
353 * `TRACE_DEBUG` (14)
354
355 `java.util.logging` (option:--jul option)::
356 Shortcuts such as `severe` are allowed.
357 +
358 * `JUL_OFF` (`INT32_MAX`)
359 * `JUL_SEVERE` (1000)
360 * `JUL_WARNING` (900)
361 * `JUL_INFO` (800)
362 * `JUL_CONFIG` (700)
363 * `JUL_FINE` (500)
364 * `JUL_FINER` (400)
365 * `JUL_FINEST` (300)
366 * `JUL_ALL` (`INT32_MIN`)
367
368 Apache log4j (option:--log4j option)::
369 Shortcuts such as `severe` are allowed.
370 +
371 * `LOG4J_OFF` (`INT32_MAX`)
372 * `LOG4J_FATAL` (50000)
373 * `LOG4J_ERROR` (40000)
374 * `LOG4J_WARN` (30000)
375 * `LOG4J_INFO` (20000)
376 * `LOG4J_DEBUG` (10000)
377 * `LOG4J_TRACE` (5000)
378 * `LOG4J_ALL` (`INT32_MIN`)
379
380 Python (option:--python option)::
381 Shortcuts such as `critical` are allowed.
382 +
383 * `PYTHON_CRITICAL` (50)
384 * `PYTHON_ERROR` (40)
385 * `PYTHON_WARNING` (30)
386 * `PYTHON_INFO` (20)
387 * `PYTHON_DEBUG` (10)
388 * `PYTHON_NOTSET` (0)
389
390
391 [[filter-cond]]
392 Event payload and context filter condition
393 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
394 An event{nbsp}__E__ satisfies the event payload and context filter
395 condition of a recording event rule if the option:--filter='EXPR'
396 option is missing or if 'EXPR' is _true_.
397
398 'EXPR' can contain references to the payload fields of{nbsp}__E__ and
399 to the current context fields.
400
401 IMPORTANT: Make sure to **single-quote** 'EXPR' when you run the
402 `enable-event` command from a shell, as filter expressions typically
403 include characters having a special meaning for most shells.
404
405 The expected syntax of 'EXPR' is similar to the syntax of a
406 C{nbsp}language conditional expression (an expression which an `if`
407 statement can evaluate), but there are a few differences:
408
409 * A _NAME_ expression identifies an event payload field named
410 _NAME_ (a C{nbsp}identifier).
411 +
412 Use the C{nbsp}language dot and square bracket notations to access
413 nested structure and array/sequence fields. You can only use a constant,
414 positive integer number within square brackets. If the index is out of
415 bounds, 'EXPR' is _false_.
416 +
417 The value of an enumeration field is an integer.
418 +
419 When a field expression doesn't exist, 'EXPR' is _false_.
420 +
421 Examples: `my_field`, `target_cpu`, `seq[7]`, `msg.user[1].data[2][17]`.
422
423 * A ++$ctx.++__TYPE__ expression identifies the statically-known context
424 field having the type _TYPE_ (a C{nbsp}identifier).
425 +
426 List the available statically-known context field names with the
427 man:lttng-add-context(1) command.
428 +
429 When a field expression doesn't exist, 'EXPR' is _false_.
430 +
431 Examples: `$ctx.prio`, `$ctx.preemptible`,
432 `$ctx.perf:cpu:stalled-cycles-frontend`.
433
434 * A ++$app.++__PROVIDER__++:++__TYPE__ expression identifies the
435 application-specific context field having the type _TYPE_ (a
436 C{nbsp}identifier) from the provider _PROVIDER_ (a C{nbsp}identifier).
437 +
438 When a field expression doesn't exist, 'EXPR' is _false_.
439 +
440 Example: `$app.server:cur_user`.
441
442 * Compare strings, either string fields or string literals
443 (double-quoted), with the `==` and `!=` operators.
444 +
445 When comparing to a string literal, the `*` character means ``match
446 anything''. To match a literal `*` character, use :escwc:.
447 +
448 Examples: `my_field == "user34"`, `my_field == my_other_field`,
449 `my_field == "192.168.*"`.
450
451 * The precedence table of the operators which are supported in 'EXPR'
452 is as follows. In this table, the highest precedence is{nbsp}1:
453 +
454 [options="header"]
455 |===
456 |Precedence |Operator |Description |Associativity
457 |1 |`-` |Unary minus |Right-to-left
458 |1 |`+` |Unary plus |Right-to-left
459 |1 |`!` |Logical NOT |Right-to-left
460 |1 |`~` |Bitwise NOT |Right-to-left
461 |2 |`<<` |Bitwise left shift |Left-to-right
462 |2 |`>>` |Bitwise right shift |Left-to-right
463 |3 |`&` |Bitwise AND |Left-to-right
464 |4 |`^` |Bitwise XOR |Left-to-right
465 |5 |`\|` |Bitwise OR |Left-to-right
466 |6 |`<` |Less than |Left-to-right
467 |6 |`<=` |Less than or equal to |Left-to-right
468 |6 |`>` |Greater than |Left-to-right
469 |6 |`>=` |Greater than or equal to |Left-to-right
470 |7 |`==` |Equal to |Left-to-right
471 |7 |`!=` |Not equal to |Left-to-right
472 |8 |`&&` |Logical AND |Left-to-right
473 |9 |`\|\|` |Logical OR |Left-to-right
474 |===
475 +
476 Parentheses are supported to bypass the default order.
477 +
478 IMPORTANT: Unlike the C{nbsp}language, the bitwise AND and OR operators
479 (`&` and `|`) in 'EXPR' take precedence over relational operators (`<`,
480 `<=`, `>`, `>=`, `==`, and `!=`). This means the expression `2 & 2 == 2`
481 is _true_ while the equivalent C{nbsp}expression is _false_.
482 +
483 The arithmetic operators are :not: supported.
484 +
485 LTTng first casts all integer constants and fields to signed 64-bit
486 integers. The representation of negative integers is two's complement.
487 This means that, for example, the signed 8-bit integer field 0xff (-1)
488 becomes 0xffffffffffffffff (still -1) once casted.
489 +
490 Before a bitwise operator is applied, LTTng casts all its operands to
491 unsigned 64-bit integers, and then casts the result back to a signed
492 64-bit integer. For the bitwise NOT operator, it's the equivalent of
493 this C{nbsp}expression:
494 +
495 [source,c]
496 ----
497 (int64_t) ~((uint64_t) val)
498 ----
499 +
500 For the binary bitwise operators, it's the equivalent of those
501 C{nbsp}expressions:
502 +
503 [source,c]
504 ----
505 (int64_t) ((uint64_t) lhs >> (uint64_t) rhs)
506 (int64_t) ((uint64_t) lhs << (uint64_t) rhs)
507 (int64_t) ((uint64_t) lhs & (uint64_t) rhs)
508 (int64_t) ((uint64_t) lhs ^ (uint64_t) rhs)
509 (int64_t) ((uint64_t) lhs | (uint64_t) rhs)
510 ----
511 +
512 If the right-hand side of a bitwise shift operator (`<<` and `>>`) is
513 not in the [0,{nbsp}63] range, then 'EXPR' is _false_.
514
515 [NOTE]
516 ====
517 Use the man:lttng-track(1) and man:lttng-untrack(1) commands to allow or
518 disallow processes to record LTTng events based on their attributes
519 instead of using equivalent statically-known context fields in 'EXPR'
520 like `$ctx.pid`.
521
522 The former method is much more efficient.
523 ====
524
525 'EXPR' examples:
526
527 ----------------------------
528 msg_id == 23 && size >= 2048
529 ----------------------------
530
531 -------------------------------------------------
532 $ctx.procname == "lttng*" && (!flag || poel < 34)
533 -------------------------------------------------
534
535 ---------------------------------------------------------
536 $app.my_provider:my_context == 17.34e9 || some_enum >= 14
537 ---------------------------------------------------------
538
539 ---------------------------------------
540 $ctx.cpu_id == 2 && filename != "*.log"
541 ---------------------------------------
542
543 ------------------------------------------------
544 eax_reg & 0xff7 == 0x240 && x[4] >> 12 <= 0x1234
545 ------------------------------------------------
546
547
548 [[er-name]]
549 Event record name
550 ~~~~~~~~~~~~~~~~~
551 When LTTng records an event{nbsp}__E__, the resulting event record has a
552 name which depends on the instrumentation point type condition (see the
553 <<inst-point-type-cond,Instrumentation point type condition>> section
554 above) of the recording event rule which matched{nbsp}__E__:
555
556 LTTng tracepoint (option:--kernel/option:--userspace and option:--tracepoint options)::
557 Full name of the tracepoint from which LTTng creates{nbsp}__E__.
558 +
559 Note that the full name of a user space tracepoint is
560 __PROVIDER__++:++__NAME__, where __PROVIDER__ is the tracepoint provider
561 name and __NAME__ is the tracepoint name.
562
563 `java.util.logging` logging statement (option:--jul and option:--tracepoint options)::
564 `lttng_jul:event`
565 +
566 Such an event record has a string field `logger_name` which contains the
567 name of the `java.util.logging` logger from which LTTng
568 creates{nbsp}__E__.
569
570 Apache log4j logging statement (option:--log4j and option:--tracepoint options)::
571 `lttng_log4j:event`
572 +
573 Such an event record has a string field `logger_name` which contains the
574 name of the Apache log4j logger from which LTTng creates{nbsp}__E__.
575
576 Python logging statement (option:--python and option:--tracepoint options)::
577 `lttng_python:event`
578 +
579 Such an event record has a string field `logger_name` which contains the
580 name of the Python logger from which LTTng creates{nbsp}__E__.
581
582 Linux system call (option:--kernel and option:--syscall options)::
583 Entry:::
584 ++syscall_entry_++__NAME__, where _NAME_ is the name of the
585 system call from which LTTng creates{nbsp}__E__, without any
586 `sys_` prefix.
587
588 Exit:::
589 ++syscall_exit_++__NAME__, where _NAME_ is the name of the
590 system call from which LTTng creates{nbsp}__E__, without any
591 `sys_` prefix.
592
593 Linux kprobe (option:--kernel and option:--probe options)::
594 Linux user space probe (option:--kernel and option:--userspace-probe options)::
595 'RECORDNAME' (first non-option argument).
596
597 Linux kretprobe (option:--kernel and option:--function options)::
598 Entry:::
599 __RECORDNAME__++_entry++
600
601 Exit:::
602 __RECORDNAME__++_exit++
603
604
605 [[enable]]
606 Enable a disabled recording event rule
607 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
608 The `enable-event` command can enable a disabled recording event rule,
609 as listed in the output of the man:lttng-list(1) command.
610
611 You may enable a disabled recording event rule regardless of the
612 activity (started or stopped) of its tracing session (see
613 man:lttng-start(1) and man:lttng-stop(1)).
614
615 To enable a disabled recording event rule, run the `enable-event`
616 command with the exact same options and arguments that you used to
617 create it. In particular, with the option:--filter='EXPR' option, 'EXPR'
618 must be the exact same string as the one you used on creation.
619
620
621 include::common-lttng-cmd-options-head.txt[]
622
623
624 Tracing domain
625 ~~~~~~~~~~~~~~
626 One of:
627
628 option:-j, option:--jul::
629 Create or enable recording event rules in the `java.util.logging`
630 (JUL) tracing domain.
631
632 option:-k, option:--kernel::
633 Create or enable recording event rules in the Linux kernel tracing
634 domain.
635
636 option:-l, option:--log4j::
637 Create or enable recording event rules in the Apache log4j tracing
638 domain.
639
640 option:-p, option:--python::
641 Create or enable recording event rules in the Python tracing domain.
642
643 option:-u, option:--userspace::
644 Create or enable recording event rules in the user space tracing
645 domain.
646
647
648 Recording target
649 ~~~~~~~~~~~~~~~~
650 option:-c 'CHANNEL', option:--channel='CHANNEL'::
651 Create or enable recording event rules attached to the channel named
652 'CHANNEL' instead of `channel0`.
653
654 option:-s 'SESSION', option:--session='SESSION'::
655 Create or enable recording event rules in the tracing session named
656 'SESSION' instead of the current tracing session.
657
658
659 Instrumentation point type condition
660 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
661 See the <<inst-point-type-cond,Instrumentation point type condition>>
662 section above.
663
664 At most one of:
665
666 option:--function='LOC'::
667 Only match Linux kretprobe events.
668 +
669 Only available with the option:--kernel option.
670 +
671 'LOC' is one of:
672 +
673 --
674 * A function address (`0x` hexadecimal prefix supported).
675 * A function symbol name.
676 * A function symbol name and an offset
677 (__SYMBOL__++pass:[+]++__OFFSET__ format).
678 --
679 +
680 You must specify the event record name with 'RECORDNAME'. See the
681 <<er-name,Event record name>> section above to learn more.
682
683 option:--probe='LOC'::
684 Only match Linux kprobe events.
685 +
686 Only available with the option:--kernel option.
687 +
688 'LOC' is one of:
689 +
690 --
691 * An address (`0x` hexadecimal prefix supported).
692 * A symbol name.
693 * A symbol name and an offset (__SYMBOL__++pass:[+]++__OFFSET__ format).
694 --
695 +
696 You must specify the event record name with 'RECORDNAME'. See the
697 <<er-name,Event record name>> section above to learn more.
698
699 option:--userspace-probe='LOC'::
700 Only match Linux user space probe events.
701 +
702 Only available with the option:--kernel option.
703 +
704 'LOC' is one of:
705 +
706 --
707 \[++elf:++]__PATH__++:++__SYMBOL__::
708 Probe an available symbol within a user space application or
709 library.
710 +
711 --
712 'PATH'::
713 Application or library path.
714 +
715 One of:
716 +
717 * An absolute path.
718 * A relative path.
719 * The name of an application as found in the directories listed in the
720 `PATH` environment variable.
721
722 'SYMBOL'::
723 Symbol name of the function of which to instrument the entry.
724 +
725 'SYMBOL' can be any defined code symbol in the output of the man:nm(1)
726 command, including with its nloption:--dynamic option, which lists
727 dynamic symbols.
728 --
729 +
730 As of LTTng{nbsp}{lttng_version}, not specifying `elf:` is equivalent to
731 specifying it, but this default may change in the future.
732 +
733 Examples:
734 +
735 * `--userspace-probe=/usr/lib/libc.so.6:malloc`
736 * `--userspace-probe=./myapp:createUser`
737 * `--userspace-probe=elf:httpd:ap_run_open_htaccess`
738
739 ++sdt:++__PATH__++:++__PROVIDER__++:++__NAME__::
740 Use a SystemTap User-level Statically Defined Tracing (USDT) probe
741 within a user space application or library.
742 +
743 --
744 'PATH'::
745 Application or library path.
746 +
747 This can be:
748 +
749 * An absolute path.
750 * A relative path.
751 * The name of an application as found in the directories listed in the
752 `PATH` environment variable.
753
754 'PROVIDER'::
755 'NAME'::
756 USDT provider and probe names.
757 +
758 For example, with the following USDT probe:
759 +
760 [source,c]
761 ----
762 DTRACE_PROBE2("server", "accept_request",
763 request_id, ip_addr);
764 ----
765 +
766 The provider/probe name pair is `server:accept_request`.
767 --
768 +
769 Example: `--userspace-probe=sdt:./build/server:server:accept_request`
770 --
771 +
772 You must specify the event record name with 'RECORDNAME'. See the
773 <<er-name,Event record name>> section above to learn more.
774
775 option:--syscall::
776 Only match Linux system call events.
777 +
778 Only available with the option:--kernel option.
779
780 option:--tracepoint::
781 Only match:
782 +
783 With the option:--kernel or option:--userspace option:::
784 LTTng tracepoint events.
785 With the option:--jul, option:--log4j, or option:--python option:::
786 Logging events.
787
788 With the option:--kernel, not specifying any of the instrumentation
789 point type options is equivalent to specifying the option:--tracepoint
790 option, but this default may change in the future.
791
792 With the option:--userspace, option:--jul, option:--log4j, and
793 option:--python options, not specifying the option:--tracepoint option
794 is equivalent to specifying it, but this default may change in the
795 future.
796
797
798 Event name condition
799 ~~~~~~~~~~~~~~~~~~~~
800 See the <<event-name-cond,Event name condition>> section above.
801
802 option:-a, option:--all::
803 Equivalent to a single 'NAME' argument (LTTng tracepoint or logger
804 name) set to `*` (match anything).
805 +
806 You may :not: use this option with a 'NAME' argument.
807
808 option:-x 'XNAME'[,'XNAME']..., option:--exclude='XNAME'[,'XNAME']...::
809 Only match events of which none of the 'XNAME' arguments
810 matches the full name of the LTTng user space tracepoint.
811 +
812 Only available with the option:--userspace option.
813 +
814 'XNAME' is a globbing pattern: the `*` character means ``match
815 anything''. To match a literal `*` character, use :escwc:. To match
816 a literal `,` character, use :esccomma:.
817
818
819 Instrumentation point log level condition
820 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
821 See the <<inst-point-log-level-cond,Instrumentation point log level
822 condition>> section above.
823
824 At most one of:
825
826 option:--loglevel='LOGLEVEL'::
827 Only match events of which the log level of the LTTng tracepoint or
828 logging statement is at least as severe as 'LOGLEVEL'.
829
830 option:--loglevel-only='LOGLEVEL'::
831 Only match events of which the log level of the LTTng tracepoint or
832 logging statement is exactly 'LOGLEVEL'.
833
834 The instrumentation point log level options above are :not: available
835 with the option:--kernel option.
836
837
838 Event payload and context filter condition
839 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
840 See the <<filter-cond,Event payload and context filter condition>>
841 section above.
842
843 option:-f 'EXPR', option:--filter='EXPR'::
844 Only match events of which 'EXPR', which can contain references to
845 event payload and current context fields, is _true_.
846
847
848 include::common-lttng-cmd-help-options.txt[]
849
850
851 include::common-lttng-cmd-after-options.txt[]
852
853
854 include::common-footer.txt[]
855
856
857 SEE ALSO
858 --------
859 man:lttng(1),
860 man:lttng-disable-event(1),
861 man:lttng-enable-channel(1),
862 man:lttng-list(1),
863 man:lttng-start(1),
864 man:lttng-track(1),
865 man:lttng-concepts(7)
This page took 0.050275 seconds and 6 git commands to generate.