Fix: unchecked return value in trace_clock_read64_monotonic
[lttng-tools.git] / doc / proposals / 0004-lttng-address-api.txt
CommitLineData
61403b54
DG
1RFC - LTTng address API proposal
2
3Author: David Goulet <david.goulet@efficios.com>
4
5Contributors:
6 * Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
7 * Yannick Brosseau <yannick.brosseau@polymtl.ca>
8
9Version:
10 - v0.1: 31/07/2012
11 * Initial proposal
ceecb5ad
DG
12 - v0.2: 07/08/2012
13 * Remove lttng_create_session_addr
14 * Describe URL string format
15 * Add set_consumer_url examples
88927b06
DG
16 - v0.3: 14/08/2012
17 * Change set_consumer_url by adding both control and data url.
61403b54
DG
18
19Introduction
20-----------------
21
22This document proposes the use of string URLs to the command line interface and
23API which will deprecate a function and propose new ones.
24
25The purpose of this proposal is to support network streaming using URL string
26format that you can find in proposal doc/proposals/0003-network.consumer.txt,
27remove the lttng_uri structure from the API and integrate the URL string to the
28API.
29
30API
31-----------------
32
ceecb5ad 33In order NOT to expose the new lttng_uri structure used to identify trace
61403b54
DG
34location for lttng consumer, the public API will only use string address where
35it will be converted in a lttng_uri and sent to the session daemon.
36
37[*] Create session:
38
ceecb5ad
DG
39With the introduction of the enable-consumer command used for network
40streaming, the create session command has been modified so the user could
41define a consumer location either on the network or local with the command.
61403b54 42
ceecb5ad
DG
43This does NOT change the current API call but rather simply rename _path_ to
44_url_ and how it is used in the lttng-ctl library.
45
46Call changed from:
61403b54
DG
47--> lttng_create_session(const char *name, const char *path);
48
ceecb5ad
DG
49To:
50--> lttng_create_session(const char *name, const char *url);
51
52The _name_ argument is the session name and _url_ is a string representing the
53URL specified by the user which is define like so:
54
55PROTO://[HOSTNAME|IP][:PORT][/PATH]
56
57The proto supported at this stage are (6 means IPv6):
58
59 * net, net6, tcp, tcp6, file
60
61If the proto is NOT recognized, the string is considered to be a simple path on
62the local filesystem relative to the process CWD unless it starts with a "/".
63
64The PATH is relative to a subdirectory "hostname", under the remote relayd
65"virtual" root directory. This directory can be changed with the -o, --output
66option when starting the lttng-relayd. This default is at:
67
68 * $USER/lttng-traces
61403b54 69
ceecb5ad
DG
70For example, this URL results in writing the trace data in
71"$USER/lttng-traces/<target_hostname>/foo/bar".
61403b54 72
ceecb5ad 73 * net://hostname/foo/bar
61403b54 74
ceecb5ad
DG
75The PATH part can not be bigger than PATH_MAX (define in limits.h) which is
764096 bytes at the time of this proposal. Moreover, "../" is ignored and
77removed. For instance, using "net://localhost/../../" will set the path to the
78default one.
61403b54 79
ceecb5ad
DG
80The <net(6)> protocol has a special case where the user can input two ports
81respectively being the control and data port.
61403b54 82
88927b06 83 * net://[HOSTNAME|IP][:CTRL_PORT[:DATA_PORT]][/PATH]
ceecb5ad
DG
84
85If _url_ is not NULL, in addition to creating the session, the
86lttng_create_session will use the two following API calls:
87
88927b06 88 1) lttng_set_consumer_url(handle, url, url);
ceecb5ad
DG
89 2) lttng_enable_consumer(handle);
90
91If _url_ is NULL, then NO consumer is created for this tracing session and
92subsequent calls are needed to set up a consumer (i.e lttng_enable_consumer and
93lttng_set_consumer_url).
61403b54
DG
94
95[*] Consumer:
96
ceecb5ad
DG
97This call is simply renamed.
98
99From:
100--> lttng_set_consumer_uri(...)
61403b54 101
ceecb5ad
DG
102To:
103--> lttng_set_consumer_url(struct lttng_handle *handle,
88927b06 104 const char *ctrl_url, const char *data_url);
61403b54 105
88927b06
DG
106For network streaming, we need two URL for the control and data stream. Using
107the net(6) protocol for the ctrl_url, the data_url argument is ignored. The
108_ctrl_url_ MUST never be NULL or else an error is returned. If the _data_url_
109is NULL, the ctrl url is used.
110
111For both functions (consumer and create), the _*url_ will be parsed into a
61403b54
DG
112lttng_uri in the liblttng-ctl and sent to the session daemon.
113
ceecb5ad
DG
114Example:
115
88927b06
DG
116 lttng_set_consumer_url(handle, "net://42.42.42.2", NULL);
117
118 lttng_set_consumer_url(handle, "tcp://42.42.42.2:8888",
119 "tcp://5.5.5.5:8812");
ceecb5ad
DG
120
121
122With all this, the lttng_uri data structure will NOT be exposed to the public
61403b54 123API and the user command line interface.
This page took 0.050157 seconds and 4 git commands to generate.