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