lttng_ust_tracelog(3)

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

NAME

6       lttng_ust_tracelog, lttng_ust_vtracelog - LTTng-UST printf(3)-like
7       interface with a log level
8

SYNOPSIS

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

DESCRIPTION

23       The LTTng-UST lttng_ust_tracelog() and lttng_ust_vtracelog() API allows
24       you to trace your application with the help of simple printf(3)-like
25       and vprintf(3)-like macros, with an additional parameter for the
26       desired log level.
27
28       The fmt argument is passed directly as the fmt parameter of
29       vasprintf(3), as well as:
30
31       For lttng_ust_tracelog()
32           The optional parameters following fmt.
33
34       For lttng_ust_vtracelog()
35           The ap parameter as the ap parameter of vasprintf(3) (va_list
36           type).
37
38       The purpose of lttng_ust_tracelog() and lttng_ust_vtracelog() is to
39       ease the migration from logging to tracing.
40
41       The available values for the level parameter are:
42
43       LTTNG_UST_TRACEPOINT_LOGLEVEL_EMERG
44           System is unusable.
45
46       LTTNG_UST_TRACEPOINT_LOGLEVEL_ALERT
47           Action must be taken immediately.
48
49       LTTNG_UST_TRACEPOINT_LOGLEVEL_CRIT
50           Critical conditions.
51
52       LTTNG_UST_TRACEPOINT_LOGLEVEL_ERR
53           Error conditions.
54
55       LTTNG_UST_TRACEPOINT_LOGLEVEL_WARNING
56           Warning conditions.
57
58       LTTNG_UST_TRACEPOINT_LOGLEVEL_NOTICE
59           Normal, but significant, condition.
60
61       LTTNG_UST_TRACEPOINT_LOGLEVEL_INFO
62           Informational message.
63
64       LTTNG_UST_TRACEPOINT_LOGLEVEL_DEBUG_SYSTEM
65           Debug information with system-level scope (set of programs).
66
67       LTTNG_UST_TRACEPOINT_LOGLEVEL_DEBUG_PROGRAM
68           Debug information with program-level scope (set of processes).
69
70       LTTNG_UST_TRACEPOINT_LOGLEVEL_DEBUG_PROCESS
71           Debug information with process-level scope (set of modules).
72
73       LTTNG_UST_TRACEPOINT_LOGLEVEL_DEBUG_MODULE
74           Debug information with module (executable/library) scope (set of
75           units).
76
77       LTTNG_UST_TRACEPOINT_LOGLEVEL_DEBUG_UNIT
78           Debug information with compilation unit scope (set of functions).
79
80       LTTNG_UST_TRACEPOINT_LOGLEVEL_DEBUG_FUNCTION
81           Debug information with function-level scope.
82
83       LTTNG_UST_TRACEPOINT_LOGLEVEL_DEBUG_LINE
84           Debug information with line-level scope (default log level).
85
86       LTTNG_UST_TRACEPOINT_LOGLEVEL_DEBUG
87           Debug-level message.
88
89       To use lttng_ust_tracelog() or lttng_ust_vtracelog(), include
90       <lttng/tracelog.h> where you need it, and link your application with
91       liblttng-ust and liblttng-ust-common. See the EXAMPLE section below for
92       a complete usage example.
93
94       Once your application is instrumented with lttng_ust_tracelog() and/or
95       lttng_ust_vtracelog() calls and ready to run, use lttng-enable-event(1)
96       to enable the lttng_ust_tracelog:* event. You can isolate specific log
97       levels with the --loglevel and --loglevel-only options of this command.
98
99       The lttng_ust_tracelog() and lttng_ust_vtracelog() events contain the
100       following fields:
101
102       ┌───────────┬───────────────────────────┐
103       │Field name │ Description               │
104       ├───────────┼───────────────────────────┤
105       │           │                           │
106       │line       │ Line in source file where │
107       │           │ lttng_ust_tracelog() was  │
108       │           │ called.                   │
109       ├───────────┼───────────────────────────┤
110       │           │                           │
111       │file       │ Source file from which    │
112       │           │ lttng_ust_tracelog() was  │
113       │           │ called.                   │
114       ├───────────┼───────────────────────────┤
115       │           │                           │
116       │func       │ Function name from which  │
117       │           │ lttng_ust_tracelog() was  │
118       │           │ called.                   │
119       ├───────────┼───────────────────────────┤
120       │           │                           │
121       │msg        │ Formatted string output.  │
122       └───────────┴───────────────────────────┘
123
124       If you do not need to attach a specific log level to a
125       lttng_ust_tracelog()/lttng_ust_vtracelog() call, use
126       lttng_ust_tracef(3) instead.
127
128       See also the LIMITATIONS section below for important limitations to
129       consider when using lttng_ust_tracelog() or lttng_ust_vtracelog().
130

