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