@node Top
@top LTTng Userspace Tracer
-This manual is for UST 0.5.
+This manual is for UST 0.14.
@end ifnottex
@menu
Components licensed as GPL v2:
@itemize @bullet
@item ustctl
-@item libustcmd
-@item ustd
+@item libustctl
+@item ust-consumerd
@end itemize
@node Supported platforms
@item
ust
-This contains the tracing library, the ustd daemon, trace control tools
+This contains the tracing library, the ust-consumerd daemon, trace control tools
and other helper tools.
-Repository: @url{http://git.dorsal.polymtl.ca}
+Repository: @url{http://lttng.org/ust}
@item
liburcu
/* ... set values of v and st ... */
/* a marker: */
- trace_mark(ust, myevent, "firstarg %d secondarg %s", v, st);
+ ust_marker(myevent, "firstarg %d secondarg %s", v, st);
/* a marker without arguments: */
- trace_mark(ust, myotherevent, MARK_NOARGS);
+ ust_marker(myotherevent, MARK_NOARGS);
return 0;
}
/* ... set values of v and st ... */
/* a marker: */
- trace_mark(main, myevent, "firstarg %d secondarg %s", v, st);
+ ust_marker(myevent, "firstarg %d secondarg %s", v, st);
/* another marker without arguments: */
- trace_mark(main, myotherevent, MARK_NOARGS);
+ ust_marker(myotherevent, MARK_NOARGS);
return 0;
}
@end verbatim
@end example
-The invocation of the trace_mark() macro requires at least 3 arguments. The
-first, here "main", is the name of the event category. It is also the name of
-the channel the event will go in. The second, here "myevent" is the name of the
-event. The third is a format string that announces the names and the types of
-the event arguments. Its format resembles that of a printf() format string; it
-is described thoroughly in Appendix x.
+The invocation of the ust_marker() macro requires at least 2 arguments. The
+first, "myevent", is the name of the event. The second is a format string
+that announces the names and the types of the event arguments. Its
+format resembles that of a printf() format string; it is described
+thoroughly in Appendix x.
A given Marker may appear more than once in the same program. Other Markers may
have the same name and a different format string, although this might induce
@node Tracepoints
@section Tracepoints
-The Tracepoints API uses the Markers, but provides a higher-level abstraction.
-Whereas the markers API provides limited type checking, the Tracepoints API
-provides more thorough type checking and discharges from the need to insert
-format strings directly in the code and to have format strings appear more than
-once if a given marker is reused.
-
-@quotation Note
-Although this example uses @emph{mychannel} as the channel, the
-only channel name currently supported with early tracing is @strong{ust}. The
-@command{usttrace} tool always uses the early tracing mode. When using manual
-mode without early tracing, any channel name may be used.
-@end quotation
-
-A function instrumented with a tracepoint looks like this:
-
-@example
-@verbatim
-#include "tp.h"
-
-void function()
-{
- int v;
- char *st;
-
- /* ... set values of v and st ... */
-
- /* a tracepoint: */
- trace_mychannel_myevent(v, st);
-}
-@end verbatim
-@end example
-
-Another file, here tp.h, contains declarations for the tracepoint.
-
-@example
-@verbatim
-#include <ust/tracepoint.h>
-
-DECLARE_TRACE(mychannel_myevent, TP_PROTO(int v, char *st),
- TP_ARGS(v, st));
-@end verbatim
-@end example
-
-A third file, here tp.c, contains definitions for the tracepoint.
-
-@example
-@verbatim
-#include <ust/marker.h>
-#include "tp.h"
-
-DEFINE_TRACE(mychannel_myevent);
-
-void mychannel_myevent_probe(int v, char *st)
-{
- trace_mark(mychannel, myevent, "v %d st %s", v, st);
-}
-
-static void __attribute__((constructor)) init()
-{
- register_trace_mychannel_myevent(mychannel_myevent_probe);
-}
-@end verbatim
-@end example
-
-Here, tp.h and tp.c could contain declarations and definitions for other
-tracepoints. The constructor would contain other register_* calls.
+The Tracepoint API is superseded by TRACEPOINT_EVENT() (which uses the
+Tracepoints internally). At this stage, TRACEPOINT_EVENT() is work in
+progress. While we complete this API, please use the ust_marker() API
+provided by ust/marker.h.
@node Recording a trace
@chapter Recording a trace
# Make sure the directory for the communication sockets exists.
$ mkdir /tmp/ustsocks
-# Make sure the directory where ustd will write the trace exists.
+# Make sure the directory where ust-consumerd will write the trace exists.
$ mkdir /tmp/trace
# Start the daemon
-$ ustd
+$ ust-consumerd
# We assume the program we want to trace is already running and that
# it has pid 1234.
# List the available markers
-$ ustctl --list-markers 1234
+$ ustctl list-markers 1234
# A column indicates 0 for an inactive marker and 1 for an active marker.
# Enable a marker
-$ ustctl --enable-marker ust/mymark 1234
+$ ustctl enable-marker 1234 auto ust/mymark
# Create a trace
-$ ustctl --create-trace 1234
+$ ustctl create-trace 1234 auto
# Start tracing
-$ ustctl --start-trace 1234
+$ ustctl start-trace 1234 auto
# Do things...
# Stop tracing
-$ ustctl --stop-trace 1234
+$ ustctl stop-trace 1234 auto
# Destroy the trace
-$ ustctl --destroy-trace 1234
+$ ustctl destroy-trace 1234 auto
@end verbatim
@end example
Libust is initialized by a constructor, which by definition runs before the
@code{main()} function of the application starts. This constructor creates a
thread called the @emph{listener thread}. The listener thread initializes a
-named socket and waits for connections for ustd or ustctl.
+named socket and waits for connections for ust-consumerd or ustctl.
Libust-specific code may:
@itemize @bullet
GDB, the GNU Debugger, can use UST markers as GDB tracepoints (note GDB has its
own concept of tracepoint). This feature is called GDB Static Tracepoints. When
a GDB tracepoint is hit, GDB collects the marker arguments, as well as the
-state of the registers.
-
-In UST, support for GDB integration is not compiled in by default because of
-the cost of saving registers when a marker is hit. To enable it, run the
-@command{./configure} script with the @code{-DCONFIG_UST_GDB_INTEGRATION} flag
-in the @env{CFLAGS} environment variable. For example:
-
-@example
-@verbatim
-
-CFLAGS=-DCONFIG_UST_GDB_INTEGRATION ./configure
-
-@end verbatim
-@end example
-
-As of this writing, GDB Static Tracepoints have been submitted
-(@url{http://sourceware.org/ml/gdb-patches/2010-06/msg00592.html}) to the GDB
-mailing list.
-
-GDB integration is currently only supported on x86-32 and x86-64.
+state of the registers. Support for GDB is currently work in progress.
@bye
projects / ust.git / blobdiff