lttng_ust_tracelog - Man Page

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

Synopsis

#include <lttng/tracelog.h>
#define lttng_ust_tracelog(level, fmt, ...)
#define lttng_ust_vtracelog(level, fmt, ap)

Link with:

Description

The LTTng-UST lttng_ust_tracelog() and lttng_ust_vtracelog() API allows you to trace your application with the help of simple printf(3)-like and vprintf(3)-like macros, with an additional parameter for the desired log level.

The fmt argument is passed directly as the fmt parameter of vasprintf(3), as well as:

For lttng_ust_tracelog()

The optional parameters following fmt.

For lttng_ust_vtracelog()

The ap parameter as the ap parameter of vasprintf(3) (va_list type).

The purpose of lttng_ust_tracelog() and lttng_ust_vtracelog() is to ease the migration from logging to tracing.

The available values for the level parameter are:

LTTNG_UST_TRACEPOINT_LOGLEVEL_EMERG

System is unusable.

LTTNG_UST_TRACEPOINT_LOGLEVEL_ALERT

Action must be taken immediately.

LTTNG_UST_TRACEPOINT_LOGLEVEL_CRIT

Critical conditions.

LTTNG_UST_TRACEPOINT_LOGLEVEL_ERR

Error conditions.

LTTNG_UST_TRACEPOINT_LOGLEVEL_WARNING

Warning conditions.

LTTNG_UST_TRACEPOINT_LOGLEVEL_NOTICE

Normal, but significant, condition.

LTTNG_UST_TRACEPOINT_LOGLEVEL_INFO

Informational message.

LTTNG_UST_TRACEPOINT_LOGLEVEL_DEBUG_SYSTEM

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

LTTNG_UST_TRACEPOINT_LOGLEVEL_DEBUG_PROGRAM

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

LTTNG_UST_TRACEPOINT_LOGLEVEL_DEBUG_PROCESS

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

LTTNG_UST_TRACEPOINT_LOGLEVEL_DEBUG_MODULE

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

LTTNG_UST_TRACEPOINT_LOGLEVEL_DEBUG_UNIT

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

LTTNG_UST_TRACEPOINT_LOGLEVEL_DEBUG_FUNCTION

Debug information with function-level scope.

LTTNG_UST_TRACEPOINT_LOGLEVEL_DEBUG_LINE

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

LTTNG_UST_TRACEPOINT_LOGLEVEL_DEBUG

Debug-level message.

To use lttng_ust_tracelog() or lttng_ust_vtracelog(), include <lttng/tracelog.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_tracelog() and/or lttng_ust_vtracelog() 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 lttng_ust_tracelog() and lttng_ust_vtracelog() events contain the following fields:

Field nameDescription
lineLine in source file where lttng_ust_tracelog() was called.
fileSource file from which lttng_ust_tracelog() was called.
funcFunction name from which lttng_ust_tracelog() was called.
msgFormatted string output.

If you do not need to attach a specific log level to a lttng_ust_tracelog()/lttng_ust_vtracelog() call, use lttng_ust_tracef(3) instead.

See also the Limitations section below for important limitations to consider when using lttng_ust_tracelog() or lttng_ust_vtracelog().

Example

Here’s a usage example of lttng_ust_tracelog():

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

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

    if (argc < 2) {
        lttng_ust_tracelog(LTTNG_UST_TRACEPOINT_LOGLEVEL_CRIT,
                           "Not enough arguments: %d", argc);
        return EXIT_FAILURE;
    }

    lttng_ust_tracelog(LTTNG_UST_TRACEPOINT_LOGLEVEL_INFO,
                       "Starting app with %d arguments", argc);

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

    lttng_ust_tracelog(LTTNG_UST_TRACEPOINT_LOGLEVEL_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 -llttng-ust-common

You can create an LTTng tracing session, enable all the lttng_ust_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 lttng_ust_tracelog() events matching a log level at least as severe as a given log level:

$ lttng enable-event --userspace 'lttng_ust_tracelog:*' \
                     --loglevel=INFO

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

Limitations

The lttng_ust_tracelog() and lttng_ust_vtracelog() 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_tracelog()/lttng_ust_vtracelog() are useful for quick prototyping and debugging, but should not be considered for any permanent/serious application instrumentation.

lttng_ust_vtracelog() 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_tracef(3), lttng_ust_vtracef(3), lttng-ust(3), lttng(1), printf(3)

Referenced By

lttng-ust(3), lttng_ust_tracef(3), tracelog(3).

The man page lttng_ust_vtracelog(3) is an alias of lttng_ust_tracelog(3).

06/03/2022 LTTng 2.13.3 LTTng Manual