tracef(3)

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

NAME

6       tracef - LTTng-UST printf(3)-like interface
7

SYNOPSIS

9       #include <lttng/tracef.h>
10
11       #define tracef(fmt, ...)
12
13       Link with -llttng-ust.
14

DESCRIPTION

16       The LTTng-UST tracef() API allows you to trace your application with
17       the help of a simple printf(3)-like macro. The fmt argument is passed
18       directly to the fmt parameter of vasprintf(3), as well as the optional
19       parameters following fmt.
20
21       To use tracef(), include <lttng/tracef.h> where you need it, and link
22       your application with liblttng-ust. See the EXAMPLE section below for a
23       complete usage example.
24
25       Once your application is instrumented with tracef() calls and ready to
26       run, use lttng-enable-event(1) to enable the lttng_ust_tracef:* event.
27
28       The tracef() events contain a single field, named msg, which is the
29       formatted string output.
30
31       If you need to attach a specific log level to a tracef() call, use
32       tracelog(3) instead.
33
34       See also the LIMITATIONS section below for important limitations to
35       consider when using tracef().
36

EXAMPLE

38       Here’s a usage example of tracef():
39
40           #include <stdlib.h>
41           #include <lttng/tracef.h>
42
43           int main(void)
44           {
45               int i;
46
47               for (i = 0; i < 25; i++) {
48                   tracef("my message: %s, this integer: %d", "a message", i);
49               }
50
51               return EXIT_SUCCESS;
52           }
53
54       This C source file, saved as app.c, can be compiled into a program like
55       this:
56
57           $ cc -o app app.c -llttng-ust
58
59       You can create an LTTng tracing session, enable the tracef() events,
60       and start the created tracing session like this:
61
62           $ lttng create my-session
63           $ lttng enable-event --userspace 'lttng_ust_tracef:*'
64           $ lttng start
65
66       Next, start the program to be traced:
67
68           $ ./app
69
70       Finally, stop the tracing session, and inspect the recorded events:
71
72           $ lttng stop
73           $ lttng view
74

LIMITATIONS

76       The tracef() utility macro was developed to make user space tracing
77       super simple, albeit with notable disadvantages compared to custom,
78       full-fledged tracepoint providers:
79
80       ·   All generated events have the same provider/event names.
81
82       ·   There’s no static type checking.
83
84       ·   The only event field with user data you actually get, named msg, is
85           a string potentially containing the values you passed to the macro
86           using your own format. This also means that you cannot use
87           filtering using a custom expression at run time because there are
88           no isolated fields.
89
90       ·   Since tracef() uses C standard library’s vasprintf(3) function in
91           the background to format the strings at run time, its expected
92           performance is lower than using custom tracepoint providers with
93           typed fields, which do not require a conversion to a string.
94
95       ·   Generally, a string containing the textual representation of the
96           user data fields is not as compact as binary fields in the
97           resulting trace.
98
99       Thus, tracef() is useful for quick prototyping and debugging, but
100       should not be considered for any permanent/serious application
101       instrumentation.
102
103       See lttng-ust(3) to learn more about custom tracepoint providers.
104

BUGS

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

RESOURCES

110       ·   LTTng project website <http://lttng.org>
111
112       ·   LTTng documentation <http://lttng.org/docs>
113
114       ·   Git repositories <http://git.lttng.org>
115
116       ·   GitHub organization <http://github.com/lttng>
117
118       ·   Continuous integration <http://ci.lttng.org/>
119
120       ·   Mailing list <http://lists.lttng.org> for support and development:
121           lttng-dev@lists.lttng.org
122
123       ·   IRC channel <irc://irc.oftc.net/lttng>: #lttng on irc.oftc.net
124

COPYRIGHTS

126       This macro is part of the LTTng-UST project.
127
128       This macro is distributed under the GNU Lesser General Public License,
129       version 2.1 <http://www.gnu.org/licenses/old-
130       licenses/lgpl-2.1.en.html>. See the COPYING
131       <https://github.com/lttng/lttng-ust/blob/master/COPYING> file for more
132       details.
133

THANKS

135       Thanks to Ericsson for funding this work, providing real-life use
136       cases, and testing.
137
138       Special thanks to Michel Dagenais and the DORSAL laboratory
139       <http://www.dorsal.polymtl.ca/> at École Polytechnique de Montréal for
140       the LTTng journey.
141

AUTHORS

143       LTTng-UST was originally written by Mathieu Desnoyers, with additional
144       contributions from various other people. It is currently maintained by
145       Mathieu Desnoyers <mailto:mathieu.desnoyers@efficios.com>.
146