8 tracelog, vtracelog - LTTng-UST printf(3)-like interface with a log level
14 *#include <lttng/tracelog.h>*
17 #define *tracelog*('level', 'fmt', ...)
18 #define *vtracelog*('level', 'fmt', 'ap')
20 Link with `-llttng-ust`.
25 The LTTng-UST `tracelog()` and `vtracelog()` API allows you to trace
26 your application with the help of simple man:printf(3)-like and
27 man:vprintf(3)-like macros, with an additional parameter for the desired
30 The 'fmt' argument is passed directly as the 'fmt' parameter of
31 man:vasprintf(3), as well as:
34 The optional parameters following 'fmt'.
37 The 'ap' parameter as the 'ap' parameter of man:vasprintf(3)
40 The purpose of `tracelog()` and `vtracelog()` is to ease the migration
41 from logging to tracing.
43 The available values for the 'level' parameter are:
45 include::log-levels.txt[]
47 To use `tracelog()` or `vtracelog()`, include `<lttng/tracelog.h>` where
48 you need it, and link your application with `liblttng-ust`. See the
49 <<example,EXAMPLE>> section below for a complete usage example.
51 Once your application is instrumented with `tracelog()` and/or
52 `vtracelog()` calls and ready to run, use man:lttng-enable-event(1) to
53 enable the `lttng_ust_tracelog:*` event. You can isolate specific log
54 levels with the nloption:--loglevel and nloption:--loglevel-only options
57 The `tracelog()` and `vtracelog()` events contain the following fields:
61 |Field name |Description
64 |Line in source file where `tracelog()` was called.
67 |Source file from which `tracelog()` was called.
70 |Function name from which `tracelog()` was called.
73 |Formatted string output.
76 If you do not need to attach a specific log level to a
77 `tracelog()`/`vtracelog()` call, use man:tracef(3) instead.
79 See also the <<limitations,LIMITATIONS>> section below for important
80 limitations to consider when using `tracelog()` or `vtracelog()`.
86 Here's a usage example of `tracelog()`:
88 -------------------------------------------------------------------
90 #include <lttng/tracelog.h>
92 int main(int argc, char *argv[])
97 tracelog(TRACE_CRIT, "Not enough arguments: %d", argc);
101 tracelog(TRACE_INFO, "Starting app with %d arguments", argc);
103 for (i = 0; i < argc; i++) {
104 tracelog(TRACE_DEBUG, "Argument %d: %s", i, argv[i]);
107 tracelog(TRACE_INFO, "Exiting app");
111 -------------------------------------------------------------------
113 This C source file, saved as `app.c`, can be compiled into a program
118 $ cc -o app app.c -llttng-ust
121 You can create an LTTng tracing session, enable all the `tracelog()`
122 events, and start the created tracing session like this:
126 $ lttng create my-session
127 $ lttng enable-event --userspace 'lttng_ust_tracelog:*'
131 Or you can enable `tracelog()` events matching a log level at least
132 as severe as a given log level:
136 $ lttng enable-event --userspace 'lttng_ust_tracelog:*' \
137 --loglevel=TRACE_INFO
140 Next, start the program to be traced:
144 $ ./app a few arguments passed to this application
147 Finally, stop the tracing session, and inspect the recorded events:
159 :macro-name: tracelog
161 include::tracef-tracelog-limitations.txt[]
164 include::common-footer.txt[]
166 include::common-copyrights.txt[]
168 include::common-authors.txt[]