common: move copy_filter_bytecode to bytecode.c and rename it
[lttng-tools.git] / doc / streaming-howto.txt
CommitLineData
c0e668d0
DG
1STREAMING
2----------------
3
4[Last updated: 2012-07-17 by David Goulet]
5
50c47489 6This is a brief howto for network streaming feature of lttng 2.0 toolchain.
c0e668d0 7
ae403e46 8See the README.adoc file for installation procedure or use the various Linux
c0e668d0
DG
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
50c47489 20Here are the basic concepts of the new streaming component. We use two network
c0e668d0
DG
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
50c47489
JD
25stream is considered to be the reliable and priority transport channel. The
26data port is the stream which transports the tracing raw data.
c0e668d0
DG
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
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
41For now, only TCP is supported on IPv4/IPv6.
c0e668d0
DG
42
43Once done, the following examples shows you how to start streaming from the
44target machine to the remote host where we just started a lttng relay.
45
46Example 1:
47----------------
48
49Simple and quick network streaming.
50
511) Create a tracing session that will be streamed over the network for the
52specified domain. This session will contain, in our example, syscall events.
53
54 # lttng create syscall-session
55
562) 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
643) 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
71By default on the relay side, the trace will be written to the lttng-traces/
72directory of the relayd user in:
c0e668d0
DG
73
74 hostname/session-name/kernel/*
75
50c47489
JD
76The -o option of lttng-relayd allows the user to override the default output
77path.
78
c0e668d0
DG
79Just run babeltrace or lttng view -t PATH with the previous path.
80
81Example 2:
82----------------
83
84This example uses all possible options to fine grained control the streaming.
85
861) Again, create a tracing session that will be streamed over the network for
87the specified domain.
88
89 # lttng create syscall-session
90
912) Set relayd URIs for the tracing session and kernel domain.
92
93ONLY set the remote relayd URIs (both control and data at the same destination
94and using default ports) on the consumer but does not enable the consumer to use
95network streaming yet.
96
97 # lttng enable-consumer -k -U net://<remote_addr>
98
99You can also set both control and data URIs using -C and -D respectively for
100that like so:
101
50c47489 102 # lttng enable-consumer -k -C tcp://<remote_addr> -D tcp://<remote_addr>
c0e668d0
DG
103
1043) Enable the consumer previously setup with the relayd URIs.
105
106This enables the previous network destination. From this point on, the consumer
107is ready to stream once tracing is started.
108
109 # lttng enable-consumer -k --enable
110
1114) 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 118Again, run babeltrace as mentioned in the previous example on the relayd side.
c0e668d0
DG
119
120For more information, please read the --help options of each command or the man
121pages lttng(1) and the lttng-relayd(8)
This page took 0.077031 seconds and 4 git commands to generate.