1TRACELOG(3) LTTng Manual TRACELOG(3)
2
6 tracelog - LTTng-UST printf(3)-like interface with a log level
7
9 #include <lttng/tracelog.h>
10 #define tracelog(level, fmt, ...)
12 Link with -llttng-ust.
14
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 The purpose of tracelog() is to ease the migration from logging to
23 tracing.
24 The available values for the level parameter are:
26 TRACE_EMERG
28 System is unusable.
29 TRACE_ALERT
31 Action must be taken immediately.
32 TRACE_CRIT
34 Critical conditions.
35 TRACE_ERR
37 Error conditions.
38 TRACE_WARNING
40 Warning conditions.
41 TRACE_NOTICE
43 Normal, but significant, condition.
44 TRACE_INFO
46 Informational message.
47 TRACE_DEBUG_SYSTEM
49 Debug information with system-level scope (set of programs).
50 TRACE_DEBUG_PROGRAM
52 Debug information with program-level scope (set of processes).
53 TRACE_DEBUG_PROCESS
55 Debug information with process-level scope (set of modules).
56 TRACE_DEBUG_MODULE
58 Debug information with module (executable/library) scope (set of
59 units).
60 TRACE_DEBUG_UNIT
62 Debug information with compilation unit scope (set of functions).
63 TRACE_DEBUG_FUNCTION
65 Debug information with function-level scope.
66 TRACE_DEBUG_LINE
68 Debug information with line-level scope (default log level).
69 TRACE_DEBUG
71 Debug-level message.
72 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 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 The tracelog() events contain the following fields:
83 ┌───────────┬───────────────────────────┐
85 │Field name │ Description │
86 ├───────────┼───────────────────────────┤
87 │ │ │
88 │line │ Line in source file where │
89 │ │ tracelog() was called. │
90 ├───────────┼───────────────────────────┤
91 │ │ │
92 │file │ Source file from which │
93 │ │ tracelog() was called. │
94 ├───────────┼───────────────────────────┤
95 │ │ │
96 │func │ Function name from which │
97 │ │ tracelog() was called. │
98 ├───────────┼───────────────────────────┤
99 │ │ │
100 │msg │ Formatted string output. │
101 └───────────┴───────────────────────────┘
102 If you do not need to attach a specific log level to a tracelog() call,
104 use tracef(3) instead.
105 See also the LIMITATIONS section below for important limitations to
107 consider when using tracelog().
108
110 Here’s a usage example of tracelog():
111 #include <stdlib.h>
113 #include <lttng/tracelog.h>
114 int main(int argc, char *argv[])
116 {
117 int i;
118 if (argc < 2) {
120 tracelog(TRACE_CRIT, "Not enough arguments: %d", argc);
121 return EXIT_FAILURE;
122 }
123 tracelog(TRACE_INFO, "Starting app with %d arguments", argc);
125 for (i = 0; i < argc; i++) {
127 tracelog(TRACE_DEBUG, "Argument %d: %s", i, argv[i]);
128 }
129 tracelog(TRACE_INFO, "Exiting app");
131 return EXIT_SUCCESS;
133 }
134 This C source file, saved as app.c, can be compiled into a program like
136 this:
137 $ cc -o app app.c -llttng-ust
139 You can create an LTTng tracing session, enable all the tracelog()
141 events, and start the created tracing session like this:
142 $ lttng create my-session
144 $ lttng enable-event --userspace 'lttng_ust_tracelog:*'
145 $ lttng start
146 Or you can enable tracelog() events matching a log level at least as
148 severe as a given log level:
149 $ lttng enable-event --userspace 'lttng_ust_tracelog:*' \
151 --loglevel=TRACE_INFO
152 Next, start the program to be traced:
154 $ ./app a few arguments passed to this application
156 Finally, stop the tracing session, and inspect the recorded events:
158 $ lttng stop
160 $ lttng view
161
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 • All generated events have the same provider/event names.
168 • There’s no static type checking.
170 • 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 • 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 • 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 Thus, tracelog() is useful for quick prototyping and debugging, but
187 should not be considered for any permanent/serious application
188 instrumentation.
189 See lttng-ust(3) to learn more about custom tracepoint providers.
191
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
197 • LTTng project website <http://lttng.org>
198 • LTTng documentation <http://lttng.org/docs>
200 • Git repositories <http://git.lttng.org>
202 • GitHub organization <http://github.com/lttng>
204 • Continuous integration <http://ci.lttng.org/>
206 • Mailing list <http://lists.lttng.org> for support and development:
208 lttng-dev@lists.lttng.org
209 • IRC channel <irc://irc.oftc.net/lttng>: #lttng on irc.oftc.net
211
213 This macro is part of the LTTng-UST project.
214 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
222 Thanks to Ericsson for funding this work, providing real-life use
223 cases, and testing.
224 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
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
235 tracef(3), lttng-ust(3), lttng(1), printf(3)
236LTTng 2.12.2 05/14/2021 TRACELOG(3)