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