[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
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, 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:

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)
	)
)
.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
mapping 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.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 application with "\-ldl".
    - 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 "\-llttng-ust".
    - 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 "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
.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

.SH "SEE ALSO"

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