Add CTF enum type support to tracepoint event

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

diff --git a/doc/man/lttng-ust.3 b/doc/man/lttng-ust.3
index 591c1db014eef7acf3f8d4b1f11cf14adc1772f0..0455eea2810e2178dfe7c244eeeb6800d46e6106 100644 (file)
--- a/doc/man/lttng-ust.3
+++ b/doc/man/lttng-ust.3
@@ -20,7 +20,7 @@ applications and libraries.
 .SH "USAGE WITH TRACEF"
 .PP
 The simplest way to add instrumentation to your code is by far the
 .SH "USAGE WITH TRACEF"
 .PP
 The simplest way to add instrumentation to your code is by far the

-tracef() API. To you it, in a nutshell:
+tracef() API. To do it, in a nutshell:

 
 1) #include <lttng/tracef.h>
 
 
 1) #include <lttng/tracef.h>
 


@@ -29,12 +29,15 @@ tracef() API. To you it, in a nutshell:
 
 3) Link your program against liblttng-ust.so.
 
 
 3) Link your program against liblttng-ust.so.
 

-4) Enable the UST event "lttng_ust_tracef:event" when tracing with the
-   following sequence of commands from lttng-tools:
+4) Enable UST events when tracing with the following sequence of commands
+   from lttng-tools:

 
 

-   lttng create; lttng enable-event -u "lttng_ust_tracef:event"; lttng start
+   lttng create
+   lttng enable-event -u -a
+   lttng start

    [... run your program ...]
    [... run your program ...]

-   lttng stop; lttng view
+   lttng stop
+   lttng view

 
 That's it!
 
 
 That's it!
 


@@ -45,6 +48,41 @@ whereas tracepoint.h is meant for thorough instrumentation of a code
 base to be integrated with an upstream project.
 .PP
 
 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(TRACE_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 TRACE_INFO
+
+Which will gather all events from TRACE_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
 .SH "USAGE WITH TRACEPOINT"
 .PP
 The simple way to generate the lttng-ust tracepoint probes is to use the


@@ -89,11 +127,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


@@ -186,6 +224,17 @@ TRACEPOINT_EVENT(
                 */
                ctf_float(float, floatfield, floatarg)
                ctf_float(double, doublefield, doublearg)
                 */
                ctf_float(float, floatfield, floatarg)
                ctf_float(double, doublefield, doublearg)

+
+               /*
+                * ctf_enum: a field using a previously declared
+                * enumeration args: (provider, enum name, container
+                * type, field name, argument expression). The
+                * enumeration itself and its values must have been
+                * defined previously with the TRACEPOINT_ENUM macro,
+                * described below.
+                */
+               ctf_enum(sample_component, enumeration_name, int,
+                             enumfield, enumarg)

        )
 )
 
        )
 )
 


@@ -193,6 +242,49 @@ There can be an arbitrary number of tracepoint providers within an
 application, but they must each have their own provider name. Duplicate
 provider names are not allowed.
 
 application, but they must each have their own provider name. Duplicate
 provider names are not allowed.
 

+The CTF specification also supports enumerations that can be declared
+inside a tracepoint provider and used as fields in the tracepoint. This
+shows how to specify enumerations and what they can be used for:
+
+The enumeration is a mapping between an integer, or a range of integers, and a
+string. It can be used to have a more compact trace in cases where the possible
+values for a field are limited:
+
+TRACEPOINT_ENUM(
+       /*
+        * The provider name, as described in the TRACEPOINT_EVENT macro.
+        */
+       sample_component,
+
+       /*
+        * The name of this enumeration, that will be used when using this
+        * global type in tracepoint fields.
+        */
+       enumeration_name,
+
+       /*
+        * TP_ENUM_VALUES describe the values of this enumeration and what they
+        * map to.
+        */
+       TP_ENUM_VALUES(
+               /*
+                * Maps an integer with this string value. By default, enumerations
+                * start at 0 and increment 1 for each entry.
+                */
+               ctf_enum_value(string_value)
+
+               /*
+                * Maps the string value to integers in the range 'start' to 'end'
+                * inclusively. If 'start' == 'end', then the string is mapped to
+                * a specific value.
+                * Enumeration ranges may overlap, but the behavior is
+                * implementation-defined, each trace reader will handle overlapping
+                * as it wishes.
+                */
+               ctf_enum_range(start, end, string_value)
+       )
+)
+

 .fi
 
 .SH "ASSIGNING LOGLEVEL TO EVENTS"
 .fi
 
 .SH "ASSIGNING LOGLEVEL TO EVENTS"


@@ -262,7 +354,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.
 


@@ -287,6 +379,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"


@@ -296,17 +415,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:


@@ -394,13 +509,9 @@ Pthread identifier. Can be used on architectures where pthread_t maps
 nicely to an unsigned long type.
 .PP
 
 nicely to an unsigned long type.
 .PP
 

-.SH "BASE ADDRESS STATEDUMP (Experimental feature)"
+.SH "BASE ADDRESS STATEDUMP"

 
 .PP
 
 .PP

-Warning: This is an experimental feature known to cause deadlocks when the
-traced application uses fork, clone or daemon. Only use it for debugging and
-testing.  Do NOT use it in production.
-

 If an application that uses liblttng-ust.so becomes part of a session,
 information about its currently loaded shared objects will be traced to the
 session at session-enable time. To record this information, the following event
 If an application that uses liblttng-ust.so becomes part of a session,
 information about its currently loaded shared objects will be traced to the
 session at session-enable time. To record this information, the following event


@@ -425,7 +536,7 @@ line number lookup are traced by LTTng.
 
 .PP
 .IP "LTTNG_UST_DEBUG"
 
 .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


@@ -437,8 +548,20 @@ specified in milliseconds. The value 0 means "don't wait". The value
 recommended for applications with time constraints on the process
 startup time.
 .PP
 recommended for applications with time constraints on the process
 startup time.
 .PP

-.IP "LTTNG_UST_WITH_EXPERIMENTAL_BADDR_STATEDUMP"
-Experimentally allow liblttng-ust to perform a base-address statedump on session-enable.
+.IP "LTTNG_UST_WITHOUT_BADDR_STATEDUMP"
+Prevent liblttng-ust to perform a base-address statedump on session-enable.
+.PP
+.IP "LTTNG_UST_GETCPU_PLUGIN"
+Used by the getcpu override plugin system. The environment variable
+provides the path to the shared object which will act as the getcpu override
+plugin. An example can be found in the lttng-ust documentation under
+examples/getcpu-override .
+.PP
+.IP "LTTNG_UST_CLOCK_PLUGIN"
+Used by the clock override plugin system. The environment variable
+provides the path to the shared object wich will act as the clock override
+plugin. An example can be found in the lttng-ust documentation under
+doc/examples/clock-override .

 .PP
 
 .SH "SEE ALSO"
 .PP
 
 .SH "SEE ALSO"