8 tracelog - LTTng-UST printf(3)-like interface with a log level
14 *#include <lttng/tracelog.h>*
17 #define *tracelog*('level', 'fmt', ...)
19 Link with `-llttng-ust`.
24 The LTTng-UST `tracelog()` API allows you to trace your application with
25 the help of a simple man:printf(3)-like macro, with an additional
26 parameter for the desired log level. The 'fmt' argument is passed
27 directly to the 'fmt' parameter of man:vasprintf(3), as well as
28 the optional parameters following 'fmt'.
30 The purpose of `tracelog()` is to ease the migration from logging to
33 The available values for the 'level' parameter are:
35 include::log-levels.txt[]
37 To use `tracelog()`, include `<lttng/tracelog.h>` where you need it, and
38 link your application with `liblttng-ust`. See the <<example,EXAMPLE>>
39 section below for a complete usage example.
41 Once your application is instrumented with `tracelog()` calls and
42 ready to run, use man:lttng-enable-event(1) to enable the
43 `lttng_ust_tracelog:*` event. You can isolate specific log levels with
44 the nloption:--loglevel and nloption:--loglevel-only options of this
47 The `tracelog()` events contain the following fields:
50 |===============================================================
51 | Field name | Description
52 | `line` | Line in source file where `tracelog()` was called
53 | `file` | Source file from which `tracelog()` was called
54 | `func` | Function name from which `tracelog()` was called
55 | `msg` | Formatted string output
56 |===============================================================
58 If you do not need to attach a specific log level to a `tracelog()`
59 call, use man:tracef(3) instead.
61 See also the <<limitations,LIMITATIONS>> section below for important
62 limitations to consider when using `tracelog()`.
68 Here's a usage example of `tracelog()`:
70 -------------------------------------------------------------------
72 #include <lttng/tracelog.h>
74 int main(int argc, char *argv[])
79 tracelog(TRACE_CRIT, "Not enough arguments: %d", argc);
83 tracelog(TRACE_INFO, "Starting app with %d arguments", argc);
85 for (i = 0; i < argc; i++) {
86 tracelog(TRACE_DEBUG, "Argument %d: %s", i, argv[i]);
89 tracelog(TRACE_INFO, "Exiting app");
93 -------------------------------------------------------------------
95 This C source file, saved as `app.c`, can be compiled into a program
99 ---------------------------
100 cc -o app app.c -llttng-ust
101 ---------------------------
103 You can create an LTTng tracing session, enable all the `tracelog()`
104 events, and start the created tracing session like this:
107 ---------------------------------------------------
108 lttng create my-session
109 lttng enable-event --userspace 'lttng_ust_tracelog:*'
111 ---------------------------------------------------
113 Or you can enable `tracelog()` events matching a log level at least
114 as severe as a given log level:
117 -------------------------------------------------------
118 lttng enable-event --userspace 'lttng_ust_tracelog:*' \
119 --loglevel=TRACE_INFO
120 -------------------------------------------------------
122 Next, start the program to be traced:
125 ------------------------------------------------
126 ./app a few arguments passed to this application
127 ------------------------------------------------
129 Finally, stop the tracing session, and inspect the recorded events:
141 :macro-name: tracelog
143 include::tracef-tracelog-limitations.txt[]
146 include::common-footer.txt[]
148 include::common-copyrights.txt[]
150 include::common-authors.txt[]