--- name: "lttng_ust_tracef" section: "3" platform: "linux" package: "lttng-ust" version: "2.16.0-1" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/lttng_ust_tracef" --- # lttng\_ust\_tracef(3) LTTng-UST printf(3)-like interface ## NAME lttng\_ust\_tracef, lttng\_ust\_vtracef - LTTng-UST [printf(3)](/printf/3.md)-like interface ## SYNOPSIS ``` #include ``` ``` #define lttng_ust_tracef(fmt, ...) #define lttng_ust_vtracef(fmt, ap) ``` Link with: • **-llttng-ust** • If you define **\_LGPL\_SOURCE** before including **\** (directly or indirectly): **-llttng-ust-common** ## DESCRIPTION The LTTng-UST **lttng\_ust\_tracef()** and **lttng\_ust\_vtracef()** API allows you to trace your application with the help of simple [**printf**(3)](/printf/3.md)-like and [**vprintf**(3)](/vprintf/3.md)-like macros. The *fmt* argument is passed directly as the *fmt* parameter of [**vasprintf**(3)](/vasprintf/3.md), as well as: For **lttng\_ust\_tracef()** The optional parameters following *fmt*. For **lttng\_ust\_vtracef()** The *ap* parameter as the *ap* parameter of [**vasprintf**(3)](/vasprintf/3.md) (**va\_list** type). To use **lttng\_ust\_tracef()** or **lttng\_ust\_vtracef()**, include **\** where you need it, and link your application with **liblttng-ust** and **liblttng-ust-common**. See the *EXAMPLE* section below for a complete usage example. Once your application is instrumented with **lttng\_ust\_tracef()** and/or **lttng\_ust\_vtracef()** calls and ready to run, use [**lttng-enable-event**(1)](/lttng-enable-event/1.md) to enable the **lttng\_ust\_tracef:\*** event. The **lttng\_ust\_tracef()** and **lttng\_ust\_vtracef()** events contain a single field, named **msg**, which is the formatted string output. If you need to attach a specific log level to a **lttng\_ust\_tracef()**/**lttng\_ust\_vtracef()** call, use [**lttng\_ust\_tracelog**(3)](/lttng_ust_tracelog/3.md) and [**lttng\_ust\_vtracelog**(3)](/lttng_ust_vtracelog/3.md) instead. See also the *LIMITATIONS* section below for important limitations to consider when using **lttng\_ust\_tracef()** or **lttng\_ust\_vtracef()**. ## EXAMPLE Here’s a usage example of **lttng\_ust\_tracef()**: ``` #include #include int main(void) { int i; for (i = 0; i < 25; i++) { lttng_ust_tracef("my message: %s, this integer: %d", "a message", i); } return EXIT_SUCCESS; } ``` This C source file, saved as **app.c**, can be compiled into a program like this: ``` $ cc -o app app.c -llttng-ust -llttng-ust-common ``` You can create an LTTng tracing session, enable the **lttng\_ust\_tracef()** events, and start the created tracing session like this: ``` $ lttng create my-session $ lttng enable-event --userspace 'lttng_ust_tracef:*' $ lttng start ``` Next, start the program to be traced: ``` $ ./app ``` Finally, stop the tracing session, and inspect the recorded events: ``` $ lttng stop $ lttng view ``` ## LIMITATIONS The **lttng\_ust\_tracef()** and **lttng\_ust\_vtracef()** utility macros were developed to make user space tracing super simple, albeit with notable disadvantages compared to custom, full-fledged tracepoint providers: • All generated events have the same provider/event names. • There’s no static type checking. • The only event field with user data you actually get, named **msg**, is a string potentially containing the values you passed to the macro using your own format. This also means that you cannot use filtering using a custom expression at run time because there are no isolated fields. • Since **lttng\_ust\_tracef()** and **lttng\_ust\_vtracef()** use C standard library’s [**vasprintf**(3)](/vasprintf/3.md) function in the background to format the strings at run time, their expected performance is lower than using custom tracepoint providers with typed fields, which do not require a conversion to a string. • Generally, a string containing the textual representation of the user data fields is not as compact as binary fields in the resulting trace. Thus, **lttng\_ust\_tracef()**/**lttng\_ust\_vtracef()** are useful for quick prototyping and debugging, but should not be considered for any permanent/serious application instrumentation. **lttng\_ust\_vtracef()** does not have a **STAP\_PROBEV()** call, because **STAP\_PROBEV()** does not support **va\_list**. If you need it, you should emit this call yourself. See [**lttng-ust**(3)](/lttng-ust/3.md) to learn more about custom tracepoint providers. ## BUGS If you encounter any issue or usability problem, please report it on the LTTng bug tracker \. ## RESOURCES • LTTng project website \ • LTTng documentation \ • Git repositories \ • GitHub organization \ • Continuous integration \ • Mailing list \ for support and development: **lttng-dev@lists.lttng.org** • IRC channel \: **#lttng** on **irc.oftc.net** ## COPYRIGHTS This macro is part of the LTTng-UST project. This macro is distributed under the GNU Lesser General Public License, version 2.1 \. See the **COPYING** \ file for more details. ## THANKS Thanks to Ericsson for funding this work, providing real-life use cases, and testing. Special thanks to Michel Dagenais and the DORSAL laboratory \ at École Polytechnique de Montréal for the LTTng journey. ## AUTHORS LTTng-UST was originally written by Mathieu Desnoyers, with additional contributions from various other people. It is currently maintained by Mathieu Desnoyers \. ## SEE ALSO [**lttng\_ust\_tracelog**(3)](/lttng_ust_tracelog/3.md), [**lttng\_ust\_vtracelog**(3)](/lttng_ust_vtracelog/3.md), [**lttng-ust**(3)](/lttng-ust/3.md), [**lttng**(1)](/lttng/1.md), [**printf**(3)](/printf/3.md)