Fix: remove dead code from filter interpreter

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

diff --git a/doc/man/lttng-ust.3 b/doc/man/lttng-ust.3
index 27b32e9ff6bac1ee77f2ab221d1c80ff9f8e501c..4adef5b942715f16a9ebba341b1ee52a81eccb93 100644 (file)
--- a/doc/man/lttng-ust.3
+++ b/doc/man/lttng-ust.3
@@ -12,12 +12,78 @@ Link liblttng-ust.so with applications, following this manpage.
 .SH "DESCRIPTION"
 
 .PP
 .SH "DESCRIPTION"
 
 .PP

-LTTng-UST, the Linux Trace Toolkit Next Generation Userspace Tracer, is
+LTTng-UST, the Linux Trace Toolkit Next Generation Userspace Tracer, is a

 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.
 
 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.
 

-.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(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
 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.


@@ -33,18 +99,22 @@ script, through an example:
 .nf
 
 To create a tracepoint provider, within a build tree similar to
 .nf
 
 To create a tracepoint provider, within a build tree similar to

-examples/easy-ust installed with lttng-ust documentation, a
-sample_component_provider.h for the general layout. This manpage will
-focus on the various types that can be recorded into a trace event:
+examples/easy-ust installed with lttng-ust documentation, see
+sample_component_provider.h for the general layout. You will need to
+define TRACEPOINT_CREATE_PROBES before including your tracepoint
+provider probe in one source file of your application. See tp.c from
+easy-ust for an example of a tracepoint probe source file. This manpage
+will focus on the various types that can be recorded into a trace
+event:

 
 TRACEPOINT_EVENT(
        /*
         * provider name, not a variable but a string starting with a
 
 TRACEPOINT_EVENT(
        /*
         * provider name, not a variable but a string starting with a

-        * letter and containing either letters, numbers or underscores. 
+        * letter and containing either letters, numbers or underscores.

         * Needs to be the same as TRACEPOINT_PROVIDER. Needs to
         * follow the namespacing guide-lines in lttng/tracepoint.h:
         * Needs to be the same as TRACEPOINT_PROVIDER. Needs to
         * follow the namespacing guide-lines in lttng/tracepoint.h:

-        * 
-        * Must be included before include tracepoint provider 
+        *
+        * Must be included before include tracepoint provider

         * ex.: project_event
         * ex.: project_component_event
         *
         * ex.: project_event
         * ex.: project_component_event
         *


@@ -57,21 +127,21 @@ 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

         * it is in the following format
         *            TP_ARGS(type1, name1, type2, name2, ... type10,
                                 name10)
         * it is in the following format
         *            TP_ARGS(type1, name1, type2, name2, ... type10,
                                 name10)

-        * where there can be from zero to ten elements. 
-        * typeN is the datatype, such as int, struct or double **. 
+        * where there can be from zero to ten elements.
+        * typeN is the datatype, such as int, struct or double **.

         * name is the variable name (in "int myInt" the name would be
         * name is the variable name (in "int myInt" the name would be

-        * myint) 
+        * myint)

         *            TP_ARGS() is valid to mean no arguments
         *            TP_ARGS(void) is valid too
         */
         *            TP_ARGS() is valid to mean no arguments
         *            TP_ARGS(void) is valid too
         */


@@ -80,7 +150,7 @@ TRACEPOINT_EVENT(
                 double, doublearg, float, floatarg),
 
        /*
                 double, doublearg, float, floatarg),
 
        /*

-        * TP_FIELDS describes how to write the fields of the trace event. 
+        * TP_FIELDS describes how to write the fields of the trace event.

         * You can put expressions in the "argument expression" area,
         * typically using the input arguments from TP_ARGS.
         */
         * You can put expressions in the "argument expression" area,
         * typically using the input arguments from TP_ARGS.
         */


@@ -109,7 +179,7 @@ TRACEPOINT_EVENT(
                /*
                 * ctf_array: a statically-sized array.
                 * args: (type, field name, argument expression, value)
                /*
                 * ctf_array: a statically-sized array.
                 * args: (type, field name, argument expression, value)

-                */ 
+                */

                ctf_array(long, arrfield1, values, 3)
 
                /*
                ctf_array(long, arrfield1, values, 3)
 
                /*


@@ -117,7 +187,7 @@ TRACEPOINT_EVENT(
                 * a string. No need to be terminated by a null
                 * character.
                 * Behavior is undefined if "text" argument is NULL.
                 * a string. No need to be terminated by a null
                 * character.
                 * Behavior is undefined if "text" argument is NULL.

-                */ 
+                */

                ctf_array_text(char, arrfield2, text, 10)
 
                /*
                ctf_array_text(char, arrfield2, text, 10)
 
                /*


@@ -129,7 +199,7 @@ TRACEPOINT_EVENT(
                 * be preferred to "char", since the signedness of
                 * "char" is implementation-defined.
                 * Behavior is undefined if "text" argument is NULL.
                 * be preferred to "char", since the signedness of
                 * "char" is implementation-defined.
                 * Behavior is undefined if "text" argument is NULL.

-                */ 
+                */

                ctf_sequence(char, seqfield1, text,
                             size_t, textlen)
 
                ctf_sequence(char, seqfield1, text,
                             size_t, textlen)
 


@@ -154,8 +224,67 @@ 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)
+       )
+)
+
+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.
+
+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"


