Commit | Line | Data |
---|---|---|
e9b06e2b PP |
1 | lttng-enable-event(1) |
2 | ===================== | |
3 | ||
4 | ||
5 | NAME | |
6 | ---- | |
7 | lttng-enable-event - Create or enable LTTng event rules | |
8 | ||
9 | ||
10 | SYNOPSIS | |
11 | -------- | |
12 | Create or enable Linux kernel event rules: | |
13 | ||
14 | [verse] | |
ce19b9ed | 15 | *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-event* option:--kernel |
01b065c4 PP |
16 | [option:--probe='SOURCE' | option:--function='SOURCE' | option:--syscall | |
17 | option:--userspace-probe='SOURCE'] | |
e9b06e2b PP |
18 | [option:--filter='EXPR'] [option:--session='SESSION'] |
19 | [option:--channel='CHANNEL'] 'EVENT'[,'EVENT']... | |
20 | ||
21 | Create or enable an "all" Linux kernel event rule: | |
22 | ||
23 | [verse] | |
ce19b9ed | 24 | *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-event* option:--kernel option:--all [option:--syscall] |
e9b06e2b PP |
25 | [option:--filter='EXPR'] [option:--session='SESSION'] [option:--channel='CHANNEL'] |
26 | ||
01b065c4 | 27 | Create or enable application/library event rules: |
e9b06e2b PP |
28 | |
29 | [verse] | |
ce19b9ed | 30 | *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-event* |
e9b06e2b PP |
31 | (option:--userspace | option:--jul | option:--log4j | option:--python) |
32 | [option:--filter='EXPR'] [option:--exclude='EVENT'[,'EVENT']...] | |
33 | [option:--loglevel='LOGLEVEL' | option:--loglevel-only='LOGLEVEL'] | |
34 | [option:--session='SESSION'] [option:--channel='CHANNEL'] (option:--all | 'EVENT'[,'EVENT']...) | |
35 | ||
36 | ||
37 | DESCRIPTION | |
38 | ----------- | |
39 | The `lttng enable-event` command can create a new event rule, or enable | |
40 | one or more existing and disabled ones. | |
41 | ||
42 | An event rule created by `lttng enable-event` is a set of conditions | |
01b065c4 PP |
43 | that must be satisfied in order for an actual event to be emitted by an |
44 | LTTng tracer when the execution of an application or a library or the | |
45 | Linux kernel reaches an event source (tracepoint, system call, dynamic | |
46 | probe). Event sources can be listed with the man:lttng-list(1) command. | |
e9b06e2b | 47 | |
7c1a4458 | 48 | The man:lttng-disable-event(1) command can be used to disable |
e9b06e2b PP |
49 | existing event rules. |
50 | ||
51 | Event rules are always assigned to a channel when they are created. If | |
52 | the option:--channel option is omitted, a default channel named | |
53 | `channel0` is used (and created automatically if it does not exist for | |
54 | the specified domain in the selected tracing session). | |
55 | ||
56 | If the option:--session option is omitted, the chosen channel is picked | |
57 | from the current tracing session. | |
58 | ||
59 | Events can be enabled while tracing is active | |
7c1a4458 | 60 | (use man:lttng-start(1) to make a tracing session active). |
e9b06e2b PP |
61 | |
62 | ||
63 | Event source types | |
64 | ~~~~~~~~~~~~~~~~~~ | |
01b065c4 | 65 | Five types of event sources are available in the Linux kernel tracing |
e9b06e2b PP |
66 | domain (option:--kernel option): |
67 | ||
68 | Tracepoint (option:--tracepoint option; default):: | |
69 | A Linux kernel tracepoint, that is, a static instrumentation point | |
70 | placed in the kernel source code. Standard tracepoints are designed | |
71 | and placed in the source code by developers and record useful | |
72 | payload fields. | |
73 | ||
01b065c4 | 74 | Dynamic kernel probe (option:--probe option):: |
e9b06e2b PP |
75 | A Linux kernel kprobe, that is, an instrumentation point placed |
76 | dynamically in the compiled kernel code. Dynamic probe events do not | |
77 | record any payload field. | |
78 | ||
01b065c4 PP |
79 | Dynamic user space probe (option:--userspace-probe option):: |
80 | A Linux kernel uprobe, that is, an instrumentation point placed | |
81 | dynamically in the compiled user space application/library through | |
82 | the kernel. Dynamic user space probe events do not record any | |
83 | payload field. | |
84 | + | |
85 | See the <<userspace-probe,Dynamic user space probes>> section for more | |
86 | information. | |
87 | ||
e9b06e2b PP |
88 | Function probe (option:--function option):: |
89 | A Linux kernel kretprobe, that is, two instrumentation points placed | |
90 | dynamically where a function is entered and where it returns in the | |
91 | compiled kernel code. Function probe events do not record any | |
92 | payload field. | |
93 | ||
94 | System call (option:--syscall option):: | |
95 | A Linux kernel system call. Two instrumentation points are | |
96 | statically placed where a system call function is entered and where | |
97 | it returns in the compiled kernel code. System call event sources | |
98 | record useful payload fields. | |
99 | ||
100 | The application tracing domains (option:--userspace, option:--jul, | |
101 | option:--log4j, or option:--python options) only support tracepoints. | |
102 | In the cases of the JUL, Apache log4j, and Python domains, the event | |
103 | names correspond to _logger_ names. | |
104 | ||
105 | ||
106 | Understanding event rule conditions | |
107 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
108 | When creating an event rule with `lttng enable-event`, conditions are | |
109 | specified using options. The logical conjunction (logical AND) of all | |
110 | those conditions must be true when an event source is reached by an | |
111 | application or by the Linux kernel in order for an actual event | |
112 | to be emitted by an LTTng tracer. | |
113 | ||
114 | Any condition that is not explicitly specified on creation is considered | |
115 | a _don't care_. | |
116 | ||
117 | For example, consider the following commands: | |
118 | ||
d4f093aa | 119 | [role="term"] |
03c5529d PP |
120 | ---- |
121 | $ lttng enable-event --userspace hello:world | |
122 | $ lttng enable-event --userspace hello:world --loglevel=TRACE_INFO | |
123 | ---- | |
e9b06e2b PP |
124 | |
125 | Here, two event rules are created. The first one has a single condition: | |
126 | the tracepoint name must match `hello:world`. The second one has two | |
127 | conditions: | |
128 | ||
129 | * The tracepoint name must match `hello:world`, _and_ | |
130 | * The tracepoint's defined log level must be at least as severe as | |
131 | the `TRACE_INFO` level. | |
132 | ||
133 | In this case, the second event rule is pointless because the first one | |
134 | is more general: it does not care about the tracepoint's log level. | |
135 | If an event source matching both event rules is reached by the | |
136 | application's execution, only one event is emitted. | |
137 | ||
138 | The available conditions for the Linux kernel domain are: | |
139 | ||
01b065c4 PP |
140 | * Tracepoint/system call name ('EVENT' argument with option:--tracepoint |
141 | or option:--syscall options) or dynamic probe/function name/address | |
142 | (option:--probe, option:--userspace-probe, and option:--function | |
143 | option's argument) which must match event source's equivalent. | |
e9b06e2b | 144 | + |
f69e7997 PP |
145 | You can use `*` characters at any place in the tracepoint or system |
146 | call name as wildcards to match zero or more characters. To use a | |
147 | literal `*` character, use :escwc:. | |
e9b06e2b PP |
148 | |
149 | * Filter expression (option:--filter option) executed against the | |
150 | dynamic values of event fields at execution time that must evaluate | |
11613178 | 151 | to true. See the <<filter-expr,Filter expression>> section |
e9b06e2b PP |
152 | below for more information. |
153 | ||
154 | The available conditions for the application domains are: | |
155 | ||
156 | * Tracepoint name ('EVENT' with option:--tracepoint option) which must | |
157 | match event source's equivalent. | |
158 | + | |
f69e7997 PP |
159 | You can use `*` characters at any place in the tracepoint name as |
160 | wildcards to match zero or more characters. To use a literal `*` | |
161 | character, use :escwc:. When you create an event rule with a tracepoint | |
162 | name containing a wildcard, you can exclude specific tracepoint names | |
163 | from the match with the option:--exclude option. | |
e9b06e2b PP |
164 | |
165 | * Filter expression (option:--filter option) executed against the | |
166 | dynamic values of event fields at execution time that must evaluate | |
11613178 | 167 | to true. See the <<filter-expr,Filter expression>> section |
e9b06e2b PP |
168 | below for more information. |
169 | * Event's log level that must be at least as severe as a given | |
170 | log level (option:--loglevel option) or match exactly a given log | |
171 | level (option:--loglevel-only option). | |
172 | ||
173 | When using `lttng enable-event` with a set of conditions that does not | |
174 | currently exist for the chosen tracing session, domain, and channel, | |
175 | a new event rule is created. Otherwise, the existing event rule is | |
176 | enabled if it is currently disabled | |
7c1a4458 | 177 | (see man:lttng-disable-event(1)). |
e9b06e2b PP |
178 | |
179 | The option:--all option can be used alongside the option:--tracepoint | |
180 | or option:--syscall options. When this option is used, no 'EVENT' | |
181 | argument must be specified. This option defines a single event rule | |
182 | matching _all_ the possible events of a given tracing domain for the | |
183 | chosen channel and tracing session. It is the equivalent of an 'EVENT' | |
184 | argument named `*` (wildcard). | |
185 | ||
186 | ||
11613178 PP |
187 | [[filter-expr]] |
188 | Filter expression | |
189 | ~~~~~~~~~~~~~~~~~ | |
c52365cc | 190 | A filter expression can be specified with the option:--filter option |
11613178 PP |
191 | when creating a new event rule. If the filter expression evaluates |
192 | to true when executed against the dynamic values of an event's fields | |
193 | when tracing, the filtering condition passes. | |
e9b06e2b | 194 | |
60f7980c PP |
195 | NOTE: Make sure to **single-quote** the filter expression when running |
196 | the command from a shell, as filter expressions typically include | |
197 | characters having a special meaning for most shells. | |
198 | ||
11613178 PP |
199 | The filter expression syntax is similar to C language conditional |
200 | expressions (expressions that can be evaluated by an `if` statement), | |
201 | albeit with a few differences: | |
e9b06e2b | 202 | |
11613178 PP |
203 | * C integer and floating point number constants are supported, as well |
204 | as literal strings between double quotes (`"`). You can use `*` | |
205 | characters at any place in a literal string as wildcards to match zero | |
206 | or more characters. To use a literal `*` character, use :escwc:. | |
207 | + | |
208 | Examples: `32`, `-0x17`, `0755`, `12.34`, | |
209 | +"a :escbs:"literal string:escbs:""+, `"src/*/*.h"`. | |
e9b06e2b | 210 | |
11613178 PP |
211 | * The dynamic value of an event field is read by using its name as a C |
212 | identifier. | |
213 | + | |
214 | The dot and square bracket notations are available, like in the C | |
215 | language, to access nested structure and array/sequence fields. | |
216 | Only a constant, positive integer number can be used within square | |
217 | brackets. If the index is out of bounds, the whole filter expression | |
218 | evaluates to false (the event is discarded). | |
219 | + | |
220 | An enumeration field's value is an integer. | |
221 | + | |
222 | When the expression's field does not exist, the whole filter expression | |
223 | evaluates to false. | |
224 | + | |
225 | Examples: `my_field`, `target_cpu`, `seq[7]`, `msg.user[1].data[2][17]`. | |
e9b06e2b | 226 | |
11613178 PP |
227 | * The dynamic value of a statically-known context field is read by |
228 | prefixing its name with `$ctx.`. Statically-known context fields are | |
229 | context fields added to channels without the `$app.` prefix using the | |
230 | man:lttng-add-context(1) command. | |
231 | + | |
232 | When the expression's statically-known context field does not exist, | |
233 | the whole filter expression evaluates to false. | |
234 | + | |
235 | Examples: `$ctx.prio`, `$ctx.preemptible`, | |
236 | `$ctx.perf:cpu:stalled-cycles-frontend`. | |
e9b06e2b | 237 | |
11613178 PP |
238 | * The dynamic value of an application-specific context field is read by |
239 | prefixing its name with `$app.` (follows the format used to add such a | |
240 | context field with the man:lttng-add-context(1) command). | |
241 | + | |
242 | When the expression's application-specific context field does not exist, | |
243 | the whole filter expression evaluates to false. | |
244 | + | |
245 | Example: `$app.server:cur_user`. | |
246 | ||
247 | The following precedence table shows the operators which are supported | |
248 | in a filter expression. In this table, the highest precedence is 1. | |
249 | Parentheses are supported to bypass the default order. | |
250 | ||
251 | IMPORTANT: Unlike the C language, the `lttng enable-event` filter | |
252 | expression syntax's bitwise AND and OR operators (`&` and `|`) take | |
253 | precedence over relational operators (`<`, `<=`, `>`, `>=`, `==`, and | |
254 | `!=`). This means the filter expression `2 & 2 == 2` is true while the | |
255 | equivalent C expression is false. | |
256 | ||
257 | [options="header"] | |
258 | |=== | |
259 | |Precedence |Operator |Description |Associativity | |
260 | |1 |`-` |Unary minus |Right-to-left | |
261 | |1 |`+` |Unary plus |Right-to-left | |
262 | |1 |`!` |Logical NOT |Right-to-left | |
263 | |1 |`~` |Bitwise NOT |Right-to-left | |
264 | |2 |`<<` |Bitwise left shift |Left-to-right | |
265 | |2 |`>>` |Bitwise right shift |Left-to-right | |
266 | |3 |`&` |Bitwise AND |Left-to-right | |
267 | |4 |`^` |Bitwise XOR |Left-to-right | |
268 | |5 |`\|` |Bitwise OR |Left-to-right | |
269 | |6 |`<` |Less than |Left-to-right | |
270 | |6 |`<=` |Less than or equal to |Left-to-right | |
271 | |6 |`>` |Greater than |Left-to-right | |
272 | |6 |`>=` |Greater than or equal to |Left-to-right | |
273 | |7 |`==` |Equal to |Left-to-right | |
274 | |7 |`!=` |Not equal to |Left-to-right | |
275 | |8 |`&&` |Logical AND |Left-to-right | |
276 | |9 |`\|\|` |Logical OR |Left-to-right | |
277 | |=== | |
278 | ||
279 | The arithmetic operators are :not: supported. | |
280 | ||
281 | All integer constants and fields are first casted to signed 64-bit | |
282 | integers. The representation of negative integers is two's complement. | |
283 | This means that, for example, the signed 8-bit integer field 0xff (-1) | |
284 | becomes 0xffffffffffffffff (still -1) once casted. | |
285 | ||
286 | Before a bitwise operator is applied, all its operands are casted to | |
287 | unsigned 64-bit integers, and the result is casted back to a signed | |
288 | 64-bit integer. For the bitwise NOT operator, it is the equivalent of | |
289 | this C expression: | |
290 | ||
291 | [source,c] | |
292 | ---- | |
293 | (int64_t) ~((uint64_t) val) | |
294 | ---- | |
e9b06e2b | 295 | |
11613178 PP |
296 | For the binary bitwise operators, it is the equivalent of those C |
297 | expressions: | |
e9b06e2b | 298 | |
11613178 PP |
299 | [source,c] |
300 | ---- | |
301 | (int64_t) ((uint64_t) lhs >> (uint64_t) rhs) | |
302 | (int64_t) ((uint64_t) lhs << (uint64_t) rhs) | |
303 | (int64_t) ((uint64_t) lhs & (uint64_t) rhs) | |
304 | (int64_t) ((uint64_t) lhs ^ (uint64_t) rhs) | |
305 | (int64_t) ((uint64_t) lhs | (uint64_t) rhs) | |
306 | ---- | |
e9b06e2b | 307 | |
11613178 PP |
308 | If the right-hand side of a bitwise shift operator (`<<` and `>>`) is |
309 | not in the [0,{nbsp}63] range, the whole filter expression evaluates to | |
310 | false. | |
e9b06e2b PP |
311 | |
312 | NOTE: Although it is possible to filter the process ID of an event when | |
313 | the `pid` context has been added to its channel using, for example, | |
314 | `$ctx.pid == 2832`, it is recommended to use the PID tracker instead, | |
7c1a4458 | 315 | which is much more efficient (see man:lttng-track(1)). |
e9b06e2b | 316 | |
11613178 | 317 | Filter expression examples: |
e9b06e2b PP |
318 | |
319 | ---------------------------- | |
320 | msg_id == 23 && size >= 2048 | |
321 | ---------------------------- | |
322 | ||
323 | ------------------------------------------------- | |
324 | $ctx.procname == "lttng*" && (!flag || poel < 34) | |
325 | ------------------------------------------------- | |
326 | ||
327 | --------------------------------------------------------- | |
328 | $app.my_provider:my_context == 17.34e9 || some_enum >= 14 | |
329 | --------------------------------------------------------- | |
330 | ||
c52365cc PP |
331 | --------------------------------------- |
332 | $ctx.cpu_id == 2 && filename != "*.log" | |
333 | --------------------------------------- | |
f69e7997 | 334 | |
11613178 PP |
335 | ------------------------------------------------ |
336 | eax_reg & 0xff7 == 0x240 && x[4] >> 12 <= 0x1234 | |
337 | ------------------------------------------------ | |
338 | ||
e9b06e2b PP |
339 | |
340 | [[log-levels]] | |
341 | Log levels | |
342 | ~~~~~~~~~~ | |
343 | Tracepoints and log statements in applications have an attached log | |
344 | level. Application event rules can contain a _log level_ condition. | |
345 | ||
346 | With the option:--loglevel option, the event source's log level must | |
347 | be at least as severe as the option's argument. With the | |
348 | option:--loglevel-only option, the event source's log level must match | |
349 | the option's argument. | |
350 | ||
351 | The available log levels are: | |
352 | ||
353 | User space domain (option:--userspace option):: | |
354 | Shortcuts such as `system` are allowed. | |
355 | + | |
356 | * `TRACE_EMERG` (0) | |
357 | * `TRACE_ALERT` (1) | |
358 | * `TRACE_CRIT` (2) | |
359 | * `TRACE_ERR` (3) | |
360 | * `TRACE_WARNING` (4) | |
361 | * `TRACE_NOTICE` (5) | |
362 | * `TRACE_INFO` (6) | |
363 | * `TRACE_DEBUG_SYSTEM` (7) | |
364 | * `TRACE_DEBUG_PROGRAM` (8) | |
365 | * `TRACE_DEBUG_PROCESS` (9) | |
366 | * `TRACE_DEBUG_MODULE` (10) | |
367 | * `TRACE_DEBUG_UNIT` (11) | |
368 | * `TRACE_DEBUG_FUNCTION` (12) | |
369 | * `TRACE_DEBUG_LINE` (13) | |
370 | * `TRACE_DEBUG` (14) | |
371 | ||
372 | `java.util.logging` domain (option:--jul option):: | |
373 | Shortcuts such as `severe` are allowed. | |
374 | + | |
375 | * `JUL_OFF` (`INT32_MAX`) | |
376 | * `JUL_SEVERE` (1000) | |
377 | * `JUL_WARNING` (900) | |
378 | * `JUL_INFO` (800) | |
379 | * `JUL_CONFIG` (700) | |
380 | * `JUL_FINE` (500) | |
381 | * `JUL_FINER` (400) | |
382 | * `JUL_FINEST` (300) | |
383 | * `JUL_ALL` (`INT32_MIN`) | |
384 | ||
385 | Apache log4j domain (option:--log4j option):: | |
386 | Shortcuts such as `severe` are allowed. | |
387 | + | |
388 | * `LOG4J_OFF` (`INT32_MAX`) | |
389 | * `LOG4J_FATAL` (50000) | |
390 | * `LOG4J_ERROR` (40000) | |
391 | * `LOG4J_WARN` (30000) | |
392 | * `LOG4J_INFO` (20000) | |
393 | * `LOG4J_DEBUG` (10000) | |
394 | * `LOG4J_TRACE` (5000) | |
395 | * `LOG4J_ALL` (`INT32_MIN`) | |
396 | ||
397 | Python domain (option:--python option):: | |
398 | Shortcuts such as `critical` are allowed. | |
399 | + | |
400 | * `PYTHON_CRITICAL` (50) | |
401 | * `PYTHON_ERROR` (40) | |
402 | * `PYTHON_WARNING` (30) | |
403 | * `PYTHON_INFO` (20) | |
404 | * `PYTHON_DEBUG` (10) | |
405 | * `PYTHON_NOTSET` (0) | |
406 | ||
407 | ||
01b065c4 PP |
408 | [[userspace-probe]] |
409 | Dynamic user space probes | |
410 | ~~~~~~~~~~~~~~~~~~~~~~~~~ | |
411 | With the option:--userspace-probe option, you can instrument function | |
412 | entries of any user space binary (application or library) using either | |
413 | an available symbol name or a SystemTap SDT probe's provider and probe | |
414 | names. | |
415 | ||
416 | The option:--userspace-probe option must be specified with the | |
417 | option:--kernel option because it uses Linux's uprobe feature to | |
418 | dynamically instrument a user space application or library. | |
419 | ||
420 | As of this version, dynamic probe events do not record any payload | |
421 | field. | |
422 | ||
423 | The two available option:--userspace-probe option's argument formats | |
424 | are: | |
425 | ||
426 | option:--userspace-probe=`[elf:]PATH:SYMBOL`:: | |
427 | Dynamically instrument an available symbol within a user space | |
428 | executable. | |
429 | + | |
430 | -- | |
431 | 'PATH':: | |
432 | Application or library path. | |
433 | + | |
434 | This can be: | |
435 | + | |
436 | * An absolute path. | |
437 | * A relative path. | |
438 | * An executable's name as found in the directories listed in the | |
439 | `PATH` environment variable. | |
440 | ||
441 | 'SYMBOL':: | |
442 | Symbol name of the function of which to instrument the entry. | |
443 | + | |
444 | This can be any defined code symbol listed by the man:nm(1) command | |
445 | (including with its nloption:--dynamic option which lists dynamic | |
446 | symbols). | |
447 | -- | |
448 | + | |
449 | As of this version, not specifying `elf:` is equivalent to specifying | |
450 | it. | |
451 | + | |
452 | Examples: | |
453 | + | |
454 | * `--userspace-probe=/usr/lib/libc.so.6:malloc` | |
455 | * `--userspace-probe=./myapp:createUser` | |
456 | * `--userspace-probe=httpd:ap_run_open_htaccess` | |
457 | ||
458 | option:--userspace-probe=`sdt:PATH:PROVIDER:NAME`:: | |
459 | Dynamically instrument an SDT probe within a user space executable. | |
460 | + | |
461 | -- | |
462 | 'PATH':: | |
463 | Application or library path. | |
464 | + | |
465 | This can be: | |
466 | + | |
467 | * An absolute path. | |
468 | * A relative path. | |
469 | * An executable's name as found in the directories listed in the | |
470 | `PATH` environment variable. | |
471 | ||
472 | __PROVIDER__:__NAME__:: | |
473 | SDT provider and probe names. | |
474 | + | |
475 | For example, with the following SDT probe: | |
476 | + | |
477 | [source,c] | |
478 | ---- | |
479 | DTRACE_PROBE2("server", "accept_request", | |
480 | request_id, ip_addr); | |
481 | ---- | |
482 | + | |
483 | The provider/probe name pair is `server:accept_request`. | |
484 | -- | |
485 | + | |
486 | Example: | |
487 | + | |
488 | * `--userspace-probe=sdt:./build/server:server:accept_request` | |
489 | ||
490 | ||
e9b06e2b PP |
491 | include::common-cmd-options-head.txt[] |
492 | ||
493 | ||
494 | Domain | |
495 | ~~~~~~ | |
496 | One of: | |
497 | ||
498 | option:-j, option:--jul:: | |
499 | Create or enable event rules in the `java.util.logging` | |
500 | (JUL) domain. | |
501 | ||
502 | option:-k, option:--kernel:: | |
503 | Create or enable event rules in the Linux kernel domain. | |
504 | ||
505 | option:-l, option:--log4j:: | |
506 | Create or enable event rules in the Apache log4j domain. | |
507 | ||
508 | option:-p, option:--python:: | |
509 | Create or enable event rules in the Python domain. | |
510 | ||
511 | option:-u, option:--userspace:: | |
512 | Create or enable event rules in the user space domain. | |
513 | ||
514 | ||
515 | Target | |
516 | ~~~~~~ | |
59b19c3c | 517 | option:-c 'CHANNEL', option:--channel='CHANNEL':: |
e9b06e2b PP |
518 | Create or enable event rules in the channel named 'CHANNEL' instead |
519 | of the default channel name `channel0`. | |
520 | ||
59b19c3c | 521 | option:-s 'SESSION', option:--session='SESSION':: |
e9b06e2b PP |
522 | Create or enable event rules in the tracing session named 'SESSION' |
523 | instead of the current tracing session. | |
524 | ||
525 | ||
526 | Event source type | |
527 | ~~~~~~~~~~~~~~~~~ | |
528 | One of: | |
529 | ||
530 | option:--function='SOURCE':: | |
531 | Linux kernel kretprobe. Only available with the option:--kernel | |
532 | domain option. 'SOURCE' is one of: | |
533 | + | |
534 | * Function address (`0x` prefix supported) | |
535 | * Function symbol | |
536 | * Function symbol and offset (`SYMBOL+OFFSET` format) | |
537 | ||
538 | option:--probe='SOURCE':: | |
539 | Linux kernel kprobe. Only available with the option:--kernel | |
540 | domain option. 'SOURCE' is one of: | |
541 | + | |
542 | * Address (`0x` prefix supported) | |
543 | * Symbol | |
544 | * Symbol and offset (`SYMBOL+OFFSET` format) | |
545 | ||
01b065c4 PP |
546 | option:--userspace-probe='SOURCE':: |
547 | Linux kernel uprobe. Only available with the option:--kernel | |
548 | domain option. | |
549 | + | |
550 | See the <<userspace-probe,Dynamic user space probes>> section for more | |
551 | information about the option's argument 'SOURCE'. | |
552 | ||
e9b06e2b PP |
553 | option:--syscall:: |
554 | Linux kernel system call. Only available with the option:--kernel | |
555 | domain option. | |
556 | ||
557 | option:--tracepoint:: | |
558 | Linux kernel or application tracepoint (default). | |
559 | ||
560 | ||
561 | Log level | |
562 | ~~~~~~~~~ | |
563 | One of: | |
564 | ||
565 | option:--loglevel='LOGLEVEL':: | |
566 | Add log level condition to the event rule: the event source's | |
567 | defined log level must be at least as severe as 'LOGLEVEL'. | |
568 | See the <<log-levels,Log levels>> section above for the available | |
569 | log levels. Only available with application domains. | |
570 | ||
571 | option:--loglevel-only='LOGLEVEL':: | |
572 | Add log level condition to the event rule: the event source's | |
573 | defined log level must match 'LOGLEVEL'. See the | |
574 | <<log-levels,Log levels>> section above for the available log | |
575 | levels. Only available with application domains. | |
576 | ||
577 | ||
578 | Filtering and exclusion | |
579 | ~~~~~~~~~~~~~~~~~~~~~~~ | |
59b19c3c | 580 | option:-x 'EVENT'[,'EVENT']..., option:--exclude='EVENT'[,'EVENT']...:: |
e9b06e2b | 581 | Exclude events named 'EVENT' from the event rule. This option |
f69e7997 PP |
582 | can be used when the command's 'EVENT' argument contains at least |
583 | one wildcard star (`*`) to exclude specific names. 'EVENT' can also | |
584 | contain wildcard stars. To use a | |
585 | literal `,` character, use :esccomma:. | |
586 | Only available with the option:--userspace domain. | |
e9b06e2b | 587 | |
59b19c3c | 588 | option:-f 'EXPR', option:--filter='EXPR':: |
e9b06e2b PP |
589 | Add filter expression condition to the event rule. Expression 'EXPR' |
590 | must evaluate to true when executed against the dynamic values of | |
11613178 | 591 | event fields. See the <<filter-expr,Filter expression>> |
e9b06e2b PP |
592 | section above for more information. |
593 | ||
594 | ||
595 | Shortcuts | |
596 | ~~~~~~~~~ | |
597 | option:-a, option:--all:: | |
598 | Equivalent to an 'EVENT' argument named `*` (wildcard) when also | |
599 | using the option:--tracepoint (default) or option:--syscall option. | |
600 | ||
601 | ||
602 | include::common-cmd-help-options.txt[] | |
603 | ||
604 | ||
605 | include::common-cmd-footer.txt[] | |
606 | ||
607 | ||
608 | SEE ALSO | |
609 | -------- | |
7c1a4458 PP |
610 | man:lttng-disable-event(1), |
611 | man:lttng(1) |