doc/proposals/0004-lttng-address-api.txt

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