---
name: "lttng_ust_vtracelog"
section: "3"
platform: "linux"
package: "liblttng-ust-dev"
version: "2.13.9-1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/lttng_ust_tracelog"
---

# lttng\_ust\_vtracelog(3)

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

Part of [lttng\_ust\_tracelog(3)](/lttng_ust_tracelog/3.md).

## NAME

lttng\_ust\_tracelog, lttng\_ust\_vtracelog - LTTng-UST [printf(3)](/printf/3.md)-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:

• **-llttng-ust**

• If you define **\_LGPL\_SOURCE** before including **\<lttng/tracelog.h\>** (directly or indirectly): **-llttng-ust-common**

## 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)](/printf/3.md)-like and [**vprintf**(3)](/vprintf/3.md)-like macros, with an additional parameter for the desired log level.

The *fmt* argument is passed directly as the *fmt* parameter of [**vasprintf**(3)](/vasprintf/3.md), 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)](/vasprintf/3.md) (**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)](/lttng-enable-event/1.md) 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 name** | **Description** |
| **line** | Line in source file where **lttng\_ust\_tracelog()** was called. |
| **file** | Source file from which **lttng\_ust\_tracelog()** was called. |
| **func** | Function name from which **lttng\_ust\_tracelog()** was called. |
| **msg** | Formatted 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)](/lttng_ust_tracef/3.md) 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:

• 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\_tracelog()** and **lttng\_ust\_vtracelog()** use C standard library’s [**vasprintf**(3)](/vasprintf/3.md) 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\_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)](/lttng-ust/3.md) 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 **COPYING** \<https://github.com/lttng/lttng-ust/blob/v2.13/COPYING\> file 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_tracef/3.md), [**lttng\_ust\_vtracef**(3)](/lttng_ust_vtracef/3.md), [**lttng-ust**(3)](/lttng-ust/3.md), [**lttng**(1)](/lttng/1.md), [**printf**(3)](/printf/3.md)