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