1 // SPDX-FileCopyrightText: 2016 Philippe Proulx <pproulx@efficios.com>
2 // SPDX-License-Identifier: CC-BY-4.0
11 lttng_ust_tracelog, lttng_ust_vtracelog - LTTng-UST printf(3)-like interface with a log level
17 *#include <lttng/tracelog.h>*
20 #define *lttng_ust_tracelog*('level', 'fmt', ...)
21 #define *lttng_ust_vtracelog*('level', 'fmt', 'ap')
26 * If you define `_LGPL_SOURCE` before including
27 `<lttng/tracelog.h>` (directly or indirectly): `-llttng-ust-common`
31 The LTTng-UST `lttng_ust_tracelog()` and `lttng_ust_vtracelog()` API
32 allows you to trace your application with the help of simple
33 man:printf(3)-like and man:vprintf(3)-like macros, with an additional
34 parameter for the desired log level.
36 The 'fmt' argument is passed directly as the 'fmt' parameter of
37 man:vasprintf(3), as well as:
39 For `lttng_ust_tracelog()`::
40 The optional parameters following 'fmt'.
42 For `lttng_ust_vtracelog()`::
43 The 'ap' parameter as the 'ap' parameter of man:vasprintf(3)
46 The purpose of `lttng_ust_tracelog()` and `lttng_ust_vtracelog()` is to
47 ease the migration from logging to tracing.
49 The available values for the 'level' parameter are:
51 include::log-levels.txt[]
53 To use `lttng_ust_tracelog()` or `lttng_ust_vtracelog()`, include
54 `<lttng/tracelog.h>` where you need it, and link your application with
55 `liblttng-ust` and `liblttng-ust-common`. See the <<example,EXAMPLE>>
56 section below for a complete usage example.
58 Once your application is instrumented with `lttng_ust_tracelog()` and/or
59 `lttng_ust_vtracelog()` calls and ready to run, use
60 man:lttng-enable-event(1) to enable the `lttng_ust_tracelog:*` event.
61 You can isolate specific log levels with the nloption:--loglevel and
62 nloption:--loglevel-only options of this command.
64 The `lttng_ust_tracelog()` and `lttng_ust_vtracelog()` events contain
69 |Field name |Description
72 |Line in source file where `lttng_ust_tracelog()` was called.
75 |Source file from which `lttng_ust_tracelog()` was called.
78 |Function name from which `lttng_ust_tracelog()` was called.
81 |Formatted string output.
84 If you do not need to attach a specific log level to a
85 `lttng_ust_tracelog()`/`lttng_ust_vtracelog()` call, use
86 man:lttng_ust_tracef(3) instead.
88 See also the <<limitations,LIMITATIONS>> section below for important
89 limitations to consider when using `lttng_ust_tracelog()` or
90 `lttng_ust_vtracelog()`.
96 Here's a usage example of `lttng_ust_tracelog()`:
98 -------------------------------------------------------------------
100 #include <lttng/tracelog.h>
102 int main(int argc, char *argv[])
107 lttng_ust_tracelog(LTTNG_UST_TRACEPOINT_LOGLEVEL_CRIT,
108 "Not enough arguments: %d", argc);
112 lttng_ust_tracelog(LTTNG_UST_TRACEPOINT_LOGLEVEL_INFO,
113 "Starting app with %d arguments", argc);
115 for (i = 0; i < argc; i++) {
116 lttng_ust_tracelog(LTTNG_UST_TRACEPOINT_LOGLEVEL_DEBUG,
117 "Argument %d: %s", i, argv[i]);
120 lttng_ust_tracelog(LTTNG_UST_TRACEPOINT_LOGLEVEL_INFO,
124 -------------------------------------------------------------------
126 This C source file, saved as `app.c`, can be compiled into a program
131 $ cc -o app app.c -llttng-ust -llttng-ust-common
134 You can create an LTTng tracing session, enable all the
135 `lttng_ust_tracelog()` events, and start the created tracing session
140 $ lttng create my-session
141 $ lttng enable-event --userspace 'lttng_ust_tracelog:*'
145 Or you can enable `lttng_ust_tracelog()` events matching a log level at
146 least as severe as a given log level:
150 $ lttng enable-event --userspace 'lttng_ust_tracelog:*' \
154 Next, start the program to be traced:
158 $ ./app a few arguments passed to this application
161 Finally, stop the tracing session, and inspect the recorded events:
173 :macro-suffix: tracelog
175 include::tracef-tracelog-limitations.txt[]
178 include::common-footer.txt[]
180 include::common-copyrights.txt[]
182 include::common-authors.txt[]
187 man:lttng_ust_tracef(3),
188 man:lttng_ust_vtracef(3),