X-Git-Url: http://git.lttng.org/?a=blobdiff_plain;f=doc%2Fman%2Flttng-ust.3;h=0455eea2810e2178dfe7c244eeeb6800d46e6106;hb=c785c634a51956094130218c2bffeff32756cb69;hp=117fe985ffa6f391b288705e12d2862c0b0a62fc;hpb=ce46717ac558a0a1de31f0740a040ee075622677;p=lttng-ust.git diff --git a/doc/man/lttng-ust.3 b/doc/man/lttng-ust.3 index 117fe985..0455eea2 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 + +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 @@ -92,11 +127,11 @@ TRACEPOINT_EVENT( sample_component, /* - * tracepoint name, same format as sample provider. Does not - * need to be declared before. in this case the name is - * "message" + * tracepoint name, characters permitted follow the same + * constraints as the provider name. The name of this example + * event is "sample_event". */ - message, + sample_event, /* * TP_ARGS macro contains the arguments passed for the tracepoint @@ -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" @@ -265,7 +354,7 @@ debug information. debug information with line-level scope (TRACEPOINT_EVENT default) TRACE_DEBUG 14 - debug-level message (trace_printf default) + debug-level message See lttng(1) for information on how to use LTTng-UST loglevels. @@ -290,6 +379,33 @@ 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 map events back to their call sites when analyzing the trace. + +Sometimes arguments to the probe are expensive to compute (e.g. +take call stack). To avoid the computation when the tracepoint is +disabled one can use more 'low level' tracepoint_enabled() and +do_tracepoint() macros as following: + + if (tracepoint_enabled(ust_tests_hello, tptest)) { + /* prepare arguments */ + do_tracepoint(ust_tests_hello, tptest, i, netint, values, + text, strlen(text), dbl, flt); + } + +Here do_tracepoint() doesn't contain check if the tracepoint is enabled. +Using tracepoint() in such scenario is dangerous since it also contains +enabled check and thus race condition is possible in the following code +if the tracepoint has been enabled after check in tracepoint_enabled() +but before tracepoint(): + + if (tracepoint_enabled(provider, name)) { /* tracepoint is disabled */ + prepare(args); + } + /* tracepoint is enabled by 'lttng' tool */ + tracepoint(provider, name, args); /* args wasn't prepared properly */ + +Note also that neither tracepoint_enabled() nor do_tracepoint() have +STAP_PROBEV() call so if you need it you should emit this call yourself. + .fi .SH "BUILDING/LINKING THE TRACEPOINT PROVIDER" @@ -299,17 +415,13 @@ There are 2 ways to compile the Tracepoint Provider with the application: either statically or dynamically. Please follow carefully: - 1.1) Compile the Tracepoint provider with the application, either - directly or through a static library (.a): - - Into exactly one object of your application: define + 1) Compile the Tracepoint Provider with the application, either + directly or through a static library (.a): + - Into exactly one object of your application, define "TRACEPOINT_DEFINE" and include the tracepoint provider. - Use "\-I." for the compilation unit containing the tracepoint - provider include (e.g. tp.c). - - Link application with "\-ldl". - - If building the provider directly into the application, - link the application with "\-llttng-ust". - - If building a static library for the provider, link the static - library with "\-llttng-ust". + provider include (e.g., tp.c). + - Link the application with "\-llttng-ust" and "\-ldl". - Include the tracepoint provider header into all C files using the provider. - Examples: @@ -424,7 +536,7 @@ line number lookup are traced by LTTng. .PP .IP "LTTNG_UST_DEBUG" -Activate liblttng-ust debug output. +Activate liblttng-ust debug and error output. .PP .IP "LTTNG_UST_REGISTER_TIMEOUT" The environment variable "LTTNG_UST_REGISTER_TIMEOUT" can be used to @@ -439,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 wich 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"