doc/man: only mention `-llttng-ust-common` in synopses (conditionally)

[lttng-ust.git] / doc / man / lttng_ust_tracelog.3.txt

lttng_ust_tracelog(3)
=====================
:object-type: macro


NAME
----
lttng_ust_tracelog, lttng_ust_vtracelog - LTTng-UST printf(3)-like interface with a log level


SYNOPSIS
--------
[verse]
*#include <lttng/tracelog.h>*

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

The 'fmt' argument is passed directly as the 'fmt' parameter of
man: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 man: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:

include::log-levels.txt[]

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,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
man:lttng-enable-event(1) to enable the `lttng_ust_tracelog:*` event.
You can isolate specific log levels with the nloption:--loglevel and
nloption:--loglevel-only options of this command.

The `lttng_ust_tracelog()` and `lttng_ust_vtracelog()` events contain
the following fields:

[options="header"]
|===
|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
man:lttng_ust_tracef(3) instead.

See also the <<limitations,LIMITATIONS>> section below for important
limitations to consider when using `lttng_ust_tracelog()` or
`lttng_ust_vtracelog()`.


[[example]]
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:

[role="term"]
----
$ 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:

[role="term"]
----
$ 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:

[role="term"]
----
$ lttng enable-event --userspace 'lttng_ust_tracelog:*' \
                     --loglevel=INFO
----

Next, start the program to be traced:

[role="term"]
----
$ ./app a few arguments passed to this application
----

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

[role="term"]
----
$ lttng stop
$ lttng view
----


[[limitations]]
LIMITATIONS
-----------
:macro-suffix: tracelog

include::tracef-tracelog-limitations.txt[]


include::common-footer.txt[]

include::common-copyrights.txt[]

include::common-authors.txt[]


SEE ALSO
--------
man:lttng_ust_tracef(3),
man:lttng_ust_vtracef(3),
man:lttng-ust(3),
man:lttng(1),
man:printf(3)