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