Add streaming howto
[lttng-tools.git] / doc / streaming-howto.txt
CommitLineData
c0e668d0
DG
1STREAMING
2----------------
3
4[Last updated: 2012-07-17 by David Goulet]
5
6This is a brief howto for network streaming< feature of lttng 2.0 toolchain.
7
8See the README file for installation procedure or use the various Linux
9distribution packages.
10
11Terminology:
12
13 * The "target" is the traced machine (either UST or/and kernel tracer)
14
15 * The "remote" is the machine that receives the traces over network
16 streaming transport layer.
17
18Basics:
19
20Here are the basics concept of the new streaming component. We use two network
21ports for that called _control_ and _data_ respectively defined by default to
225342 and 5343.
23
24The control port is where the commands AND metadata data are sent since this
25stream is considered to be the reliable and prioritize transport channel. The
26data port is the stream with all the tracing raw data.
27
28In order to gather traces from the network, the remote machine MUST have a
29lttng-relayd running on it bound to network interfaces remotely reachable by the
30target.
31
32[remote] $ lttng-relayd -d
33(to daemonize)
34
35[remote] $ lttng-relayd -vvv
36(foreground with debug output)
37
38[remote] $ lttng-relayd -C 1234 -D 5678
39(control port set to 1234 and data port to 5678)
40
41Once done, the following examples shows you how to start streaming from the
42target machine to the remote host where we just started a lttng relay.
43
44Example 1:
45----------------
46
47Simple and quick network streaming.
48
491) Create a tracing session that will be streamed over the network for the
50specified domain. This session will contain, in our example, syscall events.
51
52 # lttng create syscall-session
53
542) Enable the consumer to send data over the network for the kernel domain.
55
56 # lttng enable-consumer --kernel net://<remote_addr>
57
58 You can also skip this step and directly use the lttng create command like so:
59
60 # lttng create -U net://<remote_addr> syscall-session
61
623) Set and start the tracing. Nothing new here.
63
64 # lttng enable-event -a --syscall -k
65 # lttng start
66 (wait and get coffee)
67 # lttng stop
68
69On the relay side, the trace will be written to the lttng-traces/ directory of
70the relayd user in:
71
72 hostname/session-name/kernel/*
73
74Just run babeltrace or lttng view -t PATH with the previous path.
75
76Example 2:
77----------------
78
79This example uses all possible options to fine grained control the streaming.
80
811) Again, create a tracing session that will be streamed over the network for
82the specified domain.
83
84 # lttng create syscall-session
85
862) Set relayd URIs for the tracing session and kernel domain.
87
88ONLY set the remote relayd URIs (both control and data at the same destination
89and using default ports) on the consumer but does not enable the consumer to use
90network streaming yet.
91
92 # lttng enable-consumer -k -U net://<remote_addr>
93
94You can also set both control and data URIs using -C and -D respectively for
95that like so:
96
97 # lttng enable-consumer -k -C tcp://<remote_addr>-D tcp://<remote_addr>
98
993) Enable the consumer previously setup with the relayd URIs.
100
101This enables the previous network destination. From this point on, the consumer
102is ready to stream once tracing is started.
103
104 # lttng enable-consumer -k --enable
105
1064) Set and start the tracing. Nothing new here.
107
108 # lttng enable-event -a --syscall -k
109 # lttng start
110 (wait and get coffee)
111 # lttng stop
112
113Again, run babeltrace as mention in the previous example on the relayd side.
114
115For more information, please read the --help options of each command or the man
116pages lttng(1) and the lttng-relayd(8)
This page took 0.050292 seconds and 4 git commands to generate.