X-Git-Url: https://git.lttng.org/?a=blobdiff_plain;f=doc%2Fman%2Flttng-ust.3;h=4adef5b942715f16a9ebba341b1ee52a81eccb93;hb=3e6a069401b74471672a89bac283b5e8f61ccf6f;hp=3ba5c7cc8e46b2a554957d1fd7b5a99b488925b9;hpb=e3feda7db3de3530e7c9c511536c36cccf317013;p=lttng-ust.git diff --git a/doc/man/lttng-ust.3 b/doc/man/lttng-ust.3 index 3ba5c7cc..4adef5b9 100644 --- a/doc/man/lttng-ust.3 +++ b/doc/man/lttng-ust.3 @@ -1,7 +1,7 @@ .TH "LTTNG-UST" "3" "February 16, 2012" "" "" .SH "NAME" -lttng-ust \(em Linux Trace Toolkit Next Generation User-Space Tracer +lttng-ust \(em Linux Trace Toolkit Next Generation User-Space Tracer 2.x .SH "SYNOPSIS" @@ -12,12 +12,78 @@ Link liblttng-ust.so with applications, following this manpage. .SH "DESCRIPTION" .PP -LTTng-UST, the Linux Trace Toolkit Next Generation Userspace Tracer, is +LTTng-UST, the Linux Trace Toolkit Next Generation Userspace Tracer, is a 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. -.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 + +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 UST events when tracing with the following sequence of commands + from lttng-tools: + + lttng create + lttng enable-event -u -a + 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 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 lttng-gen-tp(1) tool. See the lttng-gen-tp(1) manpage for explanation. @@ -33,18 +99,22 @@ script, through an example: .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( /* * provider name, not a variable but a string starting with a - * letter and containing either letters, numbers or underscores. + * letter and containing either letters, numbers or underscores. * Needs to be the same as TRACEPOINT_PROVIDER. Needs to * follow the namespacing guide-lines in lttng/tracepoint.h: - * - * Must be included before include tracepoint provider + * + * Must be included before include tracepoint provider * ex.: project_event * ex.: project_component_event * @@ -57,21 +127,21 @@ 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 + * TP_ARGS macro contains the arguments passed for the tracepoint * it is in the following format * TP_ARGS(type1, name1, type2, name2, ... type10, name10) - * where there can be from zero to ten elements. - * typeN is the datatype, such as int, struct or double **. + * where there can be from zero to ten elements. + * typeN is the datatype, such as int, struct or double **. * name is the variable name (in "int myInt" the name would be - * myint) + * myint) * TP_ARGS() is valid to mean no arguments * TP_ARGS(void) is valid too */ @@ -80,7 +150,7 @@ TRACEPOINT_EVENT( double, doublearg, float, floatarg), /* - * TP_FIELDS describes how to write the fields of the trace event. + * TP_FIELDS describes how to write the fields of the trace event. * You can put expressions in the "argument expression" area, * typically using the input arguments from TP_ARGS. */ @@ -109,27 +179,34 @@ TRACEPOINT_EVENT( /* * ctf_array: a statically-sized array. * args: (type, field name, argument expression, value) - */ + */ ctf_array(long, arrfield1, values, 3) /* * ctf_array_text: a statically-sized array, printed as * a string. No need to be terminated by a null * character. - */ + * Behavior is undefined if "text" argument is NULL. + */ ctf_array_text(char, arrfield2, text, 10) /* * ctf_sequence: a dynamically-sized array. * args: (type, field name, argument expression, * type of length expression, length expression) - */ + * The "type of length expression" needs to be an + * unsigned type. As a reminder, "unsigned char" should + * be preferred to "char", since the signedness of + * "char" is implementation-defined. + * Behavior is undefined if "text" argument is NULL. + */ ctf_sequence(char, seqfield1, text, size_t, textlen) /* * ctf_sequence_text: a dynamically-sized array, printed * as string. No need to be null-terminated. + * Behavior is undefined if "text" argument is NULL. */ ctf_sequence_text(char, seqfield2, text, size_t, textlen) @@ -137,6 +214,7 @@ TRACEPOINT_EVENT( /* * ctf_string: null-terminated string. * args: (field name, argument expression) + * Behavior is undefined if "text" argument is NULL. */ ctf_string(stringfield, text) @@ -146,8 +224,67 @@ 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) + ) +) + +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" @@ -160,7 +297,7 @@ following construct: TRACEPOINT_LOGLEVEL(< [com_company_]project[_component] >, < event >, < loglevel_name >) - The first field is the provider name, the second field is the name of +The first field is the provider name, the second field is the name of the tracepoint, and the third field is the loglevel name. A TRACEPOINT_EVENT should be declared prior to the the TRACEPOINT_LOGLEVEL for a given tracepoint name. The TRACEPOINT_PROVIDER must be already @@ -168,56 +305,56 @@ declared before declaring a TRACEPOINT_LOGLEVEL. The loglevels go from 0 to 14. Higher numbers imply the most verbosity (higher event throughput expected. - + Loglevels 0 through 6, and loglevel 14, match syslog(3) loglevels semantic. Loglevels 7 through 13 offer more fine-grained selection of debug information. - + TRACE_EMERG 0 system is unusable - + TRACE_ALERT 1 action must be taken immediately - + TRACE_CRIT 2 critical conditions - + TRACE_ERR 3 error conditions - + TRACE_WARNING 4 warning conditions - + TRACE_NOTICE 5 normal, but significant, condition - + TRACE_INFO 6 informational message - + TRACE_DEBUG_SYSTEM 7 debug information with system-level scope (set of programs) - + TRACE_DEBUG_PROGRAM 8 debug information with program-level scope (set of processes) - + TRACE_DEBUG_PROCESS 9 debug information with process-level scope (set of modules) - + TRACE_DEBUG_MODULE 10 debug information with module (executable/library) scope (set of units) - + TRACE_DEBUG_UNIT 11 debug information with compilation unit scope (set of functions) - + TRACE_DEBUG_FUNCTION 12 debug information with function-level scope - + TRACE_DEBUG_LINE 13 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. @@ -238,6 +375,37 @@ For instance, add within a function: As a call to the tracepoint. It will only be activated when requested by lttng(1) through lttng-sessiond(8). +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" @@ -247,21 +415,19 @@ 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 "\-lllttng-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. - - Example: - tests/hello/ hello.c tp.c ust_tests_hello.h Makefile.example + - Examples: + - doc/examples/easy-ust/ sample.c sample_component_provider.h tp.c + Makefile + - doc/examples/hello-static-lib/ hello.c tp.c ust_test_hello.h Makefile 2) Compile the Tracepoint Provider separately from the application, using dynamic linking: @@ -276,25 +442,101 @@ carefully: - Link application with "\-ldl". - Set a LD_PRELOAD environment to preload the tracepoint provider shared object before starting the application when tracing is - needed. + needed. Another way is to dlopen the tracepoint probe when needed + by the application. - Example: - - tests/demo/ demo.c tp*.c ust_tests_demo*.h demo-trace + - doc/examples/demo demo.c tp*.c ust_tests_demo*.h demo-trace Makefile - - Note about dlopen() usage: due to locking side-effects due to the - way libc lazily resolves Thread-Local Storage (TLS) symbols when a - library is dlopen'd, linking the tracepoint probe or liblttng-ust - with dlopen() is discouraged. They should be linked with the - application using "\-llibname" or loaded with LD_PRELOAD. + - Note about dlclose() usage: it is not safe to use dlclose on a + provider shared object that is being actively used for tracing due + to a lack of reference counting from lttng-ust to the used shared + object. - Enable instrumentation and control tracing with the "lttng" command from lttng-tools. See lttng-tools doc/quickstart.txt. + - Note for C++ support: although an application instrumented with + tracepoints can be compiled with g++, tracepoint probes should be + compiled with gcc (only tested with gcc so far). + +.fi + +.SH "USING LTTNG UST WITH DAEMONS" + +.nf +Some extra care is needed when using liblttng-ust with daemon +applications that call fork(), clone(), or BSD rfork() without a +following exec() family system call. The library "liblttng-ust-fork.so" +needs to be preloaded for the application (launch with e.g. +LD_PRELOAD=liblttng-ust-fork.so appname). .fi +.SH "CONTEXT" + +.PP +Context information can be prepended by the tracer before each, or some, +events. The following context information is supported by LTTng-UST: +.PP + +.PP +.IP "vtid" +Virtual thread ID: thread ID as seen from the point of view of the +process namespace. +.PP + +.PP +.IP "vpid" +Virtual process ID: process ID as seen from the point of view of the +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 +programs set their thread name with prctl() before hitting the first +tracepoint for that thread. +.PP + +.PP +.IP "pthread_id" +Pthread identifier. Can be used on architectures where pthread_t maps +nicely to an unsigned long type. +.PP + +.SH "BASE ADDRESS STATEDUMP" + +.PP +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 .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 @@ -306,16 +548,45 @@ specified in milliseconds. The value 0 means "don't wait". The value recommended for applications with time constraints on the process startup time. .PP +.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" .PP -lttng-gen-tp(1), lttng(1), babeltrace(1), lttng-sessiond(8) +lttng-gen-tp(1), lttng(1), babeltrace(1), lttng-ust-cyg-profile(3), +lttng-ust-dl(3), lttng-sessiond(8) .PP + +.SH "COMPATIBILITY" + +.PP +Older lttng-ust libraries reject more recent, and incompatible, probe +providers. Newer lttng-ust libraries accept older probe providers, even +though some newer features might not be available with those providers. +.PP + .SH "BUGS" .PP -No knows bugs at this point. +LTTng-UST 2.0 and 2.1 lttng-ust libraries do not check for probe +provider version compatibility. This can lead to out-of-bound accesses +when using a more recent probe provider with an older lttng-ust library. +These error only trigger when tracing is active. This issue has been +fixed in LTTng-UST 2.2. If you encounter any issues or usability problem, please report it on our mailing list to help improve this