From 61403b54c75c41dbadf2ba18ad2d54898a9043ad Mon Sep 17 00:00:00 2001 From: David Goulet Date: Tue, 31 Jul 2012 12:40:01 -0400 Subject: [PATCH] Add lttng address API proposal. Initial import Signed-off-by: David Goulet --- doc/proposals/0004-lttng-address-api.txt | 73 ++++++++++++++++++++++++ 1 file changed, 73 insertions(+) create mode 100644 doc/proposals/0004-lttng-address-api.txt diff --git a/doc/proposals/0004-lttng-address-api.txt b/doc/proposals/0004-lttng-address-api.txt new file mode 100644 index 000000000..be15f5829 --- /dev/null +++ b/doc/proposals/0004-lttng-address-api.txt @@ -0,0 +1,73 @@ +RFC - LTTng address API proposal + +Author: David Goulet + +Contributors: + * Mathieu Desnoyers + * Yannick Brosseau + +Version: + - v0.1: 31/07/2012 + * Initial proposal + +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 change deprecates +the old API function and adds a new one. + +Deprecated: +--> lttng_create_session(const char *name, const char *path); + +Proposed: +--> lttng_create_session_addr(const char *name, const char *addr, + int enable_consumer); + +The _name_ argument is the session name and _addr_ is a string representing the +URL specified by the user which looks like this: + +PROTO://[HOST|IP][:PORT][/PATH] + +Examples: + +* net://myhostname +* net://myhostname:9888 +* net://myhostname/foo/bar +* net://X.X.X.X:9888/foo/bar + +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. + +[*] Consumer: + +The current lttng_set_consumer_uri(...) call will be changed to: + +lttng_set_consumer_addr(struct lttng_handle *handle, + const char *addr); + +For both functions (consumer and create), the addr will be translate to 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 +API and the user command line interface. -- 2.34.1