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 |
b981f450 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 | ||
b981f450 | 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 | |
b981f450 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 | ~~~~~~~~~~~~~~~~~~ | |
b981f450 | 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 | ||
b981f450 | 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 | ||
b981f450 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 | ||
b981f450 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 | ||
b981f450 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 | |
0e63136b GB |
413 | an available symbol name or a SystemTap User-level Statically Defined |
414 | Tracing (USDT, a DTrace-style marker) probe's provider and probe names. | |
415 | As of this version, only USDT probes that are :not: surrounded by a | |
416 | reference counter (semaphore) are supported. | |
b981f450 PP |
417 | |
418 | The option:--userspace-probe option must be specified with the | |
419 | option:--kernel option because it uses Linux's uprobe feature to | |
420 | dynamically instrument a user space application or library. | |
421 | ||
422 | As of this version, dynamic probe events do not record any payload | |
423 | field. | |
424 | ||
b981f450 | 425 | |
fa72991a PP |
426 | include::common-cmd-options-head.txt[] |
427 | ||
428 | ||
429 | Domain | |
430 | ~~~~~~ | |
431 | One of: | |
432 | ||
433 | option:-j, option:--jul:: | |
434 | Create or enable event rules in the `java.util.logging` | |
435 | (JUL) domain. | |
436 | ||
437 | option:-k, option:--kernel:: | |
438 | Create or enable event rules in the Linux kernel domain. | |
439 | ||
440 | option:-l, option:--log4j:: | |
441 | Create or enable event rules in the Apache log4j domain. | |
442 | ||
443 | option:-p, option:--python:: | |
444 | Create or enable event rules in the Python domain. | |
445 | ||
446 | option:-u, option:--userspace:: | |
447 | Create or enable event rules in the user space domain. | |
448 | ||
449 | ||
450 | Target | |
451 | ~~~~~~ | |
452 | option:-c 'CHANNEL', option:--channel='CHANNEL':: | |
453 | Create or enable event rules in the channel named 'CHANNEL' instead | |
454 | of the default channel name `channel0`. | |
455 | ||
456 | option:-s 'SESSION', option:--session='SESSION':: | |
457 | Create or enable event rules in the tracing session named 'SESSION' | |
458 | instead of the current tracing session. | |
459 | ||
460 | ||
461 | Event source type | |
462 | ~~~~~~~~~~~~~~~~~ | |
463 | One of: | |
464 | ||
465 | option:--function='SOURCE':: | |
466 | Dynamic kernel return probe (kretprobe). Only available with the | |
467 | option:--kernel domain option. 'SOURCE' is one of: | |
468 | + | |
469 | * Function address (`0x` prefix supported) | |
470 | * Function symbol name | |
471 | * Function symbol name and offset (__SYMBOL__++pass:[+]++__OFFSET__ format) | |
472 | ||
473 | option:--probe='SOURCE':: | |
474 | Dynamic kernel probe (kprobe). Only available with the | |
475 | option:--kernel domain option. 'SOURCE' is one of: | |
476 | + | |
477 | * Address (`0x` prefix supported) | |
478 | * Symbol nane | |
479 | * Symbol name and offset (__SYMBOL__++pass:[+]++__OFFSET__ format) | |
480 | ||
481 | option:--userspace-probe='SOURCE':: | |
482 | Dynamic user space probe (uprobe). Only available with the | |
483 | option:--kernel domain option. See the | |
484 | <<userspace-probe,Dynamic user space probes>> section. | |
485 | + | |
486 | 'SOURCE' is one of: | |
487 | + | |
488 | -- | |
489 | \[++elf:++]__PATH__++:++__SYMBOL__:: | |
b981f450 | 490 | Dynamically instrument an available symbol within a user space |
fa72991a | 491 | application or library. |
b981f450 PP |
492 | + |
493 | -- | |
494 | 'PATH':: | |
495 | Application or library path. | |
496 | + | |
497 | This can be: | |
498 | + | |
499 | * An absolute path. | |
500 | * A relative path. | |
fa72991a | 501 | * An application's name as found in the directories listed in the |
b981f450 PP |
502 | `PATH` environment variable. |
503 | ||
504 | 'SYMBOL':: | |
505 | Symbol name of the function of which to instrument the entry. | |
506 | + | |
507 | This can be any defined code symbol listed by the man:nm(1) command | |
508 | (including with its nloption:--dynamic option which lists dynamic | |
509 | symbols). | |
510 | -- | |
511 | + | |
512 | As of this version, not specifying `elf:` is equivalent to specifying | |
513 | it. | |
514 | + | |
515 | Examples: | |
516 | + | |
517 | * `--userspace-probe=/usr/lib/libc.so.6:malloc` | |
518 | * `--userspace-probe=./myapp:createUser` | |
519 | * `--userspace-probe=httpd:ap_run_open_htaccess` | |
520 | ||
fa72991a | 521 | ++sdt:++__PATH__++:++__PROVIDER__++:++__NAME__:: |
0e63136b | 522 | Dynamically instrument a USDT probe within a user space application |
fa72991a | 523 | or library. |
b981f450 PP |
524 | + |
525 | -- | |
526 | 'PATH':: | |
527 | Application or library path. | |
528 | + | |
529 | This can be: | |
530 | + | |
531 | * An absolute path. | |
532 | * A relative path. | |
fa72991a | 533 | * An application's name as found in the directories listed in the |
b981f450 PP |
534 | `PATH` environment variable. |
535 | ||
fa72991a | 536 | __PROVIDER__++:++__NAME__:: |
0e63136b | 537 | USDT provider and probe names. |
b981f450 | 538 | + |
0e63136b | 539 | For example, with the following USDT probe: |
b981f450 PP |
540 | + |
541 | [source,c] | |
542 | ---- | |
543 | DTRACE_PROBE2("server", "accept_request", | |
544 | request_id, ip_addr); | |
545 | ---- | |
546 | + | |
547 | The provider/probe name pair is `server:accept_request`. | |
548 | -- | |
549 | + | |
550 | Example: | |
551 | + | |
552 | * `--userspace-probe=sdt:./build/server:server:accept_request` | |
fa72991a | 553 | -- |
b981f450 | 554 | |
e9b06e2b PP |
555 | option:--syscall:: |
556 | Linux kernel system call. Only available with the option:--kernel | |
557 | domain option. | |
558 | ||
559 | option:--tracepoint:: | |
560 | Linux kernel or application tracepoint (default). | |
561 | ||
562 | ||
563 | Log level | |
564 | ~~~~~~~~~ | |
565 | One of: | |
566 | ||
567 | option:--loglevel='LOGLEVEL':: | |
568 | Add log level condition to the event rule: the event source's | |
569 | defined log level must be at least as severe as 'LOGLEVEL'. | |
570 | See the <<log-levels,Log levels>> section above for the available | |
571 | log levels. Only available with application domains. | |
572 | ||
573 | option:--loglevel-only='LOGLEVEL':: | |
574 | Add log level condition to the event rule: the event source's | |
575 | defined log level must match 'LOGLEVEL'. See the | |
576 | <<log-levels,Log levels>> section above for the available log | |
577 | levels. Only available with application domains. | |
578 | ||
579 | ||
580 | Filtering and exclusion | |
581 | ~~~~~~~~~~~~~~~~~~~~~~~ | |
59b19c3c | 582 | option:-x 'EVENT'[,'EVENT']..., option:--exclude='EVENT'[,'EVENT']...:: |
e9b06e2b | 583 | Exclude events named 'EVENT' from the event rule. This option |
f69e7997 PP |
584 | can be used when the command's 'EVENT' argument contains at least |
585 | one wildcard star (`*`) to exclude specific names. 'EVENT' can also | |
586 | contain wildcard stars. To use a | |
587 | literal `,` character, use :esccomma:. | |
588 | Only available with the option:--userspace domain. | |
e9b06e2b | 589 | |
59b19c3c | 590 | option:-f 'EXPR', option:--filter='EXPR':: |
e9b06e2b PP |
591 | Add filter expression condition to the event rule. Expression 'EXPR' |
592 | must evaluate to true when executed against the dynamic values of | |
11613178 | 593 | event fields. See the <<filter-expr,Filter expression>> |
e9b06e2b PP |
594 | section above for more information. |
595 | ||
596 | ||
597 | Shortcuts | |
598 | ~~~~~~~~~ | |
599 | option:-a, option:--all:: | |
600 | Equivalent to an 'EVENT' argument named `*` (wildcard) when also | |
601 | using the option:--tracepoint (default) or option:--syscall option. | |
602 | ||
603 | ||
604 | include::common-cmd-help-options.txt[] | |
605 | ||
606 | ||
607 | include::common-cmd-footer.txt[] | |
608 | ||
609 | ||
610 | SEE ALSO | |
611 | -------- | |
7c1a4458 PP |
612 | man:lttng-disable-event(1), |
613 | man:lttng(1) |