LTTNG_UST_TRACEF(3)

📦
version 2.16.0 · 9 versions
, in arch rolling

💅 LTTNG_UST_TRACEF(3) — the lttng_ust_tracef / lttng_ust_vtracef era

okay so bestie, this is a page from the LTTng Manual, and it's literally about the lttng_ust_tracef() and lttng_ust_vtracef() girlies — the printf(3)-like interface for tracing. no cap, it's giving "easy mode for user space tracing" ✨

🌸 NAME 🌸

lttng_ust_tracef, lttng_ust_vtracef — the LTTng-UST printf(3)-like interface, periodt 💅

🎀 SYNOPSIS 🎀

#include <lttng/tracef.h>

#define lttng_ust_tracef(fmt, ...)
#define lttng_ust_vtracef(fmt, ap)

Link with:

  • -llttng-ust
  • If you define _LGPL_SOURCE before including <lttng/tracef.h> (directly or indirectly): -llttng-ust-common
yes bestie, that second one is conditional — define _LGPL_SOURCE first or the -llttng-ust-common link line is not the vibe 🙈

🦋 DESCRIPTION 🦋

So the LTTng-UST lttng_ust_tracef() and lttng_ust_vtracef() API lets you trace your app with the help of simple printf(3)-like and vprintf(3)-like macros. iconic behavior honestly 💖

The fmt argument gets passed directly as the fmt parameter of vasprintf(3), and also:

  • For lttng_ust_tracef() — the optional parameters following fmt.
  • For lttng_ust_vtracef() — the ap parameter, as the ap parameter of vasprintf(3) (va_list type).

To use lttng_ust_tracef() or lttng_ust_vtracef(), include <lttng/tracef.h> wherever you need it, and link your application with liblttng-ust and liblttng-ust-common. there's a whole complete usage example down in the EXAMPLE section, iykyk 👀

Once your app is instrumented with lttng_ust_tracef() and/or lttng_ust_vtracef() calls and ready to run, use lttng-enable-event(1) to enable the lttng_ust_tracef:* event. slay ✨

The lttng_ust_tracef() and lttng_ust_vtracef() events contain a single field, named msg, which is the formatted string output. that's the whole field list, that's the girl 🎀

If you need to attach a specific log level to a lttng_ust_tracef()/lttng_ust_vtracef() call, use lttng_ust_tracelog(3) and lttng_ust_vtracelog(3) instead. different function, different vibe 💅

Also pls check the LIMITATIONS section below for important limitations to consider when using lttng_ust_tracef() or lttng_ust_vtracef() — no skipping, it's important 🫶

🌈 EXAMPLE 🌈

Here's a usage example of lttng_ust_tracef():

#include <stdlib.h>
#include <lttng/tracef.h>

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

and that's it, that's the whole ritual 🔥

💀 LIMITATIONS 💀

okay bestie, sit down for this one. 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. it's giving tradeoffs, fr fr:

  • All generated events have the same provider/event names. same name, every time 🫠
  • There's no static type checking. none. zero. 😭
  • 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. so no cute per-field filtering for you 💀
  • Since lttng_ust_tracef() and lttng_ust_vtracef() use C standard library's vasprintf(3) 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. slower, but honest 🌸
  • Generally, a string containing the textual representation of the user data fields is not as compact as binary fields in the resulting trace. bigger traces, more bytes, more storage, you get it 📦

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. read that again bestie. prototyping and debugging only — do not make it your permanent main character ⚠️

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. diy queen 🛠️

See lttng-ust(3) to learn more about custom tracepoint providers. those are the upgrade path, no cap ✨

🐛 BUGS 🐛

If you encounter any issue or usability problem, please report it on the LTTng bug tracker <https://bugs.lttng.org/projects/lttng-ust>. bestie please tell them, they wanna know 🙈

🍓 RESOURCES 🍓

like, the whole community is right there, go say hi 💜

👑 COPYRIGHTS 👑

This macro is part of the LTTng-UST project.

This macro is distributed under the GNU Lesser General Public License, version 2.1 <http://www.gnu.org/licenses/old-licenses/lgpl-2.1.en.html>. See the COPYING <https://github.com/lttng/lttng-ust/blob/v2.16/COPYING> file for more details. 📜

🧚 THANKS 🧚

Thanks to Ericsson for funding this work, providing real-life use cases, and testing. real ones 🫶

Special thanks to Michel Dagenais and the DORSAL laboratory <http://www.dorsal.polymtl.ca/> at École Polytechnique de Montréal for the LTTng journey. iconic collaboration, honestly 🌟

⭐ AUTHORS ⭐

LTTng-UST was originally written by Mathieu Desnoyers, with additional contributions from various other people. It is currently maintained by Mathieu Desnoyers <mailto:mathieu.desnoyers@efficios.com>. main character energy 👑

🌺 SEE ALSO 🌺

lttng_ust_tracelog(3), lttng_ust_vtracelog(3), lttng-ust(3), lttng(1), printf(3)

okay that's the whole page bestie, go trace something cute 💖

this lil drop is from LTTng 2.16.0, dated 08/31/2026 — and it's the LTTNG_UST_TRACEF(3) page, signing off 🎀✨🦋

📦 where this page comes from
  • arch rolling: lttng-ust 2.16.0-1 · LGPL-2.1-only AND MIT AND GPL-2.0-only AND BSD-3-Clause AND BSD-2-Clause AND GPL-3.0-or-later
  • 💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on : a language model's rewrite of the original, under its terms