Add tracelog documentation to lttng-ust(3)

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

diff --git a/doc/man/lttng-ust.3 b/doc/man/lttng-ust.3
index 55de9fd2d88cea5de0cd1fa04f6eba46c4371efd..f57d7f880926fe6481248a16b731e5ad0d5cc28d 100644 (file)
--- a/doc/man/lttng-ust.3
+++ b/doc/man/lttng-ust.3
@@ -17,7 +17,72 @@ port of the low-overhead tracing capabilities of the LTTng kernel tracer
 to user-space. The library "liblttng-ust" enables tracing of
 applications and libraries.
 
 to user-space. The library "liblttng-ust" enables tracing of
 applications and libraries.
 

-.SH "USAGE"
+.SH "USAGE WITH TRACEF"
+.PP
+The simplest way to add instrumentation to your code is by far the
+tracef() API. To do it, in a nutshell:
+
+1) #include <lttng/tracef.h>
+
+2) /* in your code, use like a printf */
+   tracef("my message, this integer %d", 1234);
+
+3) Link your program against liblttng-ust.so.
+
+4) Enable UST events when tracing with the following sequence of commands
+   from lttng-tools:
+
+   lttng create
+   lttng enable-event -u -a
+   lttng start
+   [... run your program ...]
+   lttng stop
+   lttng view
+
+That's it!
+
+If you want to have more flexibility and control on the event names,
+payload typing, etc, you can continue reading on and use the tracepoints
+below. "tracef()" is there for quick and dirty ad hoc instrumentation,
+whereas tracepoint.h is meant for thorough instrumentation of a code
+base to be integrated with an upstream project.
+.PP
+
+.SH "USAGE WITH TRACELOG"
+.PP
+If you want to migrate existing logging (info, errors, ...)
+to LTTng UST, you can use the tracelog() interface.
+To do it, in a nutshell:
+
+1) #include <lttng/tracelog.h>
+
+2) /* in your code, use like a printf, with extra loglevel info. */
+   tracelog(info, "Message with integer %d", 1234);
+
+3) Link your program against liblttng-ust.so.
+
+4) Enable UST events when tracing with the following sequence of commands
+   from lttng-tools:
+
+   lttng create
+   lttng enable-event -u "lttng_ust_tracelog:*"
+   lttng start
+   [... run your program ...]
+   lttng stop
+   lttng view
+
+That's it!
+
+You can replace the enable-event line above with a selection of
+loglevels, e.g.:
+
+   lttng enable-event -u -a --loglevel INFO
+
+Which will gather all events from INFO and more important loglevels.
+
+.PP
+
+.SH "USAGE WITH TRACEPOINT"

 .PP
 The simple way to generate the lttng-ust tracepoint probes is to use the
 lttng-gen-tp(1) tool. See the lttng-gen-tp(1) manpage for explanation.
 .PP
 The simple way to generate the lttng-ust tracepoint probes is to use the
 lttng-gen-tp(1) tool. See the lttng-gen-tp(1) manpage for explanation.


@@ -61,11 +126,11 @@ TRACEPOINT_EVENT(
        sample_component,
 
        /*
        sample_component,
 
        /*

-        * tracepoint name, same format as sample provider. Does not
-        * need to be declared before. in this case the name is
-        * "message"
+        * tracepoint name, characters permitted follow the same
+        * constraints as the provider name. The name of this example
+        * event is "sample_event".

         */
         */

-       message,
+       sample_event,

 
        /*
         * TP_ARGS macro contains the arguments passed for the tracepoint
 
        /*
         * TP_ARGS macro contains the arguments passed for the tracepoint


@@ -234,7 +299,7 @@ debug information.
    debug information with line-level scope (TRACEPOINT_EVENT default)
 
    TRACE_DEBUG           14
    debug information with line-level scope (TRACEPOINT_EVENT default)
 
    TRACE_DEBUG           14

-   debug-level message (trace_printf default)
+   debug-level message

 
 See lttng(1) for information on how to use LTTng-UST loglevels.
 
 
 See lttng(1) for information on how to use LTTng-UST loglevels.
 


@@ -259,6 +324,33 @@ Even though LTTng-UST supports tracepoint() call site duplicates having
 the same provider and event name, it is recommended to use a
 provider event name pair only once within the source code to help
 map events back to their call sites when analyzing the trace.
 the same provider and event name, it is recommended to use a
 provider event name pair only once within the source code to help
 map events back to their call sites when analyzing the trace.

+
+Sometimes arguments to the probe are expensive to compute (e.g.
+take call stack). To avoid the computation when the tracepoint is
+disabled one can use more 'low level' tracepoint_enabled() and
+do_tracepoint() macros as following:
+
+       if (tracepoint_enabled(ust_tests_hello, tptest)) {
+               /* prepare arguments */
+               do_tracepoint(ust_tests_hello, tptest, i, netint, values,
+                       text, strlen(text), dbl, flt);
+       }
+
+Here do_tracepoint() doesn't contain check if the tracepoint is enabled.
+Using tracepoint() in such scenario is dangerous since it also contains
+enabled check and thus race condition is possible in the following code
+if the tracepoint has been enabled after check in tracepoint_enabled()
+but before tracepoint():
+
+       if (tracepoint_enabled(provider, name)) { /* tracepoint is disabled */
+               prepare(args);
+       }
+       /* tracepoint is enabled by 'lttng' tool */
+       tracepoint(provider, name, args); /* args wasn't prepared properly */
+
+Note also that neither tracepoint_enabled() nor do_tracepoint() have
+STAP_PROBEV() call so if you need it you should emit this call yourself.
+

 .fi
 
 .SH "BUILDING/LINKING THE TRACEPOINT PROVIDER"
 .fi
 
 .SH "BUILDING/LINKING THE TRACEPOINT PROVIDER"


