X-Git-Url: http://git.lttng.org/?a=blobdiff_plain;f=doc%2Fman%2Flttng-ust.3;h=8286e568b64ec915280aae67d1c589261fdb7545;hb=f7911aa7efbda480d98d17ee5731a65d569db265;hp=3ba5c7cc8e46b2a554957d1fd7b5a99b488925b9;hpb=e3feda7db3de3530e7c9c511536c36cccf317013;p=lttng-ust.git diff --git a/doc/man/lttng-ust.3 b/doc/man/lttng-ust.3 index 3ba5c7cc..8286e568 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" @@ -116,6 +116,7 @@ TRACEPOINT_EVENT( * 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" field is NULL. */ ctf_array_text(char, arrfield2, text, 10) @@ -123,6 +124,11 @@ TRACEPOINT_EVENT( * 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" field is NULL. */ ctf_sequence(char, seqfield1, text, size_t, textlen) @@ -130,6 +136,7 @@ TRACEPOINT_EVENT( /* * ctf_sequence_text: a dynamically-sized array, printed * as string. No need to be null-terminated. + * Behavior is undefined if "text" field is NULL. */ ctf_sequence_text(char, seqfield2, text, size_t, textlen) @@ -137,6 +144,7 @@ TRACEPOINT_EVENT( /* * ctf_string: null-terminated string. * args: (field name, argument expression) + * Behavior is undefined if "text" field is NULL. */ ctf_string(stringfield, text) @@ -238,6 +246,10 @@ 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 +mapping events back to their call sites when analyzing the trace. .fi .SH "BUILDING/LINKING THE TRACEPOINT PROVIDER" @@ -257,11 +269,11 @@ carefully: - 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". + library with "\-llttng-ust". - 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 + - tests/hello/ hello.c tp.c ust_tests_hello.h Makefile.example 2) Compile the Tracepoint Provider separately from the application, using dynamic linking: @@ -276,20 +288,66 @@ 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 - - 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 "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 "ENVIRONMENT VARIABLES" .PP @@ -310,12 +368,13 @@ startup time. .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-sessiond(8) .PP .SH "BUGS" .PP -No knows bugs at this point. +No known bugs at this point. If you encounter any issues or usability problem, please report it on our mailing list to help improve this