X-Git-Url: http://git.lttng.org./?a=blobdiff_plain;f=doc%2Fman%2Flttng-ust.3;h=55de9fd2d88cea5de0cd1fa04f6eba46c4371efd;hb=f6df8626c40e58c39e83215a5bdbdf7a29038c35;hp=27b32e9ff6bac1ee77f2ab221d1c80ff9f8e501c;hpb=ff42aeefe49e4b0c0739d844907dccceb54ab9f0;p=lttng-ust.git diff --git a/doc/man/lttng-ust.3 b/doc/man/lttng-ust.3 index 27b32e9f..55de9fd2 100644 --- a/doc/man/lttng-ust.3 +++ b/doc/man/lttng-ust.3 @@ -12,7 +12,7 @@ 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. @@ -33,18 +33,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 * @@ -59,19 +63,19 @@ TRACEPOINT_EVENT( /* * tracepoint name, same format as sample provider. Does not * need to be declared before. in this case the name is - * "message" + * "message" */ message, /* - * 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 +84,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,7 +113,7 @@ TRACEPOINT_EVENT( /* * ctf_array: a statically-sized array. * args: (type, field name, argument expression, value) - */ + */ ctf_array(long, arrfield1, values, 3) /* @@ -117,7 +121,7 @@ TRACEPOINT_EVENT( * 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) /* @@ -129,7 +133,7 @@ TRACEPOINT_EVENT( * 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) @@ -156,6 +160,11 @@ TRACEPOINT_EVENT( ctf_float(double, doublefield, doublearg) ) ) + +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. + .fi .SH "ASSIGNING LOGLEVEL TO EVENTS" @@ -168,7 +177,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 @@ -176,54 +185,54 @@ 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) @@ -249,7 +258,7 @@ 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. +map events back to their call sites when analyzing the trace. .fi .SH "BUILDING/LINKING THE TRACEPOINT PROVIDER" @@ -272,8 +281,10 @@ carefully: 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 + - 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: @@ -291,7 +302,7 @@ carefully: needed. Another way is to dlopen the tracepoint probe when needed by the application. - Example: - - doc/examples/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 dlclose() usage: it is not safe to use dlclose on a provider shared object that is being actively used for tracing due @@ -335,6 +346,13 @@ 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 @@ -348,6 +366,28 @@ 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, that represents the state of currently loaded +shared objects (of the traced application). If this information gets combined +with the lttng-ust-dl(3) instrumentation, all aspects of dynamic loading that +are relevant for symbol and linenumber-lookup are traced by LTTng. +.PP .SH "ENVIRONMENT VARIABLES" .PP @@ -364,19 +404,22 @@ 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 .SH "SEE ALSO" .PP lttng-gen-tp(1), lttng(1), babeltrace(1), lttng-ust-cyg-profile(3), -lttng-sessiond(8) +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 librairies accept older probe providers, even +providers. Newer lttng-ust libraries accept older probe providers, even though some newer features might not be available with those providers. .PP