@node Top
@top LTTng Userspace Tracer
-This manual is for UST 0.5.
+This manual is for UST 0.11.
@end ifnottex
@menu
Components licensed as GPL v2:
@itemize @bullet
@item ustctl
-@item libustcmd
+@item libustctl
@item ust-consumerd
@end itemize
/* ... 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
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.
+The @command{usttrace} tool always uses the early tracing mode.
@end quotation
A function instrumented with a tracepoint looks like this:
@verbatim
#include "tp.h"
-void function()
+void function(void)
{
int v;
char *st;
/* ... set values of v and st ... */
/* a tracepoint: */
- trace_mychannel_myevent(v, st);
+ trace_myevent(v, st);
}
@end verbatim
@end example
@verbatim
#include <ust/tracepoint.h>
-DECLARE_TRACE(mychannel_myevent, TP_PROTO(int v, char *st),
- TP_ARGS(v, st));
+DECLARE_TRACEPOINT(myevent, TP_PROTO(int v, char *st),
+ TP_ARGS(v, st));
@end verbatim
@end example
#include <ust/marker.h>
#include "tp.h"
-DEFINE_TRACE(mychannel_myevent);
+DEFINE_TRACEPOINT(myevent);
-void mychannel_myevent_probe(int v, char *st)
+void myevent_probe(int v, char *st)
{
- trace_mark(mychannel, myevent, "v %d st %s", v, st);
+ ust_marker(myevent, "v %d st %s", v, st);
}
static void __attribute__((constructor)) init()
{
- register_trace_mychannel_myevent(mychannel_myevent_probe);
+ register_trace_myevent(myevent_probe);
}
@end verbatim
@end example
# 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
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