Add lttng URL proposal for the public API
[lttng-tools.git] / 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
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
31 In order NOT to expose the new lttng_uri structure used to identify trace
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
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.
40
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:
45 --> lttng_create_session(const char *name, const char *path);
46
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
67
68 For example, this URL results in writing the trace data in
69 "$USER/lttng-traces/<target_hostname>/foo/bar".
70
71 * net://hostname/foo/bar
72
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.
77
78 The <net(6)> protocol has a special case where the user can input two ports
79 respectively being the control and data port.
80
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).
92
93 [*] Consumer:
94
95 This call is simply renamed.
96
97 From:
98 --> lttng_set_consumer_uri(...)
99
100 To:
101 --> lttng_set_consumer_url(struct lttng_handle *handle,
102 const char *url);
103
104 For both functions (consumer and create), the _url_ will be parsed into a
105 lttng_uri in the liblttng-ctl and sent to the session daemon.
106
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
113 API and the user command line interface.
This page took 0.047196 seconds and 4 git commands to generate.