|
HTML rendering created 2025-09-06 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|
|
NAME | SYNOPSIS | DESCRIPTION | EXAMPLE | LIMITATIONS | BUGS | RESOURCES | COPYRIGHTS | THANKS | AUTHORS | SEE ALSO | COLOPHON |
|
|
|
LTTNG_UST_TRACEF(3) LTTng Manual LTTNG_UST_TRACEF(3)
lttng_ust_tracef, lttng_ust_vtracef - LTTng-UST printf(3)-like
interface
#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
The LTTng-UST lttng_ust_tracef() and lttng_ust_vtracef() API
allows you to trace your application with the help of simple
printf(3)-like and vprintf(3)-like macros.
The fmt argument is passed directly as the fmt parameter of
vasprintf(3), 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) (va_list
type).
To use lttng_ust_tracef() or lttng_ust_vtracef(), include
<lttng/tracef.h> 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) 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) and lttng_ust_vtracelog(3) instead.
See also the LIMITATIONS section below for important limitations
to consider when using lttng_ust_tracef() or lttng_ust_vtracef().
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
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) 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) to learn more about custom tracepoint providers.
If you encounter any issue or usability problem, please report it
on the LTTng bug tracker <https://bugs.lttng.org/projects/lttng-
ust>.
• LTTng project website <http://lttng.org>
• LTTng documentation <http://lttng.org/docs>
• Git repositories <http://git.lttng.org>
• GitHub organization <http://github.com/lttng>
• Continuous integration <http://ci.lttng.org/>
• Mailing list <http://lists.lttng.org> for support and
development: lttng-dev@lists.lttng.org
• IRC channel <irc://irc.oftc.net/lttng>: #lttng on irc.oftc.net
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.14/COPYING> file for
more details.
Thanks to Ericsson for funding this work, providing real-life use
cases, and testing.
Special thanks to Michel Dagenais and the DORSAL laboratory
<http://www.dorsal.polymtl.ca/> at École Polytechnique de Montréal
for the LTTng journey.
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>.
lttng_ust_tracelog(3), lttng_ust_vtracelog(3), lttng-ust(3),
lttng(1), printf(3)
This page is part of the LTTng-UST (LTTng Userspace Tracer)
project. Information about the project can be found at
⟨http://lttng.org/⟩. It is not known how to report bugs for this
man page; if you know, please send a mail to man-pages@man7.org.
This page was obtained from the tarball fetched from
⟨https://lttng.org/files/lttng-ust/⟩ on 2025-08-11. If you
discover any rendering problems in this HTML version of the page,
or you believe there is a better or more up-to-date source for the
page, or you have corrections or improvements to the information
in this COLOPHON (which is not part of the original manual page),
send a mail to man-pages@man7.org
LTTng 2.14.0-pre 06/07/2024 LTTNG_UST_TRACEF(3)
Pages that refer to this page: lttng-ust(3), lttng_ust_tracelog(3), tracef(3)
|
HTML rendering created 2025-09-06 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|