[lttv.git] / trunk / lttv / doc / developer / ust.txt

LTTng User-space Tracing Design

A user-space application may contain static instrumentation, and be linked with
an associated runtime library, in order to produce an execution trace. User
space Tracepoints and Markers, analogous to Kernel Tracepoints and Markers,
define program locations and arguments provided. Probes may then be connected to
each Tracepoint and Marker before they are activated. The probes will typically
call LTTng user-space event writing functions.

When the instrumented application starts, a pipe is opened to allow external
tracing control, asynchronous notification is requested when commands arrive in
the pipe, and a signal handler is installed for SIGIO (or a carefully chosen
chainable signal number). Every time such signal is received, the runtime
library checks for commands received on the external tracing control pipe. The
recognized commands are:

- list the available Markers and Tracepoints;
- dynamically load a library (presumably containing probes to connect);
- connect a probe to a Tracepoint or Marker;
- activate a Tracepoint or Marker;
- initialize the tracing buffers;
- flush the tracing buffers;
- finalize the tracing buffers;

The application may also spontaneously provide information to the pipe:

- a buffer is full;
- new tracepoints or markers are appearing or disappearing, because modules are
  dynamically loaded or unloaded;

In addition, the tracing control application should be notified when the
application exits (to save the content of buffers if the application is
crashing). Such notification may be obtained through utrace.

This tracing scheme plans to use a direct function call to tracing into buffers
mapped in user-space. This should be an order of magnitude faster than the
current Dtrace implementation (c.f.
https://ltt.polymtl.ca/tracingwiki/index.php/DTrace) which uses a breakpoint to
perform both dynamic and static user-space tracing. Performance comparison of
a function call vs the int3 approach is available at
http://sourceware.org/ml/systemtap/2006-q3/msg00793.html (see "Conclusion").
Commit	Line	Data
d4c85b6e	1	LTTng User-space Tracing Design
	2
	3	A user-space application may contain static instrumentation, and be linked with
	4	an associated runtime library, in order to produce an execution trace. User
	5	space Tracepoints and Markers, analogous to Kernel Tracepoints and Markers,
	6	define program locations and arguments provided. Probes may then be connected to
	7	each Tracepoint and Marker before they are activated. The probes will typically
	8	call LTTng user-space event writing functions.
	9
	10	When the instrumented application starts, a pipe is opened to allow external
	11	tracing control, asynchronous notification is requested when commands arrive in
9a192a69	12	the pipe, and a signal handler is installed for SIGIO (or a carefully chosen
	13	chainable signal number). Every time such signal is received, the runtime
	14	library checks for commands received on the external tracing control pipe. The
	15	recognized commands are:
d4c85b6e	16
	17	- list the available Markers and Tracepoints;
	18	- dynamically load a library (presumably containing probes to connect);
	19	- connect a probe to a Tracepoint or Marker;
	20	- activate a Tracepoint or Marker;
	21	- initialize the tracing buffers;
	22	- flush the tracing buffers;
	23	- finalize the tracing buffers;
	24
	25	The application may also spontaneously provide information to the pipe:
	26
	27	- a buffer is full;
	28	- new tracepoints or markers are appearing or disappearing, because modules are
	29	dynamically loaded or unloaded;
	30
	31	In addition, the tracing control application should be notified when the
	32	application exits (to save the content of buffers if the application is
	33	crashing). Such notification may be obtained through utrace.
14b9349e	34
	35	This tracing scheme plans to use a direct function call to tracing into buffers
	36	mapped in user-space. This should be an order of magnitude faster than the
	37	current Dtrace implementation (c.f.
	38	https://ltt.polymtl.ca/tracingwiki/index.php/DTrace) which uses a breakpoint to
	39	perform both dynamic and static user-space tracing. Performance comparison of
	40	a function call vs the int3 approach is available at
	41	http://sourceware.org/ml/systemtap/2006-q3/msg00793.html (see "Conclusion").
	42