@@ -268,17 +360,13 @@ There are 2 ways to compile the Tracepoint Provider with the
 application: either statically or dynamically. Please follow
 carefully:
 
 application: either statically or dynamically. Please follow
 carefully:
 

-  1.1) Compile the Tracepoint provider with the application, either
-       directly or through a static library (.a):
-    - Into exactly one object of your application: define
+  1) Compile the Tracepoint Provider with the application, either
+     directly or through a static library (.a):
+    - Into exactly one object of your application, define

       "TRACEPOINT_DEFINE" and include the tracepoint provider.
     - Use "\-I." for the compilation unit containing the tracepoint
       "TRACEPOINT_DEFINE" and include the tracepoint provider.
     - Use "\-I." for the compilation unit containing the tracepoint

-      provider include (e.g. tp.c).
-    - Link application with "\-ldl".
-    - If building the provider directly into the application,
-      link the application with "\-llttng-ust".
-    - If building a static library for the provider, link the static
-      library with "\-llttng-ust".
+      provider include (e.g., tp.c).
+    - Link the application with "\-llttng-ust" and "\-ldl".

     - Include the tracepoint provider header into all C files using
       the provider.
     - Examples:
     - Include the tracepoint provider header into all C files using
       the provider.
     - Examples:


@@ -377,22 +465,23 @@ needs to be enabled:
 .IP "ust_baddr_statedump:soinfo"
 This event is used to trace a currently loaded shared object. The base address
 (where the dynamic linker has placed the shared object) is recorded in the
 .IP "ust_baddr_statedump:soinfo"
 This event is used to trace a currently loaded shared object. The base address
 (where the dynamic linker has placed the shared object) is recorded in the

-baddr-field. The path to the shared object gets recorded in the sopath-field
-(as string). The file size of the loaded object (in bytes) is recorded to the
-size-field and its time of last modification (in seconds since Epoch) is
-recorded in the mtime-field.
-.PP
-If the event above is enabled, a series of ust_baddr_statedump:soinfo events is
-recorded at session-enable time, that represents the state of currently loaded
-shared objects (of the traced application). If this information gets combined
-with the lttng-ust-dl(3) instrumentation, all aspects of dynamic loading that
-are relevant for symbol and linenumber-lookup are traced by LTTng.
+"baddr" field. The path to the shared object gets recorded in the
+"sopath" field (as string). The file size of the loaded object (in
+bytes) is recorded to the "size" field and its time of last modification
+(in seconds since Epoch) is recorded in the "mtime" field.
+.PP
+If the event above is enabled, a series of "ust_baddr_statedump:soinfo"
+events is recorded at session-enable time. It represents the state of
+currently loaded shared objects for the traced process. If this
+information gets combined with the lttng-ust-dl(3) instrumentation, all
+aspects of dynamic loading that are relevant for symbol and
+line number lookup are traced by LTTng.

 .PP
 .SH "ENVIRONMENT VARIABLES"
 
 .PP
 .IP "LTTNG_UST_DEBUG"
 .PP
 .SH "ENVIRONMENT VARIABLES"
 
 .PP
 .IP "LTTNG_UST_DEBUG"

-Activate liblttng-ust debug output.
+Activate liblttng-ust debug and error output.

 .PP
 .IP "LTTNG_UST_REGISTER_TIMEOUT"
 The environment variable "LTTNG_UST_REGISTER_TIMEOUT" can be used to
 .PP
 .IP "LTTNG_UST_REGISTER_TIMEOUT"
 The environment variable "LTTNG_UST_REGISTER_TIMEOUT" can be used to