@@ -168,7 +297,7 @@ following construct:
        TRACEPOINT_LOGLEVEL(< [com_company_]project[_component] >,
                < event >, < loglevel_name >)
 
        TRACEPOINT_LOGLEVEL(< [com_company_]project[_component] >,
                < event >, < loglevel_name >)
 

- The first field is the provider name, the second field is the name of
+The first field is the provider name, the second field is the name of

 the tracepoint, and the third field is the loglevel name.  A
 TRACEPOINT_EVENT should be declared prior to the the TRACEPOINT_LOGLEVEL
 for a given tracepoint name. The TRACEPOINT_PROVIDER must be already
 the tracepoint, and the third field is the loglevel name.  A
 TRACEPOINT_EVENT should be declared prior to the the TRACEPOINT_LOGLEVEL
 for a given tracepoint name. The TRACEPOINT_PROVIDER must be already


@@ -176,56 +305,56 @@ declared before declaring a TRACEPOINT_LOGLEVEL.
 
 The loglevels go from 0 to 14. Higher numbers imply the most verbosity
 (higher event throughput expected.
 
 The loglevels go from 0 to 14. Higher numbers imply the most verbosity
 (higher event throughput expected.

-  
+

 Loglevels 0 through 6, and loglevel 14, match syslog(3) loglevels
 semantic. Loglevels 7 through 13 offer more fine-grained selection of
 debug information.
 Loglevels 0 through 6, and loglevel 14, match syslog(3) loglevels
 semantic. Loglevels 7 through 13 offer more fine-grained selection of
 debug information.

-  
+

    TRACE_EMERG           0
    system is unusable
    TRACE_EMERG           0
    system is unusable

-  
+

    TRACE_ALERT           1
    action must be taken immediately
    TRACE_ALERT           1
    action must be taken immediately

-  
+

    TRACE_CRIT            2
    critical conditions
    TRACE_CRIT            2
    critical conditions

-  
+

    TRACE_ERR             3
    error conditions
    TRACE_ERR             3
    error conditions

-  
+

    TRACE_WARNING         4
    warning conditions
    TRACE_WARNING         4
    warning conditions

-  
+

    TRACE_NOTICE          5
    normal, but significant, condition
    TRACE_NOTICE          5
    normal, but significant, condition

-  
+

    TRACE_INFO            6
    informational message
    TRACE_INFO            6
    informational message

-  
+

    TRACE_DEBUG_SYSTEM    7
    debug information with system-level scope (set of programs)
    TRACE_DEBUG_SYSTEM    7
    debug information with system-level scope (set of programs)

-  
+

    TRACE_DEBUG_PROGRAM   8
    debug information with program-level scope (set of processes)
    TRACE_DEBUG_PROGRAM   8
    debug information with program-level scope (set of processes)

-  
+

    TRACE_DEBUG_PROCESS   9
    debug information with process-level scope (set of modules)
    TRACE_DEBUG_PROCESS   9
    debug information with process-level scope (set of modules)

-  
+

    TRACE_DEBUG_MODULE    10
    debug information with module (executable/library) scope (set of
    units)
    TRACE_DEBUG_MODULE    10
    debug information with module (executable/library) scope (set of
    units)

-  
+

    TRACE_DEBUG_UNIT      11
    debug information with compilation unit scope (set of functions)
    TRACE_DEBUG_UNIT      11
    debug information with compilation unit scope (set of functions)

-  
+

    TRACE_DEBUG_FUNCTION  12
    debug information with function-level scope
    TRACE_DEBUG_FUNCTION  12
    debug information with function-level scope

-  
+

    TRACE_DEBUG_LINE      13
    debug information with line-level scope (TRACEPOINT_EVENT default)
    TRACE_DEBUG_LINE      13
    debug information with line-level scope (TRACEPOINT_EVENT default)

-  
+

    TRACE_DEBUG           14
    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.
 


@@ -249,7 +378,34 @@ lttng(1) through lttng-sessiond(8).
 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
 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

-mapping events back to their call sites when analyzing the trace.
+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"


@@ -259,21 +415,19 @@ 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.
     - Include the tracepoint provider header into all C files using
       the provider.

-    - Example:
-      - tests/hello/  hello.c tp.c ust_tests_hello.h Makefile.example
+    - Examples:
+      - doc/examples/easy-ust/   sample.c sample_component_provider.h tp.c
+        Makefile
+      - doc/examples/hello-static-lib/   hello.c tp.c ust_test_hello.h Makefile

 
   2) Compile the Tracepoint Provider separately from the application,
      using dynamic linking:
 
   2) Compile the Tracepoint Provider separately from the application,
      using dynamic linking:


