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:

       •   -llttng-ust

       •   If you define _LGPL_SOURCE before including <lttng/tracef.h> (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)-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().

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:

       •   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.

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

       •   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

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)