Add lttng URL proposal for the public API
[lttng-tools.git] / doc / proposals / 0003-network.consumer.txt
CommitLineData
fa8f9c82
DG
1RFC - Network consumer
2
3Author: David Goulet <david.goulet@efficios.com>
4
5Contributors:
6 * Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
7 * Julien Desfossez <julien.desfossez@efficios.com>
8
9Version:
10 - v0.1: 16/04/2012
11 * Initial proposal
12 - v0.2: 04/05/2012
13 * Add snapshot description
14 * Propose a new API and lttng cli command
15 - v0.3: 23/07/2012
16 * Remove snapshot and focus only on network consumer for straming.
17
18Introduction
19-----------------
20
21This RFC proposes a way for the lttng 2.0 session daemon to handle network
22session for streaming purposes and eventually remote control.
23
24The next sections introduce the concept of network session and how it is
25envisioned in the lttng 2.0 toolchain.
26
27Please note that this RFC is neither final nor complete without the community
28feedbacks. The text below is a proposal.
29
30Network consumer
31-----------------
32
33For version 2.1 of lttngt-tools, we propose to add a network consumer which will
34be used for streaming.
35
36We allow to pass a full URI to the enable consumer command to override the
37current consumer or define a new one.
38
39We should at least support the following protocols:
40
41* net://HOST[:PORT_CTRL[:PORT_DATA]]
42* tcp://HOST:PORT
43* tcp6://HOST:PORT
44* udp://HOST:PORT
45* udp6://HOST:PORT
46* file://
47
48The net:// URI scheme makes the control and data stream use the default
49transport protocol which is TCP. The same remote host is also
50used for both. The ports can be specified and if not the defaults are used which
51are 5342 for control and 5343 for data.
52
53If URI not recognized, we use the arguments as a file name (same behavior as
54using file:///).
55
56The control and data stream are two separate arguments of the API since we allow
57the user to control the protocol and path (address). However, for a transfer to
58succeed, the lttng-sessiond and the remote end must establish a session for the
59control _and_ data path. If one fails to do so, the procedure is aborted. Thus,
60a different address for the control path from the data path is allowed but the
61user has to make sure that both communication channels end up at the same
62physical destination.
63
64Note that the control path is a crucial and high priority channel of
65communication so for now we only allow it to use the TCP protocol.
66
67Session with Network Transport
68-----------------
69
70In order to tell the session daemon where to send the data for streaming, a
71tracing session has to be aware of some information of the remote target.
72
73 * Remote end network address (Ex: IP or Hostname)
74 * Destination control port
75 * Destination data port
76
77Streaming can be initiated by telling the session daemon that a specific session
78is set for network streaming. This will make the session daemon establish a
79connection with the remote end. Once tracing starts, the local consumer will be
80made aware of this information and will start sending data following a strict
81protocol defined in the streaming RFC written by Julien Desfossez.
82
83Finally, a trace received by a network consumer will have a new "namespace"
84prepended to the trace output directory hierarchy: the hostname from _where_ the
85trace is coming from.
86
87host01
88\-- my_session1
89 \-- ust
90 \-- my_app1[...]
91 \-- trace data...
92 \-- kernel
93 \-- trace data...
94
95Client API integration
96-----------------
97
98Adding an API call to set attributes such as network information to a session.
99Since lttng_create_session only takes a name and a path, a new call is required
100to pass this information. The naming convention is NOT final and can be
101improved.
102
103struct lttng_handle handle;
104
105enum lttng_dst_type {
106 LTTNG_DST_IPV4,
107 LTTNG_DST_IPV6,
108 LTTNG_DST_HOST,
109 LTTNG_DST_PATH,
110};
111
112enum lttng_uri_type {
113 LTTNG_URI_HOP,
114 LTTNG_URI_DST,
115};
116
117enum lttng_stream_type {
118 LTTNG_STREAM_CONTROL,
119 LTTNG_STREAM_DATA
120};
121
122enum lttng_proto_type {
123 LTTNG_UDP,
124 LTTNG_TCP,
125};
126
127#define LTTNG_NETWORK_PADDING1_LEN 32
128#define LTTNG_NETWORK_PADDING2_LEN 128
129struct lttng_uri {
130 enum lttng_dst_type dtype;
131 enum lttng_uri_type utype;
132 enum lttng_stream_type stype;
133 enum lttng_proto proto;
134 in_port_t port;
135 char padding[LTTNG_NETWORK_PADDING1_LEN];
136 char subdir[PATH_MAX];
137 union {
138 char ipv4[INET_ADDRSTRLEN];
139 char ipv6[INET6_ADDRSTRLEN];
140 char path[PATH_NAME];
141 char padding[LTTNG_NETWORK_PADDING2_LEN];
142 } dst;
143};
144
145/* Set URI in the consumer template*/
146lttng_set_consumer_uri(handle, struct lttng_uri *u);
147
148
149/*
150 * Enable consumer template for the session. Once enabled, no more URI setting
151 * are possible for that specific consumer.
152 */
153lttng_enable_consumer(handle);
154
155/*
156 * Disable the consumer means that the consumer will stop consuming but will
157 * still be exist. Executing the enable_consumer call again will simply re
158 * enable it.
159 */
160lttng_disable_consumer(handle);
161
162If lttng_set_consumer_uri is executed on a session which already has a network
163consumer attached to it, the present consumer is freed and a new template is
164added.
165
166We propose to add two commands to the lttng command line actions:
167
168i) lttng enable-consumer [URI] [OPTIONS]
169 -s SESSION_NAME
170 -C, --control-uri=[HOP1,]URI
171 -D, --data-uri=[HOP1,]URI
172
173ii) lttng disable-consumer
174 -s SESSION_NAME
175
176Each option defining URI(s) can contains a list of hops preceeding the final
177destination. However, the proxy feature is still not supported but we prefer to
178inform the community of is future existence.
179
180So, the regular chain of command to enable a network consumer would be:
181
182# lttng create session1
183// The command sets the destination but uses the default protocols and ports.
184# lttng enable-consumer net://192.168.1.10
185# lttng enable-event -a -k
186# lttng start
187(tracing...)
188# lttng stop
189
190(This example considers that there is a lttng-relayd on the remote end.)
191
192Session daemon integration
193-----------------
194
195As mentioned earlier, the session daemon will be in charge of establishing a
196streaming session with the target over the network i.e. creating the control and
197data path bidirectional socket. Once done, a network consumer is spawned and
198those sockets are passed over.
199
200From there, the session daemon can interact with the consumer by stopping the
201network streaming or re-establishing a local trace collection with a non network
202consumer.
This page took 0.042876 seconds and 4 git commands to generate.