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