8 lttng_ust_tracef, lttng_ust_vtracef - LTTng-UST printf(3)-like interface
14 *#include <lttng/tracef.h>*
17 #define *lttng_ust_tracef*('fmt', ...)
18 #define *lttng_ust_vtracef*('fmt', 'ap')
23 * If you define `_LGPL_SOURCE` before including
24 `<lttng/tracef.h>` (directly or indirectly): `-llttng-ust-common`
29 The LTTng-UST `lttng_ust_tracef()` and `lttng_ust_vtracef()` API allows
30 you to trace your application with the help of simple man:printf(3)-like
31 and man:vprintf(3)-like macros.
33 The 'fmt' argument is passed directly as the 'fmt' parameter of
34 man:vasprintf(3), as well as:
36 For `lttng_ust_tracef()`::
37 The optional parameters following 'fmt'.
39 For `lttng_ust_vtracef()`::
40 The 'ap' parameter as the 'ap' parameter of man:vasprintf(3)
43 To use `lttng_ust_tracef()` or `lttng_ust_vtracef()`, include
44 `<lttng/tracef.h>` where you need it, and link your application with
45 `liblttng-ust` and `liblttng-ust-common`. See the <<example,EXAMPLE>>
46 section below for a complete usage example.
48 Once your application is instrumented with `lttng_ust_tracef()` and/or
49 `lttng_ust_vtracef()` calls and ready to run, use
50 man:lttng-enable-event(1) to enable the `lttng_ust_tracef:*` event.
52 The `lttng_ust_tracef()` and `lttng_ust_vtracef()` events contain a
53 single field, named `msg`, which is the formatted string output.
55 If you need to attach a specific log level to a
56 `lttng_ust_tracef()`/`lttng_ust_vtracef()` call, use
57 man:lttng_ust_tracelog(3) and man:lttng_ust_vtracelog(3) instead.
59 See also the <<limitations,LIMITATIONS>> section below for important
60 limitations to consider when using `lttng_ust_tracef()` or
61 `lttng_ust_vtracef()`.
67 Here's a usage example of `lttng_ust_tracef()`:
69 -------------------------------------------------------------------
71 #include <lttng/tracef.h>
77 for (i = 0; i < 25; i++) {
78 lttng_ust_tracef("my message: %s, this integer: %d",
84 -------------------------------------------------------------------
86 This C source file, saved as `app.c`, can be compiled into a program
91 $ cc -o app app.c -llttng-ust -llttng-ust-common
94 You can create an LTTng tracing session, enable the `lttng_ust_tracef()`
95 events, and start the created tracing session like this:
99 $ lttng create my-session
100 $ lttng enable-event --userspace 'lttng_ust_tracef:*'
104 Next, start the program to be traced:
111 Finally, stop the tracing session, and inspect the recorded events:
123 :macro-suffix: tracef
125 include::tracef-tracelog-limitations.txt[]
128 include::common-footer.txt[]
130 include::common-copyrights.txt[]
132 include::common-authors.txt[]
137 man:lttng_ust_tracelog(3),
138 man:lttng_ust_vtracelog(3),