1TRACEF(3)                        LTTng Manual                        TRACEF(3)
2
3
4

NAME

6       tracef - LTTng-UST printf(3)-like interface
7

SYNOPSIS

9       #include <lttng/tracef.h>
10
11       #define tracef(fmt, ...)
12
13       Link with -llttng-ust.
14

DESCRIPTION

16       The LTTng-UST tracef() API allows you to trace your application with
17       the help of a simple printf(3)-like macro. The fmt argument is passed
18       directly to the fmt parameter of vasprintf(3), as well as the optional
19       parameters following fmt.
20
21       To use tracef(), include <lttng/tracef.h> where you need it, and link
22       your application with liblttng-ust. See the EXAMPLE section below for a
23       complete usage example.
24
25       Once your application is instrumented with tracef() calls and ready to
26       run, use lttng-enable-event(1) to enable the lttng_ust_tracef:* event.
27
28       The tracef() events contain a single field, named msg, which is the
29       formatted string output.
30
31       If you need to attach a specific log level to a tracef() call, use
32       tracelog(3) instead.
33
34       See also the LIMITATIONS section below for important limitations to
35       consider when using tracef().
36

EXAMPLE

38       Here’s a usage example of tracef():
39
40           #include <stdlib.h>
41           #include <lttng/tracef.h>
42
43           int main(void)
44           {
45               int i;
46
47               for (i = 0; i < 25; i++) {
48                   tracef("my message: %s, this integer: %d", "a message", i);
49               }
50
51               return EXIT_SUCCESS;
52           }
53
54       This C source file, saved as app.c, can be compiled into a program like
55       this:
56
57           $ cc -o app app.c -llttng-ust
58
59       You can create an LTTng tracing session, enable the tracef() events,
60       and start the created tracing session like this:
61
62           $ lttng create my-session
63           $ lttng enable-event --userspace 'lttng_ust_tracef:*'
64           $ lttng start
65
66       Next, start the program to be traced:
67
68           $ ./app
69
70       Finally, stop the tracing session, and inspect the recorded events:
71
72           $ lttng stop
73           $ lttng view
74

LIMITATIONS

76       The tracef() utility macro was developed to make user space tracing
77       super simple, albeit with notable disadvantages compared to custom,
78       full-fledged tracepoint providers:
79
80       ·   All generated events have the same provider/event names.
81
82       ·   There’s no static type checking.
83
84       ·   The only event field with user data you actually get, named msg, is
85           a string potentially containing the values you passed to the macro
86           using your own format. This also means that you cannot use
87           filtering using a custom expression at run