X-Git-Url: https://git.lttng.org/?p=lttng-tools.git;a=blobdiff_plain;f=doc%2Fproposals%2F0004-lttng-address-api.txt;h=88b20d0b79018a52f78fffdabbce69ffe4843613;hp=be15f582939fe50d543aeaa2a328639570a17818;hb=HEAD;hpb=61403b54c75c41dbadf2ba18ad2d54898a9043ad

diff --git a/doc/proposals/0004-lttng-address-api.txt b/doc/proposals/0004-lttng-address-api.txt
index be15f5829..88b20d0b7 100644
--- a/doc/proposals/0004-lttng-address-api.txt
+++ b/doc/proposals/0004-lttng-address-api.txt
@@ -9,6 +9,12 @@ Contributors:
 Version:
     - v0.1: 31/07/2012
         * Initial proposal
+	- v0.2: 07/08/2012
+		* Remove lttng_create_session_addr
+		* Describe URL string format
+		* Add set_consumer_url examples
+	- v0.3: 14/08/2012
+		* Change set_consumer_url by adding both control and data url.
 
 Introduction
 -----------------
@@ -24,50 +30,94 @@ API.
 API
 -----------------
 
-In order not to expose the new lttng_uri structure used to identify trace
+In order NOT to expose the new lttng_uri structure used to identify trace
 location for lttng consumer, the public API will only use string address where
 it will be converted in a lttng_uri and sent to the session daemon.
 
 [*] Create session:
 
-With the introduction of the enable-consumer command used for network streaming,
-the create session command has been modified so the user could define a consumer
-location either on the network or local with the command. This change deprecates
-the old API function and adds a new one.
+With the introduction of the enable-consumer command used for network
+streaming, the create session command has been modified so the user could
+define a consumer location either on the network or local with the command.
 
-Deprecated:
+This does NOT change the current API call but rather simply rename _path_ to
+_url_ and how it is used in the lttng-ctl library.
+
+Call changed from:
 --> lttng_create_session(const char *name, const char *path);
 
-Proposed:
---> lttng_create_session_addr(const char *name, const char *addr,
-								int enable_consumer);
+To:
+--> lttng_create_session(const char *name, const char *url);
+
+The _name_ argument is the session name and _url_ is a string representing the
+URL specified by the user which is define like so:
+
+PROTO://[HOSTNAME|IP][:PORT][/PATH]
+
+The proto supported at this stage are (6 means IPv6):
+
+	* net, net6, tcp, tcp6, file
+
+If the proto is NOT recognized, the string is considered to be a simple path on
+the local filesystem relative to the process CWD unless it starts with a "/".
+
+The PATH is relative to a subdirectory "hostname", under the remote relayd
+"virtual" root directory. This directory can be changed with the -o, --output
+option when starting the lttng-relayd. This default is at:
+
+	* $USER/lttng-traces
+
+For example, this URL results in writing the trace data in
+"$USER/lttng-traces/<target_hostname>/foo/bar".
 
-The _name_ argument is the session name and _addr_ is a string representing the
-URL specified by the user which looks like this:
+	* net://hostname/foo/bar
 
-PROTO://[HOST|IP][:PORT][/PATH]
+The PATH part can not be bigger than PATH_MAX (define in limits.h) which is
+4096 bytes at the time of this proposal. Moreover, "../" is ignored and
+removed. For instance, using "net://localhost/../../" will set the path to the
+default one.
 
-Examples:
+The <net(6)> protocol has a special case where the user can input two ports
+respectively being the control and data port.
 
-* net://myhostname
-* net://myhostname:9888
-* net://myhostname/foo/bar
-* net://X.X.X.X:9888/foo/bar
+	* net://[HOSTNAME|IP][:CTRL_PORT[:DATA_PORT]][/PATH]
 
-The enable_consumer option will disable the use of the consumer for the tracing
-session. This will be useful with the to come snapshot feature. The motivation
-behing this flag is to offer the same options as the enable-consumer command
-where you can only set the URI for the consumer and not enable it.
+If _url_ is not NULL, in addition to creating the session, the
+lttng_create_session will use the two following API calls:
+
+	1) lttng_set_consumer_url(handle, url, url);
+	2) lttng_enable_consumer(handle);
+
+If _url_ is NULL, then NO consumer is created for this tracing session and
+subsequent calls are needed to set up a consumer (i.e lttng_enable_consumer and
+lttng_set_consumer_url).
 
 [*] Consumer:
 
-The current lttng_set_consumer_uri(...) call will be changed to:
+This call is simply renamed.
+
+From:
+--> lttng_set_consumer_uri(...)
+
+To:
+--> lttng_set_consumer_url(struct lttng_handle *handle,
+				const char *ctrl_url, const char *data_url);
 
-lttng_set_consumer_addr(struct lttng_handle *handle,
-				const char *addr);
+For network streaming, we need two URL for the control and data stream. Using
+the net(6) protocol for the ctrl_url, the data_url argument is ignored. The
+_ctrl_url_ MUST never be NULL or else an error is returned. If the _data_url_
+is NULL, the ctrl url is used.
 
-For both functions (consumer and create), the addr will be translate to a
+For both functions (consumer and create), the _*url_ will be parsed into a
 lttng_uri in the liblttng-ctl and sent to the session daemon.
 
-With all this, the lttng_uri data structure will not be exposed to the public
+Example:
+
+	lttng_set_consumer_url(handle, "net://42.42.42.2", NULL);
+
+	lttng_set_consumer_url(handle, "tcp://42.42.42.2:8888",
+								"tcp://5.5.5.5:8812");
+
+
+With all this, the lttng_uri data structure will NOT be exposed to the public
 API and the user command line interface.