RFC - LTTng address API proposal Author: David Goulet Contributors: * Mathieu Desnoyers * Yannick Brosseau 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 ----------------- 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//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 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, 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 *ctrl_url, const char *data_url); 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 _*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", 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.