doc/live-reading-howto.txt

   1 LTTng Live trace reading how-to
   2
   3 Julien Desfossez
   4 September 27th, 2013
   5
   6 This document presents a summary on how to use the live trace reading feature
   7 introduced in LTTng 2.4. For the details about the protocol, please refer to
   8 the live-reading-protocol.txt document.
   9
  10 Live trace reading refers to the feature of reading the trace while it is being
  11 recorded. In order to do that, the trace must be streamed a relay even if the
  12 viewer is running on the same machine as the tracer.
  13
  14 So, the first thing to do is to start a lttng-relayd process. It can be
  15 anywhere on the network (including localhost) as long as the sessiond/consumerd
  16 and the viewer can communicate with it over TCP/IP.
  17
  18 $ lttng-relayd -d
  19
  20 Then, we can create a session configured for streaming with the new --live
  21 parameter.
  22
  23 $ lttng create --live 1000000 -U net://localhost
  24
  25 The --live parameter activates a session-wide timer (usec) that is responsible
  26 for checking at a user-defined rate if new data is available. If there is new
  27 data, it is flushed automatically, otherwise a beacon is sent to the relayd to
  28 inform it that the stream is currently empty and the viewer can ignore this
  29 stream up to a certain point in time.
  30
  31 Once the session is created, the user can activate events as usual.
  32
  33 In order to view the live trace, the viewer must implement the live-reading
  34 protocol.
  35
  36 For now, a basic client is available in the branch index2013 of the git
  37 repository :
  38 https://github.com/jdesfossez/babeltrace-dev.git
  39
  40 This client is still in heavy development and the branch will be rebased, it is
  41 only provided as a proof-of-concept and an exemple on how to use the protocol.
  42 Once compiled and installed, just run :
  43 $ test-live hostname 2>/dev/null
  44
  45 If you want to see all the debug, just get rid of "2>/dev/null".
  46 Once again, it is a client in development, the name is purposely bad and the
  47 debug output is relatively heavy.
  48
  49 Known viewer issues :
  50 - adding metadata on the fly (enabling events when a viewer is connected)
  51 - destroy not clean
  52 - aggressive polling when all the streams are inactive (after a lttng stop)
  53 - restart reading from the beginning (SEEK_LAST not implemented yet)