X-Git-Url: http://git.lttng.org./?a=blobdiff_plain;f=doc%2Fman%2Flttng-ust.3;h=5be3cfaa081a669cb8d9b9e990117dd63f9bc735;hb=efbad5cc87395d00fa1d578ae211aee431fa3b4a;hp=49b3b5d57aa2a52dddd9ca4cb4d9926c2cc8a0c5;hpb=eba411c6aab3199aa9cbc7c1dd128e6a9acbd2db;p=lttng-ust.git diff --git a/doc/man/lttng-ust.3 b/doc/man/lttng-ust.3 index 49b3b5d5..5be3cfaa 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" @@ -123,6 +123,10 @@ 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. */ ctf_sequence(char, seqfield1, text, size_t, textlen) @@ -150,6 +154,79 @@ TRACEPOINT_EVENT( ) .fi +.SH "ASSIGNING LOGLEVEL TO EVENTS" + +.nf + +Optionally, a loglevel can be assigned to a TRACEPOINT_EVENT using the +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 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 +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) + +See lttng(1) for information on how to use LTTng-UST loglevels. + +.fi + .SH "ADDING TRACEPOINTS TO YOUR CODE" .nf @@ -165,6 +242,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" @@ -178,17 +259,17 @@ carefully: 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 + - Use "\-I." for the compilation unit containing the tracepoint provider include (e.g. tp.c). - - Link application with "-ldl". + - Link application with "\-ldl". - If building the provider directly into the application, - link the application with "-llttng-ust". + 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: @@ -198,25 +279,71 @@ carefully: provider header. - Include the tracepoint provider header into all instrumented C files that use the provider. - - Compile the tracepoint provider with "-I.". - - Link the tracepoint provider with "-llttng-ust". - - Link application with "-ldl". + - Compile the tracepoint provider with "\-I.". + - Link the tracepoint provider with "\-llttng-ust". + - 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 @@ -229,7 +356,7 @@ specify how long the applications should wait for sessiond "registration done" command before proceeding to execute the main program. The default is 3000ms (3 seconds). The timeout value is specified in milliseconds. The value 0 means "don't wait". The value --1 means "wait forever". Setting this environment variable to 0 is +\-1 means "wait forever". Setting this environment variable to 0 is recommended for applications with time constraints on the process startup time. .PP @@ -237,12 +364,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