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