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

NAME

6       tracelog - LTTng-UST printf(3)-like interface with a log level
7

SYNOPSIS

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

DESCRIPTION

16       The LTTng-UST tracelog() API allows you to trace your application with
17       the help of a simple printf(3)-like macro, with an additional parameter
18       for the desired log level. The fmt argument is passed directly to the
19       fmt parameter of vasprintf(3), as well as the optional parameters
20       following fmt.
21
22       The purpose of tracelog() is to ease the migration from logging to
23       tracing.
24
25       The available values for the level parameter are:
26
27       TRACE_EMERG
28           System is unusable.
29
30       TRACE_ALERT
31           Action must be taken immediately.
32
33       TRACE_CRIT
34           Critical conditions.
35
36       TRACE_ERR
37           Error conditions.
38
39       TRACE_WARNING
40           Warning conditions.
41
42       TRACE_NOTICE
43           Normal, but significant, condition.
44
45       TRACE_INFO
46           Informational message.
47
48       TRACE_DEBUG_SYSTEM
49           Debug information with system-level scope (set of programs).
50
51       TRACE_DEBUG_PROGRAM
52           Debug information with program-level scope (set of processes).
53
54       TRACE_DEBUG_PROCESS
55           Debug information with process-level scope (set of modules).
56
57       TRACE_DEBUG_MODULE
58           Debug information with module (executable/library) scope (set of
59           units).
60
61       TRACE_DEBUG_UNIT
62           Debug information with compilation unit scope (set of functions).
63
64       TRACE_DEBUG_FUNCTION
65           Debug information with function-level scope.
66
67       TRACE_DEBUG_LINE
68           Debug information with line-level scope (default log level).
69
70       TRACE_DEBUG
71           Debug-level message.
72
73       To use tracelog(), include <lttng/tracelog.h> where you need it, and
74       link your application with liblttng-ust. See the EXAMPLE section below
75       for a complete usage example.
76
77       Once your application is instrumented with tracelog() calls and ready
78       to run, use lttng-enable-event(1) to enable the lttng_ust_tracelog:*
79       event. You can isolate specific log levels with the --loglevel and
80       --loglevel-only options of this command.
81
82       The tracelog() events contain the following fields:
83
84       ┌───────────┬───────────────────────────┐
85Field name Description               
86       ├───────────┼───────────────────────────┤
87       │           │                           │
88line       │ Line in source file where │
89       │           │ tracelog() was called.    │
90       ├───────────┼───────────────────────────┤
91       │           │                           │
92file       │ Source file from which    │
93       │           │ tracelog() was called.    │
94       ├───────────┼───────────────────────────┤
95       │           │                           │
96func       │ Function name from which  │
97       │           │ tracelog() was called.    │
98       ├───────────┼───────────────────────────┤
99       │           │                           │
100msg        │ Formatted string output.  │
101       └───────────┴───────────────────────────┘
102
103       If you do not need to attach a specific log level to a tracelog() call,
104       use tracef(3) instead.
105
106       See also the LIMITATIONS section below for important limitations to
107       consider when using tracelog().
108

EXAMPLE

110       Here’s a usage example of tracelog():
111
112           #include <stdlib.h>
113           #include <lttng/tracelog.h>
114
115           int main(int argc, char *argv[])
116           {
117               int i;
118
119               if (argc < 2) {
120                   tracelog(TRACE_CRIT, "Not enough arguments: %d", argc);
121                   return EXIT_FAILURE;
122               }
123
124               tracelog(TRACE_INFO, "Starting app with %d arguments", argc);
125
126               for (i = 0; i < argc; i++) {
127                   tracelog(TRACE_DEBUG, "Argument %d: %s", i, argv[i]);
128               }
129
130               tracelog(TRACE_INFO, "Exiting app");
131
132               return EXIT_SUCCESS;
133           }
134
135       This C source file, saved as app.c, can be compiled into a program like
136       this:
137
138           $ cc -o app app.c -llttng-ust
139
140       You can create an LTTng tracing session, enable all the tracelog()
141       events, and start the created tracing session like this:
142
143           $ lttng create my-session
144           $ lttng enable-event --userspace 'lttng_ust_tracelog:*'
145           $ lttng start
146
147       Or you can enable tracelog() events matching a log level at least as
148       severe as a given log level:
149
150           $ lttng enable-event --userspace 'lttng_ust_tracelog:*' \
151                              --loglevel=TRACE_INFO
152
153       Next, start the program to be traced:
154
155           $ ./app a few arguments passed to this application
156
157       Finally, stop the tracing session, and inspect the recorded events:
158
159           $ lttng stop
160           $ lttng view
161

LIMITATIONS

163       The tracelog() utility macro was developed to make user space tracing
164       super simple, albeit with notable disadvantages compared to custom,
165       full-fledged tracepoint providers:
166
167       •   All generated events have the same provider/event names.
168
169       •   There’s no static type checking.
170
171       •   The only event field with user data you actually get, named msg, is
172           a string potentially containing the values you passed to the macro
173           using your own format. This also means that you cannot use
174           filtering using a custom expression at run time because there are
175           no isolated fields.
176
177       •   Since tracelog() uses C standard library’s vasprintf(3) function in
178           the background to format the strings at run time, its expected
179           performance is lower than using custom tracepoint providers with
180           typed fields, which do not require a conversion to a string.
181
182       •   Generally, a string containing the textual representation of the
183           user data fields is not as compact as binary fields in the
184           resulting trace.
185
186       Thus, tracelog() is useful for quick prototyping and debugging, but
187       should not be considered for any permanent/serious application
188       instrumentation.
189
190       See lttng-ust(3) to learn more about custom tracepoint providers.
191

BUGS

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

RESOURCES

197       •   LTTng project website <http://lttng.org>
198
199       •   LTTng documentation <http://lttng.org/docs>
200
201       •   Git repositories <http://git.lttng.org>
202
203       •   GitHub organization <http://github.com/lttng>
204
205       •   Continuous integration <http://ci.lttng.org/>
206
207       •   Mailing list <http://lists.lttng.org> for support and development:
208           lttng-dev@lists.lttng.org
209
210       •   IRC channel <irc://irc.oftc.net/lttng>: #lttng on irc.oftc.net
211

COPYRIGHTS

213       This macro is part of the LTTng-UST project.
214
215       This macro is distributed under the GNU Lesser General Public License,
216       version 2.1 <http://www.gnu.org/licenses/old-
217       licenses/lgpl-2.1.en.html>. See the COPYING
218       <https://github.com/lttng/lttng-ust/blob/v2.12.2/COPYING> file for more
219       details.
220

THANKS

222       Thanks to Ericsson for funding this work, providing real-life use
223       cases, and testing.
224
225       Special thanks to Michel Dagenais and the DORSAL laboratory
226       <http://www.dorsal.polymtl.ca/> at École Polytechnique de Montréal for
227       the LTTng journey.
228

AUTHORS

230       LTTng-UST was originally written by Mathieu Desnoyers, with additional
231       contributions from various other people. It is currently maintained by
232       Mathieu Desnoyers <mailto:mathieu.desnoyers@efficios.com>.
233

SEE ALSO

235       tracef(3), lttng-ust(3), lttng(1), printf(3)
236
237
238
239LTTng 2.12.2                      05/14/2021                       TRACELOG(3)
Impressum