Commit | Line | Data |
---|---|---|
61403b54 DG |
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 | |
ceecb5ad DG |
12 | - v0.2: 07/08/2012 |
13 | * Remove lttng_create_session_addr | |
14 | * Describe URL string format | |
15 | * Add set_consumer_url examples | |
88927b06 DG |
16 | - v0.3: 14/08/2012 |
17 | * Change set_consumer_url by adding both control and data url. | |
61403b54 DG |
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 | ||
ceecb5ad | 33 | In order NOT to expose the new lttng_uri structure used to identify trace |
61403b54 DG |
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 | ||
ceecb5ad DG |
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. | |
61403b54 | 42 | |
ceecb5ad DG |
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: | |
61403b54 DG |
47 | --> lttng_create_session(const char *name, const char *path); |
48 | ||
ceecb5ad DG |
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 | |
61403b54 | 69 | |
ceecb5ad DG |
70 | For example, this URL results in writing the trace data in |
71 | "$USER/lttng-traces/<target_hostname>/foo/bar". | |
61403b54 | 72 | |
ceecb5ad | 73 | * net://hostname/foo/bar |
61403b54 | 74 | |
ceecb5ad DG |
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. | |
61403b54 | 79 | |
ceecb5ad DG |
80 | The <net(6)> protocol has a special case where the user can input two ports |
81 | respectively being the control and data port. | |
61403b54 | 82 | |
88927b06 | 83 | * net://[HOSTNAME|IP][:CTRL_PORT[:DATA_PORT]][/PATH] |
ceecb5ad DG |
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 | ||
88927b06 | 88 | 1) lttng_set_consumer_url(handle, url, url); |
ceecb5ad DG |
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). | |
61403b54 DG |
94 | |
95 | [*] Consumer: | |
96 | ||
ceecb5ad DG |
97 | This call is simply renamed. |
98 | ||
99 | From: | |
100 | --> lttng_set_consumer_uri(...) | |
61403b54 | 101 | |
ceecb5ad DG |
102 | To: |
103 | --> lttng_set_consumer_url(struct lttng_handle *handle, | |
88927b06 | 104 | const char *ctrl_url, const char *data_url); |
61403b54 | 105 | |
88927b06 DG |
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 | |
61403b54 DG |
112 | lttng_uri in the liblttng-ctl and sent to the session daemon. |
113 | ||
ceecb5ad DG |
114 | Example: |
115 | ||
88927b06 DG |
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"); | |
ceecb5ad DG |
120 | |
121 | ||
122 | With all this, the lttng_uri data structure will NOT be exposed to the public | |
61403b54 | 123 | API and the user command line interface. |