X-Git-Url: http://git.liburcu.org/?a=blobdiff_plain;f=doc%2Fman%2Flttng-ust.3;h=8286e568b64ec915280aae67d1c589261fdb7545;hb=f7911aa7efbda480d98d17ee5731a65d569db265;hp=88025c0e702727da568f9a99b7dbb70bd248cc2c;hpb=0a7c55a5916a0ff52bca2dcbfe4ac825a3bb179d;p=lttng-ust.git diff --git a/doc/man/lttng-ust.3 b/doc/man/lttng-ust.3 index 88025c0e..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,15 +288,15 @@ 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 @@ -304,6 +316,38 @@ 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 @@ -324,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