Commit | Line | Data |
---|---|---|
c0e668d0 DG |
1 | STREAMING |
2 | ---------------- | |
3 | ||
4 | [Last updated: 2012-07-17 by David Goulet] | |
5 | ||
50c47489 | 6 | This is a brief howto for network streaming feature of lttng 2.0 toolchain. |
c0e668d0 | 7 | |
ae403e46 | 8 | See the README.adoc file for installation procedure or use the various Linux |
c0e668d0 DG |
9 | distribution packages. |
10 | ||
11 | Terminology: | |
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 | ||
18 | Basics: | |
19 | ||
50c47489 | 20 | Here are the basic concepts of the new streaming component. We use two network |
c0e668d0 DG |
21 | ports for that called _control_ and _data_ respectively defined by default to |
22 | 5342 and 5343. | |
23 | ||
24 | The control port is where the commands AND metadata data are sent since this | |
50c47489 JD |
25 | stream is considered to be the reliable and priority transport channel. The |
26 | data port is the stream which transports the tracing raw data. | |
c0e668d0 DG |
27 | |
28 | In order to gather traces from the network, the remote machine MUST have a | |
29 | lttng-relayd running on it bound to network interfaces remotely reachable by the | |
30 | target. | |
31 | ||
32 | [remote] $ lttng-relayd -d | |
33 | (to daemonize) | |
34 | ||
35 | [remote] $ lttng-relayd -vvv | |
36 | (foreground with debug output) | |
37 | ||
50c47489 JD |
38 | [remote] $ lttng-relayd -C tcp://0.0.0.0:1234 -D tcp://0.0.0.0:5678 |
39 | (control port set to TCP/1234 and data port to TCP/5678 on all IP addresses) | |
40 | ||
41 | For now, only TCP is supported on IPv4/IPv6. | |
c0e668d0 DG |
42 | |
43 | Once done, the following examples shows you how to start streaming from the | |
44 | target machine to the remote host where we just started a lttng relay. | |
45 | ||
46 | Example 1: | |
47 | ---------------- | |
48 | ||
49 | Simple and quick network streaming. | |
50 | ||
e9711845 | 51 | 1) Create a recording session that will be streamed over the network for the |
c0e668d0 DG |
52 | specified domain. This session will contain, in our example, syscall events. |
53 | ||
54 | # lttng create syscall-session | |
55 | ||
56 | 2) Enable the consumer to send data over the network for the kernel domain. | |
57 | ||
58 | # lttng enable-consumer --kernel net://<remote_addr> | |
59 | ||
60 | You can also skip this step and directly use the lttng create command like so: | |
61 | ||
62 | # lttng create -U net://<remote_addr> syscall-session | |
63 | ||
64 | 3) Set and start the tracing. Nothing new here. | |
65 | ||
66 | # lttng enable-event -a --syscall -k | |
67 | # lttng start | |
68 | (wait and get coffee) | |
69 | # lttng stop | |
70 | ||
50c47489 JD |
71 | By default on the relay side, the trace will be written to the lttng-traces/ |
72 | directory of the relayd user in: | |
c0e668d0 DG |
73 | |
74 | hostname/session-name/kernel/* | |
75 | ||
50c47489 JD |
76 | The -o option of lttng-relayd allows the user to override the default output |
77 | path. | |
78 | ||
c0e668d0 DG |
79 | Just run babeltrace or lttng view -t PATH with the previous path. |
80 | ||
81 | Example 2: | |
82 | ---------------- | |
83 | ||
84 | This example uses all possible options to fine grained control the streaming. | |
85 | ||
e9711845 | 86 | 1) Again, create a recording session that will be streamed over the network for |
c0e668d0 DG |
87 | the specified domain. |
88 | ||
89 | # lttng create syscall-session | |
90 | ||
e9711845 | 91 | 2) Set relayd URIs for the recording session and kernel domain. |
c0e668d0 DG |
92 | |
93 | ONLY set the remote relayd URIs (both control and data at the same destination | |
94 | and using default ports) on the consumer but does not enable the consumer to use | |
95 | network streaming yet. | |
96 | ||
97 | # lttng enable-consumer -k -U net://<remote_addr> | |
98 | ||
99 | You can also set both control and data URIs using -C and -D respectively for | |
100 | that like so: | |
101 | ||
50c47489 | 102 | # lttng enable-consumer -k -C tcp://<remote_addr> -D tcp://<remote_addr> |
c0e668d0 DG |
103 | |
104 | 3) Enable the consumer previously setup with the relayd URIs. | |
105 | ||
106 | This enables the previous network destination. From this point on, the consumer | |
107 | is ready to stream once tracing is started. | |
108 | ||
109 | # lttng enable-consumer -k --enable | |
110 | ||
111 | 4) Set and start the tracing. Nothing new here. | |
112 | ||
113 | # lttng enable-event -a --syscall -k | |
114 | # lttng start | |
115 | (wait and get coffee) | |
116 | # lttng stop | |
117 | ||
50c47489 | 118 | Again, run babeltrace as mentioned in the previous example on the relayd side. |
c0e668d0 DG |
119 | |
120 | For more information, please read the --help options of each command or the man | |
121 | pages lttng(1) and the lttng-relayd(8) |