lttng_ust_tracef(3)

1LTTNG_UST_TRACEF(3)              LTTng Manual              LTTNG_UST_TRACEF(3)
2
3
4

NAME

6       lttng_ust_tracef, lttng_ust_vtracef - LTTng-UST printf(3)-like
7       interface
8

SYNOPSIS

10       #include <lttng/tracef.h>
11
12       #define lttng_ust_tracef(fmt, ...)
13       #define lttng_ust_vtracef(fmt, ap)
14
15       Link with:
16
17       •   -llttng-ust
18
19       •   If you define _LGPL_SOURCE before including <lttng/tracef.h>
20           (directly or indirectly): -llttng-ust-common
21

DESCRIPTION

23       The LTTng-UST lttng_ust_tracef() and lttng_ust_vtracef() API allows you
24       to trace your application with the help of simple printf(3)-like and
25       vprintf(3)-like macros.
26
27       The fmt argument is passed directly as the fmt parameter of
28       vasprintf(3), as well as:
29
30       For lttng_ust_tracef()
31           The optional parameters following fmt.
32
33       For lttng_ust_vtracef()
34           The ap parameter as the ap parameter of vasprintf(3) (va_list
35           type).
36
37       To use lttng_ust_tracef() or lttng_ust_vtracef(), include
38       <lttng/tracef.h> where you need it, and link your application with
39       liblttng-ust and liblttng-ust-common. See the EXAMPLE section below for
40       a complete usage example.
41
42       Once your application is instrumented with lttng_ust_tracef() and/or
43       lttng_ust_vtracef() calls and ready to run, use lttng-enable-event(1)
44       to enable the lttng_ust_tracef:* event.
45
46       The lttng_ust_tracef() and lttng_ust_vtracef() events contain a single
47       field, named msg, which is the formatted string output.
48
49       If you need to attach a specific log level to a
50       lttng_ust_tracef()/lttng_ust_vtracef() call, use lttng_ust_tracelog(3)
51       and lttng_ust_vtracelog(3) instead.
52
53       See also the LIMITATIONS section below for important limitations to
54       consider when using lttng_ust_tracef() or lttng_ust_vtracef().
55

EXAMPLE

57       Here’s a usage example of lttng_ust_tracef():
58
59           #include <stdlib.h>
60           #include <lttng/tracef.h>
61
62           int main(void)
63           {
64               int i;
65
66               for (i = 0; i < 25; i++) {
67                   lttng_ust_tracef("my message: %s, this integer: %d",
68                                    "a message", i);
69               }
70
71               return EXIT_SUCCESS;
72           }
73
74       This C source file, saved as app.c, can be compiled into a program like
75       this:
76
77           $ cc -o app app.c -llttng-ust -llttng-ust-common
78
79       You can create an LTTng tracing session, enable the lttng_ust_tracef()
80       events, and start the created tracing session like this:
81
82           $ lttng create my-session
83           $ lttng enable-event --userspace 'lttng_ust_tracef:*'
84           $ lttng start
85
86       Next, start the program to be traced:
87
88           $ ./app
89
90       Finally, stop the tracing session, and inspect the recorded events:
91
92           $ lttng stop
93           $ lttng view
94

LIMITATIONS

96       The lttng_ust_tracef() and lttng_ust_vtracef() utility macros were
97       developed to make user space tracing super simple, albeit with notable
98       disadvantages compared to custom, full-fledged tracepoint providers:
99
100       •   All generated events have the same provider/event names.
101
102       •   There’s no static type checking.
103
104       •   The only event field with user data you actually get, named msg, is
105           a string potentially containing the values you passed to the macro
106           using your own format. This also means that you cannot use
107           filtering using a custom expression at run time because there are
108           no isolated fields.
109
110       •   Since lttng_ust_tracef() and lttng_ust_vtracef() use C standard
111           library’s vasprintf(3) function in the background to format the
112           strings at run time, their expected performance is lower than using
113           custom tracepoint providers with typed fields, which do not require
114           a conversion to a string.
115
116       •   Generally, a string containing the textual representation of the
117           user data fields is not as compact as binary fields in the
118           resulting trace.
119
120       Thus, lttng_ust_tracef()/lttng_ust_vtracef() are useful for quick
121       prototyping and debugging, but should not be considered for any
122       permanent/serious application instrumentation.
123
124       lttng_ust_vtracef() does not have a STAP_PROBEV() call, because
125       STAP_PROBEV() does not support va_list. If you need it, you should emit
126       this call yourself.
127
128       See lttng-ust(3) to learn more about custom tracepoint providers.
129

BUGS

131       If you encounter any issue or usability problem, please report it on
132       the LTTng bug tracker <https://bugs.lttng.org/projects/lttng-ust>.
133

RESOURCES

135       •   LTTng project website <http://lttng.org>
136
137       •   LTTng documentation <http://lttng.org/docs>
138
139       •   Git repositories <http://git.lttng.org>
140
141       •   GitHub organization <http://github.com/lttng>
142
143       •   Continuous integration <http://ci.lttng.org/>
144
145       •   Mailing list <http://lists.lttng.org> for support and development:
146           lttng-dev@lists.lttng.org
147
148       •   IRC channel <irc://irc.oftc.net/lttng>: #lttng on irc.oftc.net
149

COPYRIGHTS

151       This macro is part of the LTTng-UST project.
152
153       This macro is distributed under the GNU Lesser General Public License,
154       version 2.1 <http://www.gnu.org/licenses/old-
155       licenses/lgpl-2.1.en.html>. See the for more details.
156

THANKS

158       Thanks to Ericsson for funding this work, providing real-life use
159       cases, and testing.
160
161       Special thanks to Michel Dagenais and the DORSAL laboratory
162       <http://www.dorsal.polymtl.ca/> at École Polytechnique de Montréal for
163       the LTTng journey.
164

AUTHORS

166       LTTng-UST was originally written by Mathieu Desnoyers, with additional
167       contributions from various other people. It is currently maintained by
168       Mathieu Desnoyers <mailto:mathieu.desnoyers@efficios.com>.
169