X-Git-Url: http://git.lttng.org./?a=blobdiff_plain;f=doc%2Fman%2Flttng-ust.3;h=4adef5b942715f16a9ebba341b1ee52a81eccb93;hb=ea960c20b5d55ac004fda761ed53aaba2de4cdc3;hp=7dae8b538d8d4161e57f54bee9e5a872815e6f02;hpb=8da6d0c8216f13df8f714459b7d855243296d83c;p=lttng-ust.git

diff --git a/doc/man/lttng-ust.3 b/doc/man/lttng-ust.3
index 7dae8b53..4adef5b9 100644
--- a/doc/man/lttng-ust.3
+++ b/doc/man/lttng-ust.3
@@ -48,6 +48,41 @@ 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
@@ -189,6 +224,17 @@ TRACEPOINT_EVENT(
 		 */
 		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)
 	)
 )
 
@@ -196,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.
 
+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"
@@ -462,6 +551,18 @@ startup time.
 .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"