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