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