X-Git-Url: http://git.lttng.org./?a=blobdiff_plain;f=doc%2Fman%2Ftracelog.3.txt;h=13284636fdc48ec8a512f4677bef5e0098957613;hb=fb24f1b61740fd3e8b1d87e2d89451ee404f32a5;hp=43ba934befc1ed79ac30a2b6d2bec1918459d1d9;hpb=0810c65b69a2b2f18d1c2f0e32c3d9ab92a49867;p=lttng-ust.git

diff --git a/doc/man/tracelog.3.txt b/doc/man/tracelog.3.txt
index 43ba934b..13284636 100644
--- a/doc/man/tracelog.3.txt
+++ b/doc/man/tracelog.3.txt
@@ -5,7 +5,7 @@ tracelog(3)
 
 NAME
 ----
-tracelog - LTTng-UST printf(3)-like interface with a log level
+tracelog, vtracelog - LTTng-UST printf(3)-like interface with a log level
 
 
 SYNOPSIS
@@ -15,132 +15,20 @@ SYNOPSIS
 
 [verse]
 #define *tracelog*('level', 'fmt', ...)
+#define *vtracelog*('level', 'fmt', 'ap')
 
-Link with `-llttng-ust`.
+Link with `-llttng-ust -llttng-ust-common`.
 
 
 DESCRIPTION
 -----------
-The LTTng-UST `tracelog()` API allows you to trace your application with
-the help of a simple man:printf(3)-like macro, with an additional
-parameter for the desired log level. The 'fmt' argument is passed
-directly to the 'fmt' parameter of man:vasprintf(3), as well as
-the optional parameters following 'fmt'.
+The `tracelog()` and `vtracelog()` macros are part of version{nbsp}0 of
+the LTTng-UST API (see the ``Compatibility with previous APIs'' section
+of man:lttng-ust(3)).
 
-The purpose of `tracelog()` is to ease the migration from logging to
-tracing.
-
-The available values for the 'level' parameter are:
-
-include::log-levels.txt[]
-
-To use `tracelog()`, include `<lttng/tracelog.h>` where you need it, and
-link your application with `liblttng-ust`. See the <<example,EXAMPLE>>
-section below for a complete usage example.
-
-Once your application is instrumented with `tracelog()` 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 `tracelog()` events contain the following fields:
-
-[options="header"]
-|===============================================================
-| Field name | Description
-| `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 man:tracef(3) instead.
-
-See also the <<limitations,LIMITATIONS>> section below for important
-limitations to consider when using `tracelog()`.
-
-
-[[example]]
-EXAMPLE
--------
-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:
-
-[role="term"]
----------------------------
-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:
-
-[role="term"]
----------------------------------------------------
-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 level:
-
-[role="term"]
--------------------------------------------------------
-lttng enable-event --userspace 'lttng_ust_tracelog:*' \
-                   --loglevel=TRACE_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-name: tracelog
-
-include::tracef-tracelog-limitations.txt[]
+Prefer using man:lttng_ust_tracelog(3) and man:lttng_ust_vtracelog(3)
+which are part of version{nbsp}1 of the API and have the `lttng_ust_`
+namespace.
 
 
 include::common-footer.txt[]
@@ -152,7 +40,5 @@ include::common-authors.txt[]
 
 SEE ALSO
 --------
-man:tracef(3),
-man:lttng-ust(3),
-man:lttng(1),
-man:printf(3)
+man:lttng_ust_tracelog(3),
+man:lttng_ust_vtracelog(3)