Add lttng URL proposal for the public API

[lttng-tools.git] / doc / proposals / 0004-lttng-address-api.txt

RFC - LTTng address API proposal

Author: David Goulet <david.goulet@efficios.com>

Contributors:
    * Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
	* Yannick Brosseau <yannick.brosseau@polymtl.ca>

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

Introduction
-----------------

This document proposes the use of string URLs to the command line interface and
API which will deprecate a function and propose new ones.

The purpose of this proposal is to support network streaming using URL string
format that you can find in proposal doc/proposals/0003-network.consumer.txt,
remove the lttng_uri structure from the API and integrate the URL string to the
API.

API
-----------------

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 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);

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".

	* net://hostname/foo/bar

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.

The <net(6)> protocol has a special case where the user can input two ports
respectively being the control and data port.

	* net://[HOSTNAME|IP][:CTRL_PORT][:DATA_PORT][/PATH]

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);
	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:

This call is simply renamed.

From:
--> lttng_set_consumer_uri(...)

To:
--> lttng_set_consumer_url(struct lttng_handle *handle,
				const char *url);

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.

Example:

	lttng_set_consumer_url(handle, "net://42.42.42.2");


With all this, the lttng_uri data structure will NOT be exposed to the public
API and the user command line interface.