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

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
  <title>LTTng User-space Tracing Design</title>
</head>
  <body>

<h1>LTTng User-space Tracing Design</h1>

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

<p>
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:

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

<p>
The application may also spontaneously provide information to the pipe:

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

<p>
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.
<p>
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.
<a href="http://ltt.polymtl.ca/tracingwiki/index.php/DTrace">Dtrace information
on the TracingWiki</a>) 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
<a href="http://sourceware.org/ml/systemtap/2006-q3/msg00793.html">Markers vs
int3 performance comparison</a> (see "Conclusion").

Tracing of Java application is planned to be done through a JNI interface.
Linking standard low-level C tracing library to the application within a JNI
adaptation class will be required to trace Java events. This has been prototyped
in the past. The work is available here for older LTTng versions : <a
href="http://ltt.polymtl.ca/svn/trunk/obsolete/ltt-usertrace/java/"</a>

  </body>
</html>
Commit	Line	Data
ca3fb06a	1	<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
	2	<html>
	3	<head>
	4	<title>LTTng User-space Tracing Design</title>
	5	</head>
	6	<body>
d4c85b6e	7
ca3fb06a	8	<h1>LTTng User-space Tracing Design</h1>
	9
	10	<p>
d4c85b6e	11	A user-space application may contain static instrumentation, and be linked with
	12	an associated runtime library, in order to produce an execution trace. User
	13	space Tracepoints and Markers, analogous to Kernel Tracepoints and Markers,
	14	define program locations and arguments provided. Probes may then be connected to
	15	each Tracepoint and Marker before they are activated. The probes will typically
	16	call LTTng user-space event writing functions.
	17
ca3fb06a	18	<p>
d4c85b6e	19	When the instrumented application starts, a pipe is opened to allow external
d4c85b6e	20	tracing control, asynchronous notification is requested when commands arrive in
9a192a69	21	the pipe, and a signal handler is installed for SIGIO (or a carefully chosen
	22	chainable signal number). Every time such signal is received, the runtime
	23	library checks for commands received on the external tracing control pipe. The
	24	recognized commands are:
d4c85b6e	25
ca3fb06a	26	<li> list the available Markers and Tracepoints;
	27	<li> dynamically load a library (presumably containing probes to connect);
	28	<li> connect a probe to a Tracepoint or Marker;
	29	<li> activate a Tracepoint or Marker;
	30	<li> initialize the tracing buffers;
	31	<li> flush the tracing buffers;
	32	<li> finalize the tracing buffers;
d4c85b6e	33
ca3fb06a	34	<p>
d4c85b6e	35	The application may also spontaneously provide information to the pipe:
d4c85b6e	36
ca3fb06a	37	<li> a buffer is full;
ca3fb06a	38	<li> new tracepoints or markers are appearing or disappearing, because modules are
d4c85b6e	39	dynamically loaded or unloaded;
d4c85b6e	40
ca3fb06a	41	<p>
d4c85b6e	42	In addition, the tracing control application should be notified when the
	43	application exits (to save the content of buffers if the application is
	44	crashing). Such notification may be obtained through utrace.
ca3fb06a	45	<p>
14b9349e	46	This tracing scheme plans to use a direct function call to tracing into buffers
	47	mapped in user-space. This should be an order of magnitude faster than the
	48	current Dtrace implementation (c.f.
9dd3d20d	49	<a href="http://ltt.polymtl.ca/tracingwiki/index.php/DTrace">Dtrace information
9dd3d20d	50	on the TracingWiki</a>) which uses a breakpoint to
14b9349e	51	perform both dynamic and static user-space tracing. Performance comparison of
14b9349e	52	a function call vs the int3 approach is available at
9dd3d20d	53	<a href="http://sourceware.org/ml/systemtap/2006-q3/msg00793.html">Markers vs
9dd3d20d	54	int3 performance comparison</a> (see "Conclusion").
e6f8d5e6	55
	56	Tracing of Java application is planned to be done through a JNI interface.
	57	Linking standard low-level C tracing library to the application within a JNI
	58	adaptation class will be required to trace Java events. This has been prototyped
	59	in the past. The work is available here for older LTTng versions : <a
7f3d7e4f	60	href="http://ltt.polymtl.ca/svn/trunk/obsolete/ltt-usertrace/java/"</a>
e6f8d5e6	61
ca3fb06a	62	</body>
ca3fb06a	63	</html>