trunk/lttv/doc/developer/ust.html

   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>
   7
   8 <h1>LTTng User-space Tracing Design</h1>
   9
  10 <p>
  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
  18 <p>
  19 When the instrumented application starts, a pipe is opened to allow external
  20 tracing control, asynchronous notification is requested when commands arrive in
  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:
  25
  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;
  33
  34 <p>
  35 The application may also spontaneously provide information to the pipe:
  36
  37 <li> a buffer is full;
  38 <li> new tracepoints or markers are appearing or disappearing, because modules are
  39   dynamically loaded or unloaded;
  40
  41 <p>
  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.
  45 <p>
  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.
  49 <a href="http://ltt.polymtl.ca/tracingwiki/index.php/DTrace">Dtrace information
  50 on the TracingWiki</a>) which uses a breakpoint to
  51 perform both dynamic and static user-space tracing. Performance comparison of
  52 a function call vs the int3 approach is available at
  53 <a href="http://sourceware.org/ml/systemtap/2006-q3/msg00793.html">Markers vs
  54 int3 performance comparison</a> (see "Conclusion").
  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
  60 <a
  61 href="http://ltt.polymtl.ca/svn/trunk/obsolete/ltt-usertrace/java/">here</a>
  62 for older LTTng versions.
  63
  64   </body>
  65 </html>