Provided by: liblttng-ust-dev_2.11.0-1_amd64 bug


       tracelog - LTTng-UST printf(3)-like interface with a log level


       #include <lttng/tracelog.h>

       #define tracelog(level, fmt, ...)

       Link with -llttng-ust.


       The LTTng-UST tracelog() API allows you to trace your application with the help of a
       simple printf(3)-like macro, with an additional parameter for the desired log level. The
       fmt argument is passed directly to the fmt parameter of vasprintf(3), as well as the
       optional parameters following fmt.

       The purpose of tracelog() is to ease the migration from logging to tracing.

       The available values for the level parameter are:

           System is unusable.

           Action must be taken immediately.

           Critical conditions.

           Error conditions.

           Warning conditions.

           Normal, but significant, condition.

           Informational message.

           Debug information with system-level scope (set of programs).

           Debug information with program-level scope (set of processes).

           Debug information with process-level scope (set of modules).

           Debug information with module (executable/library) scope (set of units).

           Debug information with compilation unit scope (set of functions).

           Debug information with function-level scope.

           Debug information with line-level scope (default log level).

           Debug-level message.

       To use tracelog(), include <lttng/tracelog.h> where you need it, and link your application
       with liblttng-ust. See the EXAMPLE section below for a complete usage example.

       Once your application is instrumented with tracelog() calls and ready to run, use lttng-
       enable-event(1) to enable the lttng_ust_tracelog:* event. You can isolate specific log
       levels with the --loglevel and --loglevel-only options of this command.

       The tracelog() events contain the following fields:

       │Field nameDescription               │
       │           │                           │
       │line       │ Line in source file where │
       │           │ tracelog() was called.    │
       │           │                           │
       │file       │ Source file from which    │
       │           │ tracelog() was called.    │
       │           │                           │
       │func       │ Function name from which  │
       │           │ tracelog() was called.    │
       │           │                           │
       │msg        │ Formatted string output.  │

       If you do not need to attach a specific log level to a tracelog() call, use tracef(3)

       See also the LIMITATIONS section below for important limitations to consider when using


       Here’s a usage example of tracelog():

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

           int main(int argc, char *argv[])
               int i;

               if (argc < 2) {
                   tracelog(TRACE_CRIT, "Not enough arguments: %d", argc);
                   return EXIT_FAILURE;

               tracelog(TRACE_INFO, "Starting app with %d arguments", argc);

               for (i = 0; i < argc; i++) {
                   tracelog(TRACE_DEBUG, "Argument %d: %s", i, argv[i]);

               tracelog(TRACE_INFO, "Exiting app");

               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

       You can create an LTTng tracing session, enable all the tracelog() events, and start the
       created tracing session like this:

           $ lttng create my-session
           $ lttng enable-event --userspace 'lttng_ust_tracelog:*'
           $ lttng start

       Or you can enable tracelog() events matching a log level at least as severe as a given log

           $ lttng enable-event --userspace 'lttng_ust_tracelog:*' \

       Next, start the program to be traced:

           $ ./app a few arguments passed to this application

       Finally, stop the tracing session, and inspect the recorded events:

           $ lttng stop
           $ lttng view


       The tracelog() utility macro was 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 tracelog() uses C standard library’s vasprintf(3) function in the background to
           format the strings at run time, its 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, tracelog() is useful for quick prototyping and debugging, but should not be
       considered for any permanent/serious application instrumentation.

       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


       ·   LTTng project website <>

       ·   LTTng documentation <>

       ·   Git repositories <>

       ·   GitHub organization <>

       ·   Continuous integration <>

       ·   Mailing list <> for support and development: lttng-

       ·   IRC channel <irc://>: #lttng on


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


       LTTng-UST was originally written by Mathieu Desnoyers, with additional contributions from
       various other people. It is currently maintained by Mathieu Desnoyers


       tracef(3), lttng-ust(3), lttng(1), printf(3)