[lttng-ust.git] / doc / man / lttng-ust.3

.TH "LTTNG-UST" "3" "February 16, 2012" "" ""

.SH "NAME"
lttng-ust \(em Linux Trace Toolkit Next Generation User-Space Tracer 2.x

.SH "SYNOPSIS"

.PP
.nf
Link liblttng-ust.so with applications, following this manpage.
.fi
.SH "DESCRIPTION"

.PP
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"
.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.
.PP

.PP
Here is the way to do it manually, without the lttng-gen-tp(1) helper
script, through an example:
.PP

.SH "CREATION OF TRACEPOINT PROVIDER"

.nf

To create a tracepoint provider, within a build tree similar to
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.
	 * 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
	 * ex.: project_event
	 * ex.: project_component_event
	 *
	 * Optional company name goes here
	 *  ex.: com_efficios_project_component_event
	 *
	 * In this example, "sample" is the project, and "component" is the
	 * component.
	 */
	sample_component,

	/*
	 * tracepoint name, same format as sample provider. Does not
	 * need to be declared before. in this case the name is
	 * "message"
	 */
	message,

	/*
	 * 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 **.
	 * name is the variable name (in "int myInt" the name would be
	 * myint)
	 *	      TP_ARGS() is valid to mean no arguments
	 *	      TP_ARGS(void) is valid too
	 */
	TP_ARGS(int, anint, int, netint, long *, values,
		 char *, text, size_t, textlen,
		 double, doublearg, float, floatarg),

	/*
	 * 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.
	 */
	TP_FIELDS(
		/*
		 * ctf_integer: standard integer field.
		 * args: (type, field name, argument expression)
		 */
		ctf_integer(int, intfield, anint)
		ctf_integer(long, longfield, anint)

		/*
		 * ctf_integer_hex: integer field printed as hexadecimal.
		 * args: (type, field name, argument expression)
		 */
		ctf_integer_hex(int, intfield2, anint)

		/*
		 * ctf_integer_network: integer field in network byte
		 * order. (_hex: printed as hexadecimal too)
		 * args: (type, field name, argument expression)
		 */
		ctf_integer_network(int, netintfield, netint)
		ctf_integer_network_hex(int, netintfieldhex, netint)

		/*
		 * 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)

		/*
		 * ctf_string: null-terminated string.
		 * args: (field name, argument expression)
		 * Behavior is undefined if "text" argument is NULL.
		 */
		ctf_string(stringfield, text)

		/*
		 * ctf_float: floating-point number.
		 * args: (type, field name, argument expression)
		 */
		ctf_float(float, floatfield, floatarg)
		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"

.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

Include the provider header in each C files you plan to instrument,
following the building/linking directives in the next section.

For instance, add within a function:

		tracepoint(ust_tests_hello, tptest, i, netint, values,
			text, strlen(text), dbl, flt);

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.
.fi

.SH "BUILDING/LINKING THE TRACEPOINT PROVIDER"

.nf
There are 2 ways to compile the Tracepoint Provider with the
application: either statically or dynamically. Please follow
carefully:

  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 the application with "\-llttng-ust" and "\-ldl".
    - Include the tracepoint provider header into all C files using
      the provider.
    - 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:
    - Into exactly one object of your application: define
      "TRACEPOINT_DEFINE" _and_ also define
      "TRACEPOINT_PROBE_DYNAMIC_LINKAGE", then include the tracepoint
      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".
    - Set a LD_PRELOAD environment to preload the tracepoint provider
      shared object before starting the application when tracing is
      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 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
    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 (Experimental feature)"

.PP
Warning: This is an experimental feature known to cause deadlocks when the
traced application uses fork, clone or daemon. Only use it for debugging and
testing.  Do NOT use it in production.

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.
.PP
.IP "LTTNG_UST_REGISTER_TIMEOUT"
The environment variable "LTTNG_UST_REGISTER_TIMEOUT" can be used to
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
recommended for applications with time constraints on the process
startup time.
.PP
.IP "LTTNG_UST_WITH_EXPERIMENTAL_BADDR_STATEDUMP"
Experimentally allow 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-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
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 <lttng-dev@lists.lttng.org> to help improve this
project.
.SH "CREDITS"

liblttng-ust is distributed under the GNU Lesser General Public License
version 2.1. The headers are distributed under the MIT license.
.PP
See http://lttng.org for more information on the LTTng project.
.PP
Mailing list for support and development: <lttng-dev@lists.lttng.org>.
.PP
You can find us on IRC server irc.oftc.net (OFTC) in #lttng.
.PP
.SH "THANKS"

Thanks to Ericsson for funding this work, providing real-life use-cases,
and testing.

Special thanks to Michel Dagenais and the DORSAL laboratory at
Polytechnique de Montreal for the LTTng journey.
.PP
.SH "AUTHORS"

.PP
liblttng-ust was originally written by Mathieu Desnoyers, with additional
contributions from various other people. It is currently maintained by
Mathieu Desnoyers <mathieu.desnoyers@efficios.com>.
.PP
Commit	Line	Data
eba411c6 MD	1	.TH "LTTNG-UST" "3" "February 16, 2012" "" ""
	2
	3	.SH "NAME"
77ca1460	4	lttng-ust \(em Linux Trace Toolkit Next Generation User-Space Tracer 2.x
eba411c6 MD	5
	6	.SH "SYNOPSIS"
	7
	8	.PP
	9	.nf
	10	Link liblttng-ust.so with applications, following this manpage.
	11	.fi
	12	.SH "DESCRIPTION"
	13
	14	.PP
7c501923	15	LTTng-UST, the Linux Trace Toolkit Next Generation Userspace Tracer, is a
eba411c6 MD	16	port of the low-overhead tracing capabilities of the LTTng kernel tracer
	17	to user-space. The library "liblttng-ust" enables tracing of
	18	applications and libraries.
	19
	20	.SH "USAGE"
	21	.PP
	22	The simple way to generate the lttng-ust tracepoint probes is to use the
	23	lttng-gen-tp(1) tool. See the lttng-gen-tp(1) manpage for explanation.
	24	.PP
	25
	26	.PP
	27	Here is the way to do it manually, without the lttng-gen-tp(1) helper
	28	script, through an example:
	29	.PP
	30
	31	.SH "CREATION OF TRACEPOINT PROVIDER"
	32
	33	.nf
	34
	35	To create a tracepoint provider, within a build tree similar to
dfc45f18 MD	36	examples/easy-ust installed with lttng-ust documentation, see
	37	sample_component_provider.h for the general layout. You will need to
	38	define TRACEPOINT_CREATE_PROBES before including your tracepoint
	39	provider probe in one source file of your application. See tp.c from
	40	easy-ust for an example of a tracepoint probe source file. This manpage
	41	will focus on the various types that can be recorded into a trace
	42	event:
eba411c6 MD	43
	44	TRACEPOINT_EVENT(
	45	/*
	46	* provider name, not a variable but a string starting with a
a106a9f8	47	* letter and containing either letters, numbers or underscores.
eba411c6 MD	48	* Needs to be the same as TRACEPOINT_PROVIDER. Needs to
eba411c6 MD	49	* follow the namespacing guide-lines in lttng/tracepoint.h:
a106a9f8 JG	50	*
a106a9f8 JG	51	* Must be included before include tracepoint provider
eba411c6 MD	52	* ex.: project_event
	53	* ex.: project_component_event
	54	*
	55	* Optional company name goes here
	56	* ex.: com_efficios_project_component_event
	57	*
	58	* In this example, "sample" is the project, and "component" is the
	59	* component.
	60	*/
	61	sample_component,
	62
	63	/*
	64	* tracepoint name, same format as sample provider. Does not
	65	* need to be declared before. in this case the name is
a106a9f8	66	* "message"
eba411c6 MD	67	*/
	68	message,
	69
	70	/*
a106a9f8	71	* TP_ARGS macro contains the arguments passed for the tracepoint
eba411c6 MD	72	* it is in the following format
	73	* TP_ARGS(type1, name1, type2, name2, ... type10,
	74	name10)
a106a9f8 JG	75	* where there can be from zero to ten elements.
a106a9f8 JG	76	* typeN is the datatype, such as int, struct or double **.
eba411c6	77	* name is the variable name (in "int myInt" the name would be
a106a9f8	78	* myint)
eba411c6 MD	79	* TP_ARGS() is valid to mean no arguments
	80	* TP_ARGS(void) is valid too
	81	*/
	82	TP_ARGS(int, anint, int, netint, long *, values,
	83	char *, text, size_t, textlen,
	84	double, doublearg, float, floatarg),
	85
	86	/*
a106a9f8	87	* TP_FIELDS describes how to write the fields of the trace event.
eba411c6 MD	88	* You can put expressions in the "argument expression" area,
	89	* typically using the input arguments from TP_ARGS.
	90	*/
	91	TP_FIELDS(
	92	/*
	93	* ctf_integer: standard integer field.
	94	* args: (type, field name, argument expression)
	95	*/
	96	ctf_integer(int, intfield, anint)
	97	ctf_integer(long, longfield, anint)
	98
	99	/*
	100	* ctf_integer_hex: integer field printed as hexadecimal.
	101	* args: (type, field name, argument expression)
	102	*/
	103	ctf_integer_hex(int, intfield2, anint)
	104
	105	/*
	106	* ctf_integer_network: integer field in network byte
	107	* order. (_hex: printed as hexadecimal too)
	108	* args: (type, field name, argument expression)
	109	*/
	110	ctf_integer_network(int, netintfield, netint)
	111	ctf_integer_network_hex(int, netintfieldhex, netint)
	112
	113	/*
	114	* ctf_array: a statically-sized array.
	115	* args: (type, field name, argument expression, value)
a106a9f8	116	*/
eba411c6 MD	117	ctf_array(long, arrfield1, values, 3)
	118
	119	/*
	120	* ctf_array_text: a statically-sized array, printed as
	121	* a string. No need to be terminated by a null
	122	* character.
2f65f1f5	123	* Behavior is undefined if "text" argument is NULL.
a106a9f8	124	*/
eba411c6 MD	125	ctf_array_text(char, arrfield2, text, 10)
	126
	127	/*
	128	* ctf_sequence: a dynamically-sized array.
	129	* args: (type, field name, argument expression,
	130	* type of length expression, length expression)
efbad5cc MD	131	* The "type of length expression" needs to be an
	132	* unsigned type. As a reminder, "unsigned char" should
	133	* be preferred to "char", since the signedness of
	134	* "char" is implementation-defined.
2f65f1f5	135	* Behavior is undefined if "text" argument is NULL.
a106a9f8	136	*/
eba411c6 MD	137	ctf_sequence(char, seqfield1, text,
	138	size_t, textlen)
	139
	140	/*
	141	* ctf_sequence_text: a dynamically-sized array, printed
	142	* as string. No need to be null-terminated.
2f65f1f5	143	* Behavior is undefined if "text" argument is NULL.
eba411c6 MD	144	*/
	145	ctf_sequence_text(char, seqfield2, text,
	146	size_t, textlen)
	147
	148	/*
	149	* ctf_string: null-terminated string.
	150	* args: (field name, argument expression)
2f65f1f5	151	* Behavior is undefined if "text" argument is NULL.
eba411c6 MD	152	*/
	153	ctf_string(stringfield, text)
	154
	155	/*
	156	* ctf_float: floating-point number.
	157	* args: (type, field name, argument expression)
	158	*/
	159	ctf_float(float, floatfield, floatarg)
	160	ctf_float(double, doublefield, doublearg)
	161	)
	162	)
7d381d6e MD	163
	164	There can be an arbitrary number of tracepoint providers within an
	165	application, but they must each have their own provider name. Duplicate
	166	provider names are not allowed.
	167
eba411c6 MD	168	.fi
eba411c6 MD	169
5883c06f MD	170	.SH "ASSIGNING LOGLEVEL TO EVENTS"
	171
	172	.nf
	173
	174	Optionally, a loglevel can be assigned to a TRACEPOINT_EVENT using the
	175	following construct:
	176
	177	TRACEPOINT_LOGLEVEL(< [com_company_]project[_component] >,
	178	< event >, < loglevel_name >)
	179
7c501923	180	The first field is the provider name, the second field is the name of
5883c06f MD	181	the tracepoint, and the third field is the loglevel name. A
	182	TRACEPOINT_EVENT should be declared prior to the the TRACEPOINT_LOGLEVEL
	183	for a given tracepoint name. The TRACEPOINT_PROVIDER must be already
	184	declared before declaring a TRACEPOINT_LOGLEVEL.
	185
	186	The loglevels go from 0 to 14. Higher numbers imply the most verbosity
	187	(higher event throughput expected.
a106a9f8	188
5883c06f MD	189	Loglevels 0 through 6, and loglevel 14, match syslog(3) loglevels
	190	semantic. Loglevels 7 through 13 offer more fine-grained selection of
	191	debug information.
a106a9f8	192
5883c06f MD	193	TRACE_EMERG 0
5883c06f MD	194	system is unusable
a106a9f8	195
5883c06f MD	196	TRACE_ALERT 1
5883c06f MD	197	action must be taken immediately
a106a9f8	198
5883c06f MD	199	TRACE_CRIT 2
5883c06f MD	200	critical conditions
a106a9f8	201
5883c06f MD	202	TRACE_ERR 3
5883c06f MD	203	error conditions
a106a9f8	204
5883c06f MD	205	TRACE_WARNING 4
5883c06f MD	206	warning conditions
a106a9f8	207
5883c06f MD	208	TRACE_NOTICE 5
5883c06f MD	209	normal, but significant, condition
a106a9f8	210
5883c06f MD	211	TRACE_INFO 6
5883c06f MD	212	informational message
a106a9f8	213
5883c06f MD	214	TRACE_DEBUG_SYSTEM 7
5883c06f MD	215	debug information with system-level scope (set of programs)
a106a9f8	216
5883c06f MD	217	TRACE_DEBUG_PROGRAM 8
5883c06f MD	218	debug information with program-level scope (set of processes)
a106a9f8	219
5883c06f MD	220	TRACE_DEBUG_PROCESS 9
5883c06f MD	221	debug information with process-level scope (set of modules)
a106a9f8	222
5883c06f MD	223	TRACE_DEBUG_MODULE 10
	224	debug information with module (executable/library) scope (set of
	225	units)
a106a9f8	226
5883c06f MD	227	TRACE_DEBUG_UNIT 11
5883c06f MD	228	debug information with compilation unit scope (set of functions)
a106a9f8	229
5883c06f MD	230	TRACE_DEBUG_FUNCTION 12
5883c06f MD	231	debug information with function-level scope
a106a9f8	232
5883c06f MD	233	TRACE_DEBUG_LINE 13
5883c06f MD	234	debug information with line-level scope (TRACEPOINT_EVENT default)
a106a9f8	235
5883c06f MD	236	TRACE_DEBUG 14
	237	debug-level message (trace_printf default)
	238
	239	See lttng(1) for information on how to use LTTng-UST loglevels.
	240
	241	.fi
	242
eba411c6 MD	243	.SH "ADDING TRACEPOINTS TO YOUR CODE"
	244
	245	.nf
	246
	247	Include the provider header in each C files you plan to instrument,
	248	following the building/linking directives in the next section.
	249
	250	For instance, add within a function:
	251
	252	tracepoint(ust_tests_hello, tptest, i, netint, values,
	253	text, strlen(text), dbl, flt);
	254
	255	As a call to the tracepoint. It will only be activated when requested by
	256	lttng(1) through lttng-sessiond(8).
	257
d646ca64 MD	258	Even though LTTng-UST supports tracepoint() call site duplicates having
	259	the same provider and event name, it is recommended to use a
	260	provider event name pair only once within the source code to help
7c501923	261	map events back to their call sites when analyzing the trace.
eba411c6 MD	262	.fi
	263
	264	.SH "BUILDING/LINKING THE TRACEPOINT PROVIDER"
	265
	266	.nf
	267	There are 2 ways to compile the Tracepoint Provider with the
	268	application: either statically or dynamically. Please follow
	269	carefully:
	270
560753cb PP	271	1) Compile the Tracepoint Provider with the application, either
	272	directly or through a static library (.a):
	273	- Into exactly one object of your application, define
eba411c6	274	"TRACEPOINT_DEFINE" and include the tracepoint provider.
9b6435af	275	- Use "\-I." for the compilation unit containing the tracepoint
560753cb PP	276	provider include (e.g., tp.c).
560753cb PP	277	- Link the application with "\-llttng-ust" and "\-ldl".
eba411c6 MD	278	- Include the tracepoint provider header into all C files using
eba411c6 MD	279	the provider.
a106a9f8 JG	280	- Examples:
	281	- doc/examples/easy-ust/ sample.c sample_component_provider.h tp.c
	282	Makefile
	283	- doc/examples/hello-static-lib/ hello.c tp.c ust_test_hello.h Makefile
eba411c6 MD	284
	285	2) Compile the Tracepoint Provider separately from the application,
	286	using dynamic linking:
	287	- Into exactly one object of your application: define
	288	"TRACEPOINT_DEFINE" _and_ also define
	289	"TRACEPOINT_PROBE_DYNAMIC_LINKAGE", then include the tracepoint
	290	provider header.
	291	- Include the tracepoint provider header into all instrumented C
	292	files that use the provider.
9b6435af AM	293	- Compile the tracepoint provider with "\-I.".
	294	- Link the tracepoint provider with "\-llttng-ust".
	295	- Link application with "\-ldl".
eba411c6 MD	296	- Set a LD_PRELOAD environment to preload the tracepoint provider
eba411c6 MD	297	shared object before starting the application when tracing is
13fb2d2c JG	298	needed. Another way is to dlopen the tracepoint probe when needed
13fb2d2c JG	299	by the application.
eba411c6	300	- Example:
a106a9f8	301	- doc/examples/demo demo.c tp.c ust_tests_demo.h demo-trace Makefile
eba411c6	302
13fb2d2c JG	303	- Note about dlclose() usage: it is not safe to use dlclose on a
	304	provider shared object that is being actively used for tracing due
	305	to a lack of reference counting from lttng-ust to the used shared
	306	object.
eba411c6 MD	307	- Enable instrumentation and control tracing with the "lttng" command
eba411c6 MD	308	from lttng-tools. See lttng-tools doc/quickstart.txt.
2bda849d MD	309	- Note for C++ support: although an application instrumented with
	310	tracepoints can be compiled with g++, tracepoint probes should be
	311	compiled with gcc (only tested with gcc so far).
eba411c6 MD	312
	313	.fi
	314
0a7c55a5 MD	315	.SH "USING LTTNG UST WITH DAEMONS"
	316
	317	.nf
	318	Some extra care is needed when using liblttng-ust with daemon
	319	applications that call fork(), clone(), or BSD rfork() without a
	320	following exec() family system call. The library "liblttng-ust-fork.so"
	321	needs to be preloaded for the application (launch with e.g.
	322	LD_PRELOAD=liblttng-ust-fork.so appname).
	323
	324	.fi
	325
94c9c48d MD	326	.SH "CONTEXT"
	327
	328	.PP
	329	Context information can be prepended by the tracer before each, or some,
	330	events. The following context information is supported by LTTng-UST:
	331	.PP
	332
	333	.PP
	334	.IP "vtid"
	335	Virtual thread ID: thread ID as seen from the point of view of the
	336	process namespace.
	337	.PP
	338
	339	.PP
	340	.IP "vpid"
	341	Virtual process ID: process ID as seen from the point of view of the
	342	process namespace.
	343	.PP
	344
f6df8626 PW	345	.PP
	346	.IP "ip"
	347	Instruction pointer: Enables recording of the exact location where a tracepoint
	348	was emitted. Can be used to reverse-lookup the source location that caused the
	349	event to be emitted.
	350	.PP
	351
94c9c48d MD	352	.PP
	353	.IP "procname"
	354	Thread name, as set by exec() or prctl(). It is recommended that
	355	programs set their thread name with prctl() before hitting the first
	356	tracepoint for that thread.
	357	.PP
	358
	359	.PP
	360	.IP "pthread_id"
	361	Pthread identifier. Can be used on architectures where pthread_t maps
	362	nicely to an unsigned long type.
	363	.PP
	364
b11abb67	365	.SH "BASE ADDRESS STATEDUMP (Experimental feature)"
f6df8626 PW	366
f6df8626 PW	367	.PP
b11abb67 PW	368	Warning: This is an experimental feature known to cause deadlocks when the
	369	traced application uses fork, clone or daemon. Only use it for debugging and
	370	testing. Do NOT use it in production.
	371
f6df8626 PW	372	If an application that uses liblttng-ust.so becomes part of a session,
	373	information about its currently loaded shared objects will be traced to the
	374	session at session-enable time. To record this information, the following event
	375	needs to be enabled:
	376	.PP
	377	.IP "ust_baddr_statedump:soinfo"
	378	This event is used to trace a currently loaded shared object. The base address
	379	(where the dynamic linker has placed the shared object) is recorded in the
6d262185 MD	380	"baddr" field. The path to the shared object gets recorded in the
	381	"sopath" field (as string). The file size of the loaded object (in
	382	bytes) is recorded to the "size" field and its time of last modification
	383	(in seconds since Epoch) is recorded in the "mtime" field.
f6df8626	384	.PP
6d262185 MD	385	If the event above is enabled, a series of "ust_baddr_statedump:soinfo"
	386	events is recorded at session-enable time. It represents the state of
	387	currently loaded shared objects for the traced process. If this
	388	information gets combined with the lttng-ust-dl(3) instrumentation, all
	389	aspects of dynamic loading that are relevant for symbol and
	390	line number lookup are traced by LTTng.
f6df8626	391	.PP
eba411c6 MD	392	.SH "ENVIRONMENT VARIABLES"
	393
	394	.PP
	395	.IP "LTTNG_UST_DEBUG"
	396	Activate liblttng-ust debug output.
	397	.PP
	398	.IP "LTTNG_UST_REGISTER_TIMEOUT"
	399	The environment variable "LTTNG_UST_REGISTER_TIMEOUT" can be used to
	400	specify how long the applications should wait for sessiond
	401	"registration done" command before proceeding to execute the main
	402	program. The default is 3000ms (3 seconds). The timeout value is
	403	specified in milliseconds. The value 0 means "don't wait". The value
9b6435af	404	\-1 means "wait forever". Setting this environment variable to 0 is
eba411c6 MD	405	recommended for applications with time constraints on the process
	406	startup time.
	407	.PP
b11abb67 PW	408	.IP "LTTNG_UST_WITH_EXPERIMENTAL_BADDR_STATEDUMP"
b11abb67 PW	409	Experimentally allow liblttng-ust to perform a base-address statedump on session-enable.
f6df8626	410	.PP
eba411c6 MD	411
	412	.SH "SEE ALSO"
	413
	414	.PP
d1eaa4d7	415	lttng-gen-tp(1), lttng(1), babeltrace(1), lttng-ust-cyg-profile(3),
f6df8626	416	lttng-ust-dl(3), lttng-sessiond(8)
eba411c6	417	.PP
ff42aeef MD	418
	419	.SH "COMPATIBILITY"
	420
	421	.PP
	422	Older lttng-ust libraries reject more recent, and incompatible, probe
cf949d07	423	providers. Newer lttng-ust libraries accept older probe providers, even
ff42aeef MD	424	though some newer features might not be available with those providers.
	425	.PP
	426
eba411c6 MD	427	.SH "BUGS"
	428
	429	.PP
ff42aeef MD	430	LTTng-UST 2.0 and 2.1 lttng-ust libraries do not check for probe
	431	provider version compatibility. This can lead to out-of-bound accesses
	432	when using a more recent probe provider with an older lttng-ust library.
	433	These error only trigger when tracing is active. This issue has been
	434	fixed in LTTng-UST 2.2.
eba411c6 MD	435
	436	If you encounter any issues or usability problem, please report it on
	437	our mailing list <lttng-dev@lists.lttng.org> to help improve this
	438	project.
	439	.SH "CREDITS"
	440
	441	liblttng-ust is distributed under the GNU Lesser General Public License
	442	version 2.1. The headers are distributed under the MIT license.
	443	.PP
	444	See http://lttng.org for more information on the LTTng project.
	445	.PP
	446	Mailing list for support and development: <lttng-dev@lists.lttng.org>.
	447	.PP
	448	You can find us on IRC server irc.oftc.net (OFTC) in #lttng.
	449	.PP
	450	.SH "THANKS"
	451
	452	Thanks to Ericsson for funding this work, providing real-life use-cases,
	453	and testing.
	454
	455	Special thanks to Michel Dagenais and the DORSAL laboratory at
	456	Polytechnique de Montreal for the LTTng journey.
	457	.PP
	458	.SH "AUTHORS"
	459
	460	.PP
	461	liblttng-ust was originally written by Mathieu Desnoyers, with additional
	462	contributions from various other people. It is currently maintained by
	463	Mathieu Desnoyers <mathieu.desnoyers@efficios.com>.
	464	.PP