Add lttng address API proposal. Initial import
[lttng-tools.git] / doc / proposals / 0004-lttng-address-api.txt
CommitLineData
61403b54
DG
1RFC - LTTng address API proposal
2
3Author: David Goulet <david.goulet@efficios.com>
4
5Contributors:
6 * Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
7 * Yannick Brosseau <yannick.brosseau@polymtl.ca>
8
9Version:
10 - v0.1: 31/07/2012
11 * Initial proposal
12
13Introduction
14-----------------
15
16This document proposes the use of string URLs to the command line interface and
17API which will deprecate a function and propose new ones.
18
19The purpose of this proposal is to support network streaming using URL string
20format that you can find in proposal doc/proposals/0003-network.consumer.txt,
21remove the lttng_uri structure from the API and integrate the URL string to the
22API.
23
24API
25-----------------
26
27In order not to expose the new lttng_uri structure used to identify trace
28location for lttng consumer, the public API will only use string address where
29it will be converted in a lttng_uri and sent to the session daemon.
30
31[*] Create session:
32
33With the introduction of the enable-consumer command used for network streaming,
34the create session command has been modified so the user could define a consumer
35location either on the network or local with the command. This change deprecates
36the old API function and adds a new one.
37
38Deprecated:
39--> lttng_create_session(const char *name, const char *path);
40
41Proposed:
42--> lttng_create_session_addr(const char *name, const char *addr,
43 int enable_consumer);
44
45The _name_ argument is the session name and _addr_ is a string representing the
46URL specified by the user which looks like this:
47
48PROTO://[HOST|IP][:PORT][/PATH]
49
50Examples:
51
52* net://myhostname
53* net://myhostname:9888
54* net://myhostname/foo/bar
55* net://X.X.X.X:9888/foo/bar
56
57The enable_consumer option will disable the use of the consumer for the tracing
58session. This will be useful with the to come snapshot feature. The motivation
59behing this flag is to offer the same options as the enable-consumer command
60where you can only set the URI for the consumer and not enable it.
61
62[*] Consumer:
63
64The current lttng_set_consumer_uri(...) call will be changed to:
65
66lttng_set_consumer_addr(struct lttng_handle *handle,
67 const char *addr);
68
69For both functions (consumer and create), the addr will be translate to a
70lttng_uri in the liblttng-ctl and sent to the session daemon.
71
72With all this, the lttng_uri data structure will not be exposed to the public
73API and the user command line interface.
This page took 0.03493 seconds and 4 git commands to generate.