Fix: typo in 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 de4271c2dd037969a6fdfdd6a3dac2d6268b56c1..61efa5094611d39859a88761dff90cb4eabfccc6 100644 (file)
--- a/doc/man/lttng-ust.3
+++ b/doc/man/lttng-ust.3
@@ -17,7 +17,35 @@ 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 the UST event "lttng_ust_tracef:event" when tracing with the
+   following sequence of commands from lttng-tools:
+
+   lttng create; lttng enable-event -u "lttng_ust_tracef:event"; 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 +61,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(
        /*


@@ -342,6 +374,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


@@ -355,6 +394,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


@@ -371,19 +437,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