NAME

lttng_ust_tracef, lttng_ust_vtracef - LTTng-UST printf(3)-like interface

SYNOPSIS

#include <lttng/tracef.h>

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

Link with:

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)-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()

For lttng_ust_vtracef()

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().

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

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:

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.

BUGS

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

RESOURCES

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 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 <http://www.dorsal.polymtl.ca/> 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 <mailto:mathieu.desnoyers@efficios.com>.

SEE ALSO

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