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')
20 Link with `-llttng-ust -llttng-ust-common`.
25 The LTTng-UST `lttng_ust_tracef()` and `lttng_ust_vtracef()` API allows
26 you to trace your application with the help of simple man:printf(3)-like
27 and man:vprintf(3)-like macros.
29 The 'fmt' argument is passed directly as the 'fmt' parameter of
30 man:vasprintf(3), as well as:
32 For `lttng_ust_tracef()`::
33 The optional parameters following 'fmt'.
35 For `lttng_ust_vtracef()`::
36 The 'ap' parameter as the 'ap' parameter of man:vasprintf(3)
39 To use `lttng_ust_tracef()` or `lttng_ust_vtracef()`, include
40 `<lttng/tracef.h>` where you need it, and link your application with
41 `liblttng-ust` and `liblttng-ust-common`. See the <<example,EXAMPLE>>
42 section below for a complete usage example.
44 Once your application is instrumented with `lttng_ust_tracef()` and/or
45 `lttng_ust_vtracef()` calls and ready to run, use
46 man:lttng-enable-event(1) to enable the `lttng_ust_tracef:*` event.
48 The `lttng_ust_tracef()` and `lttng_ust_vtracef()` events contain a
49 single field, named `msg`, which is the formatted string output.
51 If you need to attach a specific log level to a
52 `lttng_ust_tracef()`/`lttng_ust_vtracef()` call, use
53 man:lttng_ust_tracelog(3) and man:lttng_ust_vtracelog(3) instead.
55 See also the <<limitations,LIMITATIONS>> section below for important
56 limitations to consider when using `lttng_ust_tracef()` or
57 `lttng_ust_vtracef()`.
63 Here's a usage example of `lttng_ust_tracef()`:
65 -------------------------------------------------------------------
67 #include <lttng/tracef.h>
73 for (i = 0; i < 25; i++) {
74 lttng_ust_tracef("my message: %s, this integer: %d",
80 -------------------------------------------------------------------
82 This C source file, saved as `app.c`, can be compiled into a program
87 $ cc -o app app.c -llttng-ust -llttng-ust-common
90 You can create an LTTng tracing session, enable the `lttng_ust_tracef()`
91 events, and start the created tracing session like this:
95 $ lttng create my-session
96 $ lttng enable-event --userspace 'lttng_ust_tracef:*'
100 Next, start the program to be traced:
107 Finally, stop the tracing session, and inspect the recorded events:
119 :macro-suffix: tracef
121 include::tracef-tracelog-limitations.txt[]
124 include::common-footer.txt[]
126 include::common-copyrights.txt[]
128 include::common-authors.txt[]
133 man:lttng_ust_tracelog(3),
134 man:lttng_ust_vtracelog(3),