X-Git-Url: https://git.lttng.org/?a=blobdiff_plain;f=doc%2Fman%2Flttng_ust_tracelog.3.txt;fp=doc%2Fman%2Flttng_ust_tracelog.3.txt;h=d0a315d15b770638d2a58b92e994f33cb1a99340;hb=5b1163c6cf674c6461cc1e0ad1211924df7af789;hp=0000000000000000000000000000000000000000;hpb=e436e84d48332d559fe60c1a5eba81f03e9f38f9;p=lttng-ust.git

diff --git a/doc/man/lttng_ust_tracelog.3.txt b/doc/man/lttng_ust_tracelog.3.txt
new file mode 100644
index 00000000..d0a315d1
--- /dev/null
+++ b/doc/man/lttng_ust_tracelog.3.txt
@@ -0,0 +1,185 @@
+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 -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)