EXAMPLE

132       Here’s a usage example of lttng_ust_tracelog():
133
134           #include <stdlib.h>
135           #include <lttng/tracelog.h>
136
137           int main(int argc, char *argv[])
138           {
139               int i;
140
141               if (argc < 2) {
142                   lttng_ust_tracelog(LTTNG_UST_TRACEPOINT_LOGLEVEL_CRIT,
143                                      "Not enough arguments: %d", argc);
144                   return EXIT_FAILURE;
145               }
146
147               lttng_ust_tracelog(LTTNG_UST_TRACEPOINT_LOGLEVEL_INFO,
148                                  "Starting app with %d arguments", argc);
149
150               for (i = 0; i < argc; i++) {
151                   lttng_ust_tracelog(LTTNG_UST_TRACEPOINT_LOGLEVEL_DEBUG,
152                                      "Argument %d: %s", i, argv[i]);
153               }
154
155               lttng_ust_tracelog(LTTNG_UST_TRACEPOINT_LOGLEVEL_INFO,
156                                  "Exiting app");
157               return EXIT_SUCCESS;
158           }
159
160       This C source file, saved as app.c, can be compiled into a program like
161       this:
162
163           $ cc -o app app.c -llttng-ust -llttng-ust-common
164
165       You can create an LTTng tracing session, enable all the
166       lttng_ust_tracelog() events, and start the created tracing session like
167       this:
168
169           $ lttng create my-session
170           $ lttng enable-event --userspace 'lttng_ust_tracelog:*'
171           $ lttng start
172
173       Or you can enable lttng_ust_tracelog() events matching a log level at
174       least as severe as a given log level:
175
176           $ lttng enable-event --userspace 'lttng_ust_tracelog:*' \
177                                --loglevel=INFO
178
179       Next, start the program to be traced:
180
181           $ ./app a few arguments passed to this application
182
183       Finally, stop the tracing session, and inspect the recorded events:
184
185           $ lttng stop
186           $ lttng view
187

LIMITATIONS

189       The lttng_ust_tracelog() and lttng_ust_vtracelog() utility macros were
190       developed to make user space tracing super simple, albeit with notable
191       disadvantages compared to custom, full-fledged tracepoint providers:
192
193       •   All generated events have the same provider/event names.
194
195       •   There’s no static type checking.
196
197       •   The only event field with user data you actually get, named msg, is
198           a string potentially containing the values you passed to the macro
199           using your own format. This also means that you cannot use
200           filtering using a custom expression at run time because there are
201           no isolated fields.
202
203       •   Since lttng_ust_tracelog() and lttng_ust_vtracelog() use C standard
204           library’s vasprintf(3) function in the background to format the
205           strings at run time, their expected performance is lower than using
206           custom tracepoint providers with typed fields, which do not require
207           a conversion to a string.
208
209       •   Generally, a string containing the textual representation of the
210           user data fields is not as compact as binary fields in the
211           resulting trace.
212
213       Thus, lttng_ust_tracelog()/lttng_ust_vtracelog() are useful for quick
214       prototyping and debugging, but should not be considered for any
215       permanent/serious application instrumentation.
216
217       lttng_ust_vtracelog() does not have a STAP_PROBEV() call, because
218       STAP_PROBEV() does not support va_list. If you need it, you should emit
219       this call yourself.
220
221       See lttng-ust(3) to learn more about custom tracepoint providers.
222

BUGS

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

RESOURCES

228       •   LTTng project website <http://lttng.org>
229
230       •   LTTng documentation <http://lttng.org/docs>
231
232       •   Git repositories <http://git.lttng.org>
233
234       •   GitHub organization <http://github.com/lttng>
235
236       •   Continuous integration <http://ci.lttng.org/>
237
238       •   Mailing list <http://lists.lttng.org> for support and development:
239           lttng-dev@lists.lttng.org
240
241       •   IRC channel <irc://irc.oftc.net/lttng>: #lttng on irc.oftc.net
242

COPYRIGHTS

244       This macro is part of the LTTng-UST project.
245
246       This macro is distributed under the GNU Lesser General Public License,
247       version 2.1 <http://www.gnu.org/licenses/old-
248       licenses/lgpl-2.1.en.html>. See the for more details.
249

THANKS

251       Thanks to Ericsson for funding this work, providing real-life use
252       cases, and testing.
253
254       Special thanks to Michel Dagenais and the DORSAL laboratory
255       <http://www.dorsal.polymtl.ca/> at École Polytechnique de Montréal for
256       the LTTng journey.
257

AUTHORS

259       LTTng-UST was originally written by Mathieu Desnoyers, with additional
260       contributions from various other people. It is currently maintained by
261       Mathieu Desnoyers <mailto:mathieu.desnoyers@efficios.com>.
262