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