1 // SPDX-FileCopyrightText: 2016 Philippe Proulx <pproulx@efficios.com>
2 // SPDX-License-Identifier: CC-BY-4.0
11 lttng_ust_tracef, lttng_ust_vtracef - LTTng-UST printf(3)-like interface
17 *#include <lttng/tracef.h>*
20 #define *lttng_ust_tracef*('fmt', ...)
21 #define *lttng_ust_vtracef*('fmt', 'ap')
26 * If you define `_LGPL_SOURCE` before including
27 `<lttng/tracef.h>` (directly or indirectly): `-llttng-ust-common`
32 The LTTng-UST `lttng_ust_tracef()` and `lttng_ust_vtracef()` API allows
33 you to trace your application with the help of simple man:printf(3)-like
34 and man:vprintf(3)-like macros.
36 The 'fmt' argument is passed directly as the 'fmt' parameter of
37 man:vasprintf(3), as well as:
39 For `lttng_ust_tracef()`::
40 The optional parameters following 'fmt'.
42 For `lttng_ust_vtracef()`::
43 The 'ap' parameter as the 'ap' parameter of man:vasprintf(3)
46 To use `lttng_ust_tracef()` or `lttng_ust_vtracef()`, include
47 `<lttng/tracef.h>` where you need it, and link your application with
48 `liblttng-ust` and `liblttng-ust-common`. See the <<example,EXAMPLE>>
49 section below for a complete usage example.
51 Once your application is instrumented with `lttng_ust_tracef()` and/or
52 `lttng_ust_vtracef()` calls and ready to run, use
53 man:lttng-enable-event(1) to enable the `lttng_ust_tracef:*` event.
55 The `lttng_ust_tracef()` and `lttng_ust_vtracef()` events contain a
56 single field, named `msg`, which is the formatted string output.
58 If you need to attach a specific log level to a
59 `lttng_ust_tracef()`/`lttng_ust_vtracef()` call, use
60 man:lttng_ust_tracelog(3) and man:lttng_ust_vtracelog(3) instead.
62 See also the <<limitations,LIMITATIONS>> section below for important
63 limitations to consider when using `lttng_ust_tracef()` or
64 `lttng_ust_vtracef()`.
70 Here's a usage example of `lttng_ust_tracef()`:
72 -------------------------------------------------------------------
74 #include <lttng/tracef.h>
80 for (i = 0; i < 25; i++) {
81 lttng_ust_tracef("my message: %s, this integer: %d",
87 -------------------------------------------------------------------
89 This C source file, saved as `app.c`, can be compiled into a program
94 $ cc -o app app.c -llttng-ust -llttng-ust-common
97 You can create an LTTng tracing session, enable the `lttng_ust_tracef()`
98 events, and start the created tracing session like this:
102 $ lttng create my-session
103 $ lttng enable-event --userspace 'lttng_ust_tracef:*'
107 Next, start the program to be traced:
114 Finally, stop the tracing session, and inspect the recorded events:
126 :macro-suffix: tracef
128 include::tracef-tracelog-limitations.txt[]
131 include::common-footer.txt[]
133 include::common-copyrights.txt[]
135 include::common-authors.txt[]
140 man:lttng_ust_tracelog(3),
141 man:lttng_ust_vtracelog(3),