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 | + | |
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 | ||
0dd658dc PP |
398 | This condition is only meaningful for the LTTng tracepoint and Linux |
399 | system call instrumentation point types: it's always satisfied for other | |
400 | types. | |
401 | ||
484b2a0c PP |
402 | 'EXPR' can contain references to the payload fields of{nbsp}__E__ and |
403 | to the current context fields. | |
404 | ||
405 | IMPORTANT: Make sure to **single-quote** 'EXPR' when you run the | |
406 | `enable-event` command from a shell, as filter expressions typically | |
407 | include characters having a special meaning for most shells. | |
408 | ||
409 | The expected syntax of 'EXPR' is similar to the syntax of a | |
410 | C{nbsp}language conditional expression (an expression which an `if` | |
411 | statement can evaluate), but there are a few differences: | |
412 | ||
413 | * A _NAME_ expression identifies an event payload field named | |
414 | _NAME_ (a C{nbsp}identifier). | |
415 | + | |
416 | Use the C{nbsp}language dot and square bracket notations to access | |
417 | nested structure and array/sequence fields. You can only use a constant, | |
418 | positive integer number within square brackets. If the index is out of | |
419 | bounds, 'EXPR' is _false_. | |
420 | + | |
421 | The value of an enumeration field is an integer. | |
422 | + | |
423 | When a field expression doesn't exist, 'EXPR' is _false_. | |
11613178 PP |
424 | + |
425 | Examples: `my_field`, `target_cpu`, `seq[7]`, `msg.user[1].data[2][17]`. | |
e9b06e2b | 426 | |
484b2a0c PP |
427 | * A ++$ctx.++__TYPE__ expression identifies the statically-known context |
428 | field having the type _TYPE_ (a C{nbsp}identifier). | |
429 | + | |
430 | List the available statically-known context field names with the | |
431 | man:lttng-add-context(1) command. | |
11613178 | 432 | + |
484b2a0c | 433 | When a field expression doesn't exist, 'EXPR' is _false_. |
11613178 PP |
434 | + |
435 | Examples: `$ctx.prio`, `$ctx.preemptible`, | |
436 | `$ctx.perf:cpu:stalled-cycles-frontend`. | |
e9b06e2b | 437 | |
484b2a0c PP |
438 | * A ++$app.++__PROVIDER__++:++__TYPE__ expression identifies the |
439 | application-specific context field having the type _TYPE_ (a | |
440 | C{nbsp}identifier) from the provider _PROVIDER_ (a C{nbsp}identifier). | |
11613178 | 441 | + |
484b2a0c | 442 | When a field expression doesn't exist, 'EXPR' is _false_. |
11613178 PP |
443 | + |
444 | Example: `$app.server:cur_user`. | |
445 | ||
484b2a0c PP |
446 | * Compare strings, either string fields or string literals |
447 | (double-quoted), with the `==` and `!=` operators. | |
448 | + | |
449 | When comparing to a string literal, the `*` character means ``match | |
450 | anything''. To match a literal `*` character, use :escwc:. | |
451 | + | |
452 | Examples: `my_field == "user34"`, `my_field == my_other_field`, | |
453 | `my_field == "192.168.*"`. | |
11613178 | 454 | |
484b2a0c PP |
455 | * The precedence table of the operators which are supported in 'EXPR' |
456 | is as follows. In this table, the highest precedence is{nbsp}1: | |
457 | + | |
11613178 PP |
458 | [options="header"] |
459 | |=== | |
460 | |Precedence |Operator |Description |Associativity | |
461 | |1 |`-` |Unary minus |Right-to-left | |
462 | |1 |`+` |Unary plus |Right-to-left | |
463 | |1 |`!` |Logical NOT |Right-to-left | |
464 | |1 |`~` |Bitwise NOT |Right-to-left | |
465 | |2 |`<<` |Bitwise left shift |Left-to-right | |
466 | |2 |`>>` |Bitwise right shift |Left-to-right | |
467 | |3 |`&` |Bitwise AND |Left-to-right | |
468 | |4 |`^` |Bitwise XOR |Left-to-right | |
469 | |5 |`\|` |Bitwise OR |Left-to-right | |
470 | |6 |`<` |Less than |Left-to-right | |
471 | |6 |`<=` |Less than or equal to |Left-to-right | |
472 | |6 |`>` |Greater than |Left-to-right | |
473 | |6 |`>=` |Greater than or equal to |Left-to-right | |
474 | |7 |`==` |Equal to |Left-to-right | |
475 | |7 |`!=` |Not equal to |Left-to-right | |
476 | |8 |`&&` |Logical AND |Left-to-right | |
477 | |9 |`\|\|` |Logical OR |Left-to-right | |
478 | |=== | |
484b2a0c PP |
479 | + |
480 | Parentheses are supported to bypass the default order. | |
481 | + | |
482 | IMPORTANT: Unlike the C{nbsp}language, the bitwise AND and OR operators | |
483 | (`&` and `|`) in 'EXPR' take precedence over relational operators (`<`, | |
484 | `<=`, `>`, `>=`, `==`, and `!=`). This means the expression `2 & 2 == 2` | |
485 | is _true_ while the equivalent C{nbsp}expression is _false_. | |
486 | + | |
11613178 | 487 | The arithmetic operators are :not: supported. |
484b2a0c PP |
488 | + |
489 | LTTng first casts all integer constants and fields to signed 64-bit | |
11613178 PP |
490 | integers. The representation of negative integers is two's complement. |
491 | This means that, for example, the signed 8-bit integer field 0xff (-1) | |
492 | becomes 0xffffffffffffffff (still -1) once casted. | |
484b2a0c PP |
493 | + |
494 | Before a bitwise operator is applied, LTTng casts all its operands to | |
495 | unsigned 64-bit integers, and then casts the result back to a signed | |
496 | 64-bit integer. For the bitwise NOT operator, it's the equivalent of | |
497 | this C{nbsp}expression: | |
498 | + | |
11613178 PP |
499 | [source,c] |
500 | ---- | |
501 | (int64_t) ~((uint64_t) val) | |
502 | ---- | |
484b2a0c PP |
503 | + |
504 | For the binary bitwise operators, it's the equivalent of those | |
505 | C{nbsp}expressions: | |
506 | + | |
11613178 PP |
507 | [source,c] |
508 | ---- | |
509 | (int64_t) ((uint64_t) lhs >> (uint64_t) rhs) | |
510 | (int64_t) ((uint64_t) lhs << (uint64_t) rhs) | |
511 | (int64_t) ((uint64_t) lhs & (uint64_t) rhs) | |
512 | (int64_t) ((uint64_t) lhs ^ (uint64_t) rhs) | |
513 | (int64_t) ((uint64_t) lhs | (uint64_t) rhs) | |
514 | ---- | |
484b2a0c | 515 | + |
11613178 | 516 | If the right-hand side of a bitwise shift operator (`<<` and `>>`) is |
484b2a0c | 517 | not in the [0,{nbsp}63] range, then 'EXPR' is _false_. |
e9b06e2b | 518 | |
484b2a0c PP |
519 | [NOTE] |
520 | ==== | |
521 | Use the man:lttng-track(1) and man:lttng-untrack(1) commands to allow or | |
522 | disallow processes to record LTTng events based on their attributes | |
523 | instead of using equivalent statically-known context fields in 'EXPR' | |
524 | like `$ctx.pid`. | |
e9b06e2b | 525 | |
484b2a0c PP |
526 | The former method is much more efficient. |
527 | ==== | |
528 | ||
529 | 'EXPR' examples: | |
e9b06e2b PP |
530 | |
531 | ---------------------------- | |
532 | msg_id == 23 && size >= 2048 | |
533 | ---------------------------- | |
534 | ||
535 | ------------------------------------------------- | |
536 | $ctx.procname == "lttng*" && (!flag || poel < 34) | |
537 | ------------------------------------------------- | |
538 | ||
539 | --------------------------------------------------------- | |
540 | $app.my_provider:my_context == 17.34e9 || some_enum >= 14 | |
541 | --------------------------------------------------------- | |
542 | ||
c52365cc PP |
543 | --------------------------------------- |
544 | $ctx.cpu_id == 2 && filename != "*.log" | |
545 | --------------------------------------- | |
f69e7997 | 546 | |
11613178 PP |
547 | ------------------------------------------------ |
548 | eax_reg & 0xff7 == 0x240 && x[4] >> 12 <= 0x1234 | |
549 | ------------------------------------------------ | |
550 | ||
e9b06e2b | 551 | |
484b2a0c PP |
552 | [[er-name]] |
553 | Event record name | |
554 | ~~~~~~~~~~~~~~~~~ | |
555 | When LTTng records an event{nbsp}__E__, the resulting event record has a | |
556 | name which depends on the instrumentation point type condition (see the | |
188419c4 PP |
557 | <<inst-point-type-cond,Instrumentation point type condition>> section |
558 | above) of the recording event rule which matched{nbsp}__E__: | |
e9b06e2b | 559 | |
484b2a0c PP |
560 | LTTng tracepoint (option:--kernel/option:--userspace and option:--tracepoint options):: |
561 | Full name of the tracepoint from which LTTng creates{nbsp}__E__. | |
e9b06e2b | 562 | + |
484b2a0c PP |
563 | Note that the full name of a user space tracepoint is |
564 | __PROVIDER__++:++__NAME__, where __PROVIDER__ is the tracepoint provider | |
565 | name and __NAME__ is the tracepoint name. | |
e9b06e2b | 566 | |
484b2a0c PP |
567 | `java.util.logging` logging statement (option:--jul and option:--tracepoint options):: |
568 | `lttng_jul:event` | |
e9b06e2b | 569 | + |
484b2a0c PP |
570 | Such an event record has a string field `logger_name` which contains the |
571 | name of the `java.util.logging` logger from which LTTng | |
572 | creates{nbsp}__E__. | |
e9b06e2b | 573 | |
484b2a0c PP |
574 | Apache log4j logging statement (option:--log4j and option:--tracepoint options):: |
575 | `lttng_log4j:event` | |
e9b06e2b | 576 | + |
484b2a0c PP |
577 | Such an event record has a string field `logger_name` which contains the |
578 | name of the Apache log4j logger from which LTTng creates{nbsp}__E__. | |
e9b06e2b | 579 | |
484b2a0c PP |
580 | Python logging statement (option:--python and option:--tracepoint options):: |
581 | `lttng_python:event` | |
e9b06e2b | 582 | + |
484b2a0c PP |
583 | Such an event record has a string field `logger_name` which contains the |
584 | name of the Python logger from which LTTng creates{nbsp}__E__. | |
585 | ||
586 | Linux system call (option:--kernel and option:--syscall options):: | |
587 | Entry::: | |
588 | ++syscall_entry_++__NAME__, where _NAME_ is the name of the | |
589 | system call from which LTTng creates{nbsp}__E__, without any | |
590 | `sys_` prefix. | |
591 | ||
592 | Exit::: | |
593 | ++syscall_exit_++__NAME__, where _NAME_ is the name of the | |
594 | system call from which LTTng creates{nbsp}__E__, without any | |
595 | `sys_` prefix. | |
596 | ||
597 | Linux kprobe (option:--kernel and option:--probe options):: | |
598 | Linux user space probe (option:--kernel and option:--userspace-probe options):: | |
599 | 'RECORDNAME' (first non-option argument). | |
e9b06e2b | 600 | |
484b2a0c PP |
601 | Linux kretprobe (option:--kernel and option:--function options):: |
602 | Entry::: | |
603 | __RECORDNAME__++_entry++ | |
e9b06e2b | 604 | |
484b2a0c PP |
605 | Exit::: |
606 | __RECORDNAME__++_exit++ | |
b981f450 | 607 | |
b981f450 | 608 | |
484b2a0c PP |
609 | [[enable]] |
610 | Enable a disabled recording event rule | |
611 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
188419c4 PP |
612 | The `enable-event` command can enable a disabled recording event rule, |
613 | as listed in the output of the man:lttng-list(1) command. | |
484b2a0c PP |
614 | |
615 | You may enable a disabled recording event rule regardless of the | |
616 | activity (started or stopped) of its tracing session (see | |
617 | man:lttng-start(1) and man:lttng-stop(1)). | |
618 | ||
619 | To enable a disabled recording event rule, run the `enable-event` | |
620 | command with the exact same options and arguments that you used to | |
621 | create it. In particular, with the option:--filter='EXPR' option, 'EXPR' | |
622 | must be the exact same string as the one you used on creation. | |
b981f450 | 623 | |
b981f450 | 624 | |
55e06994 | 625 | include::common-lttng-cmd-options-head.txt[] |
fa72991a PP |
626 | |
627 | ||
484b2a0c PP |
628 | Tracing domain |
629 | ~~~~~~~~~~~~~~ | |
fa72991a PP |
630 | One of: |
631 | ||
632 | option:-j, option:--jul:: | |
484b2a0c PP |
633 | Create or enable recording event rules in the `java.util.logging` |
634 | (JUL) tracing domain. | |
fa72991a PP |
635 | |
636 | option:-k, option:--kernel:: | |
484b2a0c PP |
637 | Create or enable recording event rules in the Linux kernel tracing |
638 | domain. | |
fa72991a PP |
639 | |
640 | option:-l, option:--log4j:: | |
484b2a0c PP |
641 | Create or enable recording event rules in the Apache log4j tracing |
642 | domain. | |
fa72991a PP |
643 | |
644 | option:-p, option:--python:: | |
484b2a0c | 645 | Create or enable recording event rules in the Python tracing domain. |
fa72991a PP |
646 | |
647 | option:-u, option:--userspace:: | |
484b2a0c PP |
648 | Create or enable recording event rules in the user space tracing |
649 | domain. | |
fa72991a PP |
650 | |
651 | ||
484b2a0c PP |
652 | Recording target |
653 | ~~~~~~~~~~~~~~~~ | |
fa72991a | 654 | option:-c 'CHANNEL', option:--channel='CHANNEL':: |
484b2a0c PP |
655 | Create or enable recording event rules attached to the channel named |
656 | 'CHANNEL' instead of `channel0`. | |
fa72991a PP |
657 | |
658 | option:-s 'SESSION', option:--session='SESSION':: | |
484b2a0c PP |
659 | Create or enable recording event rules in the tracing session named |
660 | 'SESSION' instead of the current tracing session. | |
fa72991a PP |
661 | |
662 | ||
484b2a0c PP |
663 | Instrumentation point type condition |
664 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
665 | See the <<inst-point-type-cond,Instrumentation point type condition>> | |
666 | section above. | |
fa72991a | 667 | |
484b2a0c PP |
668 | At most one of: |
669 | ||
670 | option:--function='LOC':: | |
671 | Only match Linux kretprobe events. | |
672 | + | |
673 | Only available with the option:--kernel option. | |
674 | + | |
675 | 'LOC' is one of: | |
fa72991a | 676 | + |
484b2a0c PP |
677 | -- |
678 | * A function address (`0x` hexadecimal prefix supported). | |
679 | * A function symbol name. | |
680 | * A function symbol name and an offset | |
681 | (__SYMBOL__++pass:[+]++__OFFSET__ format). | |
682 | -- | |
683 | + | |
684 | You must specify the event record name with 'RECORDNAME'. See the | |
685 | <<er-name,Event record name>> section above to learn more. | |
fa72991a | 686 | |
484b2a0c PP |
687 | option:--probe='LOC':: |
688 | Only match Linux kprobe events. | |
689 | + | |
690 | Only available with the option:--kernel option. | |
691 | + | |
692 | 'LOC' is one of: | |
693 | + | |
694 | -- | |
695 | * An address (`0x` hexadecimal prefix supported). | |
696 | * A symbol name. | |
697 | * A symbol name and an offset (__SYMBOL__++pass:[+]++__OFFSET__ format). | |
698 | -- | |
fa72991a | 699 | + |
484b2a0c PP |
700 | You must specify the event record name with 'RECORDNAME'. See the |
701 | <<er-name,Event record name>> section above to learn more. | |
fa72991a | 702 | |
484b2a0c PP |
703 | option:--userspace-probe='LOC':: |
704 | Only match Linux user space probe events. | |
fa72991a | 705 | + |
484b2a0c PP |
706 | Only available with the option:--kernel option. |
707 | + | |
708 | 'LOC' is one of: | |
fa72991a PP |
709 | + |
710 | -- | |
711 | \[++elf:++]__PATH__++:++__SYMBOL__:: | |
484b2a0c PP |
712 | Probe an available symbol within a user space application or |
713 | library. | |
b981f450 PP |
714 | + |
715 | -- | |
716 | 'PATH':: | |
717 | Application or library path. | |
718 | + | |
484b2a0c | 719 | One of: |
b981f450 PP |
720 | + |
721 | * An absolute path. | |
722 | * A relative path. | |
484b2a0c | 723 | * The name of an application as found in the directories listed in the |
b981f450 PP |
724 | `PATH` environment variable. |
725 | ||
726 | 'SYMBOL':: | |
727 | Symbol name of the function of which to instrument the entry. | |
728 | + | |
484b2a0c PP |
729 | 'SYMBOL' can be any defined code symbol in the output of the man:nm(1) |
730 | command, including with its nloption:--dynamic option, which lists | |
731 | dynamic symbols. | |
b981f450 PP |
732 | -- |
733 | + | |
484b2a0c PP |
734 | As of LTTng{nbsp}{lttng_version}, not specifying `elf:` is equivalent to |
735 | specifying it, but this default may change in the future. | |
b981f450 PP |
736 | + |
737 | Examples: | |
738 | + | |
739 | * `--userspace-probe=/usr/lib/libc.so.6:malloc` | |
740 | * `--userspace-probe=./myapp:createUser` | |
484b2a0c | 741 | * `--userspace-probe=elf:httpd:ap_run_open_htaccess` |
b981f450 | 742 | |
fa72991a | 743 | ++sdt:++__PATH__++:++__PROVIDER__++:++__NAME__:: |
484b2a0c PP |
744 | Use a SystemTap User-level Statically Defined Tracing (USDT) probe |
745 | within a user space application or library. | |
b981f450 PP |
746 | + |
747 | -- | |
748 | 'PATH':: | |
749 | Application or library path. | |
750 | + | |
751 | This can be: | |
752 | + | |
753 | * An absolute path. | |
754 | * A relative path. | |
484b2a0c | 755 | * The name of an application as found in the directories listed in the |
b981f450 PP |
756 | `PATH` environment variable. |
757 | ||
484b2a0c PP |
758 | 'PROVIDER':: |
759 | 'NAME':: | |
0e63136b | 760 | USDT provider and probe names. |
b981f450 | 761 | + |
0e63136b | 762 | For example, with the following USDT probe: |
b981f450 PP |
763 | + |
764 | [source,c] | |
765 | ---- | |
766 | DTRACE_PROBE2("server", "accept_request", | |
767 | request_id, ip_addr); | |
768 | ---- | |
769 | + | |
770 | The provider/probe name pair is `server:accept_request`. | |
771 | -- | |
772 | + | |
484b2a0c | 773 | Example: `--userspace-probe=sdt:./build/server:server:accept_request` |
fa72991a | 774 | -- |
484b2a0c PP |
775 | + |
776 | You must specify the event record name with 'RECORDNAME'. See the | |
777 | <<er-name,Event record name>> section above to learn more. | |
b981f450 | 778 | |
e9b06e2b | 779 | option:--syscall:: |
484b2a0c PP |
780 | Only match Linux system call events. |
781 | + | |
782 | Only available with the option:--kernel option. | |
e9b06e2b PP |
783 | |
784 | option:--tracepoint:: | |
484b2a0c PP |
785 | Only match: |
786 | + | |
787 | With the option:--kernel or option:--userspace option::: | |
788 | LTTng tracepoint events. | |
789 | With the option:--jul, option:--log4j, or option:--python option::: | |
790 | Logging events. | |
e9b06e2b | 791 | |
484b2a0c PP |
792 | With the option:--kernel, not specifying any of the instrumentation |
793 | point type options is equivalent to specifying the option:--tracepoint | |
794 | option, but this default may change in the future. | |
e9b06e2b | 795 | |
484b2a0c PP |
796 | With the option:--userspace, option:--jul, option:--log4j, and |
797 | option:--python options, not specifying the option:--tracepoint option | |
798 | is equivalent to specifying it, but this default may change in the | |
799 | future. | |
800 | ||
801 | ||
802 | Event name condition | |
803 | ~~~~~~~~~~~~~~~~~~~~ | |
804 | See the <<event-name-cond,Event name condition>> section above. | |
805 | ||
806 | option:-a, option:--all:: | |
807 | Equivalent to a single 'NAME' argument (LTTng tracepoint or logger | |
808 | name) set to `*` (match anything). | |
809 | + | |
810 | You may :not: use this option with a 'NAME' argument. | |
811 | ||
812 | option:-x 'XNAME'[,'XNAME']..., option:--exclude='XNAME'[,'XNAME']...:: | |
813 | Only match events of which none of the 'XNAME' arguments | |
814 | matches the full name of the LTTng user space tracepoint. | |
815 | + | |
816 | Only available with the option:--userspace option. | |
817 | + | |
818 | 'XNAME' is a globbing pattern: the `*` character means ``match | |
819 | anything''. To match a literal `*` character, use :escwc:. To match | |
820 | a literal `,` character, use :esccomma:. | |
821 | ||
822 | ||
823 | Instrumentation point log level condition | |
824 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
825 | See the <<inst-point-log-level-cond,Instrumentation point log level | |
826 | condition>> section above. | |
827 | ||
828 | At most one of: | |
e9b06e2b PP |
829 | |
830 | option:--loglevel='LOGLEVEL':: | |
484b2a0c PP |
831 | Only match events of which the log level of the LTTng tracepoint or |
832 | logging statement is at least as severe as 'LOGLEVEL'. | |
e9b06e2b PP |
833 | |
834 | option:--loglevel-only='LOGLEVEL':: | |
484b2a0c PP |
835 | Only match events of which the log level of the LTTng tracepoint or |
836 | logging statement is exactly 'LOGLEVEL'. | |
e9b06e2b | 837 | |
484b2a0c PP |
838 | The instrumentation point log level options above are :not: available |
839 | with the option:--kernel option. | |
e9b06e2b PP |
840 | |
841 | ||
484b2a0c PP |
842 | Event payload and context filter condition |
843 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
844 | See the <<filter-cond,Event payload and context filter condition>> | |
845 | section above. | |
846 | ||
847 | option:-f 'EXPR', option:--filter='EXPR':: | |
848 | Only match events of which 'EXPR', which can contain references to | |
849 | event payload and current context fields, is _true_. | |
0dd658dc PP |
850 | + |
851 | This option is only available with the option:--tracepoint or | |
852 | option:--syscall option. | |
e9b06e2b PP |
853 | |
854 | ||
55e06994 | 855 | include::common-lttng-cmd-help-options.txt[] |
e9b06e2b PP |
856 | |
857 | ||
55e06994 PP |
858 | include::common-lttng-cmd-after-options.txt[] |
859 | ||
860 | ||
861 | include::common-footer.txt[] | |
e9b06e2b PP |
862 | |
863 | ||
864 | SEE ALSO | |
865 | -------- | |
484b2a0c | 866 | man:lttng(1), |
7c1a4458 | 867 | man:lttng-disable-event(1), |
484b2a0c PP |
868 | man:lttng-enable-channel(1), |
869 | man:lttng-list(1), | |
870 | man:lttng-start(1), | |
21b35b3a PP |
871 | man:lttng-track(1), |
872 | man:lttng-concepts(7) |