@@ -291,7 +445,7 @@ carefully:
       needed. Another way is to dlopen the tracepoint probe when needed
       by the application.
     - Example:
       needed. Another way is to dlopen the tracepoint probe when needed
       by the application.
     - Example:

-      - doc/examples/demo   demo.c  tp*.c ust_tests_demo*.h demo-trace
+      - doc/examples/demo   demo.c  tp*.c ust_tests_demo*.h demo-trace Makefile

 
   - Note about dlclose() usage: it is not safe to use dlclose on a
     provider shared object that is being actively used for tracing due
 
   - Note about dlclose() usage: it is not safe to use dlclose on a
     provider shared object that is being actively used for tracing due


@@ -335,6 +489,13 @@ Virtual process ID: process ID as seen from the point of view of the
 process namespace.
 .PP
 
 process namespace.
 .PP
 

+.PP
+.IP "ip"
+Instruction pointer: Enables recording of the exact location where a tracepoint
+was emitted. Can be used to reverse-lookup the source location that caused the
+event to be emitted.
+.PP
+

 .PP
 .IP "procname"
 Thread name, as set by exec() or prctl(). It is recommended that
 .PP
 .IP "procname"
 Thread name, as set by exec() or prctl(). It is recommended that


@@ -348,11 +509,34 @@ 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"
+
+.PP
+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
+needs to be enabled:
+.PP
+.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. 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"
 .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


@@ -364,19 +548,34 @@ 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_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 which 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
 lttng-gen-tp(1), lttng(1), babeltrace(1), lttng-ust-cyg-profile(3),
 
 .SH "SEE ALSO"
 
 .PP
 lttng-gen-tp(1), lttng(1), babeltrace(1), lttng-ust-cyg-profile(3),

-lttng-sessiond(8)
+lttng-ust-dl(3), lttng-sessiond(8)

 .PP
 
 .SH "COMPATIBILITY"
 
 .PP
 Older lttng-ust libraries reject more recent, and incompatible, probe
 .PP
 
 .SH "COMPATIBILITY"
 
 .PP
 Older lttng-ust libraries reject more recent, and incompatible, probe

-providers. Newer lttng-ust librairies accept older probe providers, even
+providers. Newer lttng-ust libraries accept older probe providers, even

 though some newer features might not be available with those providers.
 .PP
 
 though some newer features might not be available with those providers.
 .PP