8 tracef, vtracef - LTTng-UST printf(3)-like interface
14 *#include <lttng/tracef.h>*
17 #define *tracef*('fmt', ...)
18 #define *vtracef*('fmt', 'ap')
20 Link with `-llttng-ust`.
25 The LTTng-UST `tracef()` and `vtracef()` API allows you to trace your
26 application with the help of simple man:printf(3)-like and
27 man:vprintf(3)-like macros.
29 The 'fmt' argument is passed directly as the 'fmt' parameter of
30 man:vasprintf(3), as well as:
33 The optional parameters following 'fmt'.
36 The 'ap' parameter as the 'ap' parameter of man:vasprintf(3)
39 To use `tracef()` or `vtracef()`, include `<lttng/tracef.h>` where you
40 need it, and link your application with `liblttng-ust`. See the
41 <<example,EXAMPLE>> section below for a complete usage example.
43 Once your application is instrumented with `tracef()` and/or `vtracef()`
44 calls and ready to run, use man:lttng-enable-event(1) to enable the
45 `lttng_ust_tracef:*` event.
47 The `tracef()` and `vtracef()` events contain a single field, named
48 `msg`, which is the formatted string output.
50 If you need to attach a specific log level to a `tracef()`/`vtracef()`
51 call, use man:tracelog(3) and man:vtracelog(3) instead.
53 See also the <<limitations,LIMITATIONS>> section below for important
54 limitations to consider when using `tracef()` or `vtracef()`.
60 Here's a usage example of `tracef()`:
62 -------------------------------------------------------------------
64 #include <lttng/tracef.h>
70 for (i = 0; i < 25; i++) {
71 tracef("my message: %s, this integer: %d", "a message", i);
76 -------------------------------------------------------------------
78 This C source file, saved as `app.c`, can be compiled into a program
83 $ cc -o app app.c -llttng-ust
86 You can create an LTTng tracing session, enable the `tracef()` events,
87 and start the created tracing session like this:
91 $ lttng create my-session
92 $ lttng enable-event --userspace 'lttng_ust_tracef:*'
96 Next, start the program to be traced:
103 Finally, stop the tracing session, and inspect the recorded events:
117 include::tracef-tracelog-limitations.txt[]
120 include::common-footer.txt[]
122 include::common-copyrights.txt[]
124 include::common-authors.txt[]