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