Fix: default loglevel is DEBUG

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

diff --git a/doc/man/lttng-ust.3 b/doc/man/lttng-ust.3
index aa52c590380aaff5901f5eef8f6769513d1f23c1..c72bd32bd116a90b2546e1bb33ac4b27c88b0a28 100644 (file)
--- a/doc/man/lttng-ust.3
+++ b/doc/man/lttng-ust.3
@@ -12,12 +12,43 @@ 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 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,9 +64,13 @@ 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(
        /*
 
 TRACEPOINT_EVENT(
        /*


@@ -156,6 +191,11 @@ TRACEPOINT_EVENT(
                ctf_float(double, doublefield, doublearg)
        )
 )
                ctf_float(double, doublefield, doublearg)
        )
 )

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

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


@@ -168,7 +208,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


@@ -249,7 +289,7 @@ 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.

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


@@ -337,6 +377,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


@@ -350,6 +397,33 @@ 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)"
+
+.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
+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
 .SH "ENVIRONMENT VARIABLES"
 
 .PP


@@ -366,19 +440,22 @@ 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.
+.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