Commit | Line | Data |
---|---|---|
4ddbd0b7 PP |
1 | tracef(3) |
2 | ========= | |
3 | :object-type: macro | |
4 | ||
5 | ||
6 | NAME | |
7 | ---- | |
cfd56ee1 | 8 | tracef, vtracef - LTTng-UST printf(3)-like interface |
4ddbd0b7 PP |
9 | |
10 | ||
11 | SYNOPSIS | |
12 | -------- | |
13 | [verse] | |
14 | *#include <lttng/tracef.h>* | |
15 | ||
16 | [verse] | |
17 | #define *tracef*('fmt', ...) | |
d6208c2d | 18 | #define *vtracef*('fmt', 'ap') |
4ddbd0b7 PP |
19 | |
20 | Link with `-llttng-ust`. | |
21 | ||
22 | ||
23 | DESCRIPTION | |
24 | ----------- | |
d6208c2d PP |
25 | The LTTng-UST `tracef()` and `vtracef()` API allows you to trace your |
26 | application with the help of simple man:printf(3)-like and | |
27 | man:vprintf(3)-like macros. | |
4ddbd0b7 | 28 | |
d6208c2d PP |
29 | The 'fmt' argument is passed directly as the 'fmt' parameter of |
30 | man:vasprintf(3), as well as: | |
4ddbd0b7 | 31 | |
d6208c2d PP |
32 | For `tracef()`:: |
33 | The optional parameters following 'fmt'. | |
34 | ||
35 | For `vtracef()`:: | |
36 | The 'ap' parameter as the 'ap' parameter of man:vasprintf(3) | |
37 | (`va_list` type). | |
38 | ||
39 | To use `tracef()` or `vtracef()`, include `<lttng/tracef.h>` where you | |
40 | need it, and link your application with `liblttng-ust`. See the | |
41 | <<example,EXAMPLE>> section below for a complete usage example. | |
42 | ||
43 | Once your application is instrumented with `tracef()` and/or `vtracef()` | |
44 | calls and ready to run, use man:lttng-enable-event(1) to enable the | |
4ddbd0b7 PP |
45 | `lttng_ust_tracef:*` event. |
46 | ||
d6208c2d PP |
47 | The `tracef()` and `vtracef()` events contain a single field, named |
48 | `msg`, which is the formatted string output. | |
4ddbd0b7 | 49 | |
d6208c2d PP |
50 | If you need to attach a specific log level to a `tracef()`/`vtracef()` |
51 | call, use man:tracelog(3) and man:vtracelog(3) instead. | |
4ddbd0b7 PP |
52 | |
53 | See also the <<limitations,LIMITATIONS>> section below for important | |
cfd56ee1 | 54 | limitations to consider when using `tracef()` or `vtracef()`. |
4ddbd0b7 PP |
55 | |
56 | ||
57 | [[example]] | |
58 | EXAMPLE | |
59 | ------- | |
60 | Here's a usage example of `tracef()`: | |
61 | ||
62 | ------------------------------------------------------------------- | |
63 | #include <stdlib.h> | |
64 | #include <lttng/tracef.h> | |
65 | ||
66 | int main(void) | |
67 | { | |
68 | int i; | |
69 | ||
70 | for (i = 0; i < 25; i++) { | |
71 | tracef("my message: %s, this integer: %d", "a message", i); | |
72 | } | |
73 | ||
74 | return EXIT_SUCCESS; | |
75 | } | |
76 | ------------------------------------------------------------------- | |
77 | ||
78 | This C source file, saved as `app.c`, can be compiled into a program | |
79 | like this: | |
80 | ||
81 | [role="term"] | |
636cf2a0 PP |
82 | ---- |
83 | $ cc -o app app.c -llttng-ust | |
84 | ---- | |
4ddbd0b7 PP |
85 | |
86 | You can create an LTTng tracing session, enable the `tracef()` events, | |
87 | and start the created tracing session like this: | |
88 | ||
89 | [role="term"] | |
636cf2a0 PP |
90 | ---- |
91 | $ lttng create my-session | |
92 | $ lttng enable-event --userspace 'lttng_ust_tracef:*' | |
93 | $ lttng start | |
94 | ---- | |
4ddbd0b7 PP |
95 | |
96 | Next, start the program to be traced: | |
97 | ||
98 | [role="term"] | |
636cf2a0 PP |
99 | ---- |
100 | $ ./app | |
101 | ---- | |
4ddbd0b7 PP |
102 | |
103 | Finally, stop the tracing session, and inspect the recorded events: | |
104 | ||
105 | [role="term"] | |
636cf2a0 PP |
106 | ---- |
107 | $ lttng stop | |
108 | $ lttng view | |
109 | ---- | |
4ddbd0b7 PP |
110 | |
111 | ||
112 | [[limitations]] | |
113 | LIMITATIONS | |
114 | ----------- | |
115 | :macro-name: tracef | |
116 | ||
117 | include::tracef-tracelog-limitations.txt[] | |
118 | ||
119 | ||
120 | include::common-footer.txt[] | |
121 | ||
122 | include::common-copyrights.txt[] | |
123 | ||
124 | include::common-authors.txt[] | |
125 | ||
126 | ||
127 | SEE ALSO | |
128 | -------- | |
129 | man:tracelog(3), | |
d6208c2d | 130 | man:vtracelog(3), |
4ddbd0b7 PP |
131 | man:lttng-ust(3), |
132 | man:lttng(1), | |
133 | man:printf(3) |