LTTng address API proposal v3

RFC Mathieu Desnoyers 4 participants 5 messages Aug 7, 2012 – Aug 8, 2012 4 messages not in the archive

lore

Share & tools

lore

Mathieu Desnoyers

author

2012-08-07 19:19 UTC #1 lore raw

In reply to a message not in the archive

Quoted 72 lines · * David Goulet ([email protected]) wrote:

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA512
After a discussion with Mathieu and Yannick, here is some big changes.
I hope I did not forget anything important.
Cheers!
David
-----BEGIN PGP SIGNATURE-----
iQEcBAEBCgAGBQJQIWfcAAoJEELoaioR9I02SAkH/iic+EYwOs5dw0X+yS37sBrp rbP8VHm+v7OP4Lc+x84pfHBnz0pk5qM7MN5/lmMpRfRwCiYNW8CbxC13V5Au6UgC PsNQdZGduVb56xmB5zhV1cD1laiU2W+0vdQzahIN0YDDZowYa6uJda9yjav/b6z8 +duI2Zuw9NPOUnIDCSIpb3hKA4NZIZFsQGn+/IToikqWyRt/4wwiufaZNtlC85/w C0pGJL/9TBTY4rFmyZ/e19lJRUoNEygrFRRoJb5qxKWH5nHvfRXdFGw78xjDgim7 g9AvrWZ7g73KZaS7LEpmAcofgRicWafIMd0+jUXv0MMrj3NeT/xD66UbtcUusl8= =jRvr
-----END PGP SIGNATURE-----
RFC - LTTng address API proposal
Author: David Goulet <[email protected]>
Contributors:
* Mathieu Desnoyers <[email protected]>
* Yannick Brosseau <[email protected]>
Version:
- v0.1: 31/07/2012
* Initial proposal
- v0.2: 07/08/0212
* Remove lttng_create_session_addr
* Describe URL string format
* Add set_consumer_url examples
Introduction
-----------------
This document proposes the use of string URLs to the command line interface and API which will deprecate a function and propose new ones.
The purpose of this proposal is to support network streaming using URL string format that you can find in proposal doc/proposals/0003-network.consumer.txt, remove the lttng_uri structure from the API and integrate the URL string to the API.
API
-----------------
In order NOT to expose the new lttng_uri structure used to identify trace location for lttng consumer, the public API will only use string address where it will be converted in a lttng_uri and sent to the session daemon.
[*] Create session:
With the introduction of the enable-consumer command used for network streaming, the create session command has been modified so the user could define a consumer location either on the network or local with the command.
This does NOT change the current API call but rather simply rename _path_ to _url_ and how it is used in the lttng-ctl library.
Call changed from:
--> lttng_create_session(const char *name, const char *path);
To:
--> lttng_create_session(const char *name, const char *url);
The _name_ argument is the session name and _url_ is a string representing the URL specified by the user which is define like so:

Quoted 8 lines

PROTO://[HOSTNAME|IP][:PORT][/PATH]
The proto supported at this stage are (6 means IPv6):
* net, net6, tcp, tcp6, file
If the proto is NOT recognized, the string is considered to be a simple path on the local filesystem.

you could specify that it is a path relative to the process CWD (unless it starts with a /).

Quoted 3 lines

The PATH section is the destination path on the _remote_ host where the trace data will be written with the <target_hostname> append after.

The last sentence is not clear (after reading it 2-3 times, it's still not obvious what it explains).

Simply saying that the PATH is relative to a subdirectory "hostname", under the remote relayd "virtual" root directory, might be enough.

Quoted 2 lines

The relayd
defines a default location

... for its virtual root directory...

Quoted 15 lines

if none is given using the -o, --output option. This default is at:
* $USER/lttng-traces
For example, this URL results in writing the trace data in "$USER/lttng-traces/<target_hostname>/foo/bar".
* net://hostname/foo/bar
The PATH part can not be bigger than PATH_MAX (define in limits.h) which is 4096 bytes at the time of this proposal. Moreover, "../" is ignored and removed. For instance, using "net://localhost/../../" will set the path to the default one.

Quoted 6 lines

The <net(6)> protocol has a special case where the user can input two ports respectively being the control and data port.
* net://[HOSTNAME|IP][:CTRL_PORT][:DATA_PORT][/PATH]
If _url_ is not NULL, the lttng_create_session will use two API calls.

If _url_ is not NULL, in addition to creating the session, the lttng_create_session will use the two following API calls:

Quoted 22 lines

1) lttng_set_consumer_url(handle, url);
2) lttng_enable_consumer(handle);
If _url_ is NULL, then NO consumer is created for this tracing session and subsequent calls are needed to set up a consumer (i.e lttng_enable_consumer and lttng_set_consumer_url).
[*] Consumer:
This call is simply renamed.
From:
--> lttng_set_consumer_uri(...)
To:
--> lttng_set_consumer_url(struct lttng_handle *handle,
				const char *url);
For both functions (consumer and create), the _url_ will be parsed into a lttng_uri in the liblttng-ctl and sent to the session daemon.

Quoted 7 lines

Example:
	lttng_set_consumer_url(handle, "net://42.42.42.2");
With all this, the lttng_uri data structure will NOT be exposed to the public API and the user command line interface.

The rest looks good!

Thanks,

Mathieu

Quoted 4 lines

_______________________________________________
lttng-dev mailing list
[email protected]
http://lists.lttng.org/cgi-bin/mailman/listinfo/lttng-dev

Signature · 4 lines

Mathieu Desnoyers
Operating System Efficiency R&D Consultant
EfficiOS Inc.
http://www.efficios.com

David Goulet

2012-08-07 19:21 UTC #3 lore raw

In reply to a message not in the archive

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA512

Mathieu Desnoyers:

Quoted 61 lines

* David Goulet ([email protected]) wrote: After a discussion with Mathieu and Yannick, here is some big changes.
I hope I did not forget anything important.
Cheers! David
Quoted 54 lines
RFC - LTTng address API proposal
Author: David Goulet <[email protected]>
Contributors: * Mathieu Desnoyers <[email protected]> * Yannick Brosseau <[email protected]>
Version: - v0.1: 31/07/2012 * Initial proposal - v0.2:
07/08/0212 * Remove lttng_create_session_addr * Describe URL string format * Add set_consumer_url examples
Introduction -----------------
This document proposes the use of string URLs to the command line interface and API which will deprecate a function and propose new ones.
The purpose of this proposal is to support network streaming using URL string format that you can find in proposal doc/proposals/0003-network.consumer.txt, remove the lttng_uri structure from the API and integrate the URL string to the API.
API -----------------
In order NOT to expose the new lttng_uri structure used to identify trace location for lttng consumer, the public API will only use string address where it will be converted in a lttng_uri and sent to the session daemon.
[*] Create session:
With the introduction of the enable-consumer command used for network streaming, the create session command has been modified so the user could define a consumer location either on the network or local with the command.
This does NOT change the current API call but rather simply rename _path_ to _url_ and how it is used in the lttng-ctl library.
Call changed from: --> lttng_create_session(const char *name, const char *path);
To: --> lttng_create_session(const char *name, const char *url);
The _name_ argument is the session name and _url_ is a string representing the URL specified by the user which is define like so:
PROTO://[HOSTNAME|IP][:PORT][/PATH]
The proto supported at this stage are (6 means IPv6):

Quoted 7 lines

Quoted 4 lines
* net, net6, tcp, tcp6, file
If the proto is NOT recognized, the string is considered to be a simple path on the local filesystem.
you could specify that it is a path relative to the process CWD (unless it starts with a /).

Done

Quoted 6 lines

Quoted 5 lines
The PATH section is the destination path on the _remote_ host where the trace data will be written with the <target_hostname> append after.

Quoted 7 lines

The last sentence is not clear (after reading it 2-3 times, it's still not obvious what it explains).
Simply saying that the PATH is relative to a subdirectory "hostname", under the remote relayd "virtual" root directory, might be enough.

Done

Quoted 4 lines

Quoted 2 lines
The relayd defines a default location
... for its virtual root directory...

Done

Quoted 19 lines

Quoted 19 lines
if none is given using the -o, --output option. This default is at:
* $USER/lttng-traces
For example, this URL results in writing the trace data in "$USER/lttng-traces/<target_hostname>/foo/bar".
* net://hostname/foo/bar
The PATH part can not be bigger than PATH_MAX (define in limits.h) which is 4096 bytes at the time of this proposal. Moreover, "../" is ignored and removed. For instance, using "net://localhost/../../" will set the path to the default one.
The <net(6)> protocol has a special case where the user can input two ports respectively being the control and data port.

Quoted 7 lines

Quoted 4 lines
* net://[HOSTNAME|IP][:CTRL_PORT][:DATA_PORT][/PATH]
If _url_ is not NULL, the lttng_create_session will use two API calls.
If _url_ is not NULL, in addition to creating the session, the lttng_create_session will use the two following API calls:

Done

Eazy pizy.
David

Quoted 27 lines

Quoted 27 lines
1) lttng_set_consumer_url(handle, url); 2)
lttng_enable_consumer(handle);
If _url_ is NULL, then NO consumer is created for this tracing session and subsequent calls are needed to set up a consumer (i.e lttng_enable_consumer and lttng_set_consumer_url).
[*] Consumer:
This call is simply renamed.
From: --> lttng_set_consumer_uri(...)
To: --> lttng_set_consumer_url(struct lttng_handle *handle, const char *url);
For both functions (consumer and create), the _url_ will be parsed into a lttng_uri in the liblttng-ctl and sent to the session daemon.
Example:
lttng_set_consumer_url(handle, "net://42.42.42.2");

Quoted 15 lines

Quoted 2 lines
With all this, the lttng_uri data structure will NOT be exposed to the public API and the user command line interface.
The rest looks good!
Thanks,
Mathieu
Quoted 3 lines
_______________________________________________ lttng-dev mailing list [email protected]
http://lists.lttng.org/cgi-bin/mailman/listinfo/lttng-dev

-----BEGIN PGP SIGNATURE-----

iQEcBAEBCgAGBQJQIWrMAAoJEELoaioR9I020qwH/RcBwYZUvR3u5u7BcrG1wp7K xgJ8HmYG9vTYSCMZv1dnMBu1aKCUwzQrwMTI/wi9qmM0oXHi7yk+XMQAbUlDmXoL 5vU4KtdejDyH3jPVMKsAfZRpKu+AghszsvqhUtPON6bM5jYXTWL4E8Wd29QhGS8O xnkl6WUVN0Cb/+I1m3sIJEJFkOjEuKjaoRgZd/fO9f/ZLV90/jId8/nr3Yiar6Sa mgIyl3mfEza8C/oeqBdEmGHSF2emAYEvHBZ9p2ewGfk0T57yVhMEoWGRG1o8pAQj 5BO6fJa+JJT62UAPnh3EFkveHLReoj0eVXVDJ2o2UNU20cTKiJR/TQWDD+CBKL0= =pOdd
-----END PGP SIGNATURE-----

David Goulet

2012-08-08 17:17 UTC #4 lore raw

In reply to a message not in the archive

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA512

ADDENDUM:

The set_consumer_url() call needs an extra arguments since we can both set the CONTROL or STREAM path using this call (the stream type).

So, I would like to propose a change:

From:
lttng_set_consumer_url(struct lttng_handle *handle, const char *url);

To:
lttng_set_consumer_url(struct lttng_handle *handle, const char *url,

			enum lttng_url_stream_type stype);

With:
enum lttng_url_stream_type {
LTTNG_STREAM_CONTROL,
LTTNG_STREAM_DATA,
LTTNG_STREAM_ALL,
};

An _url_ argument with "net://localhost" for instance implies LTTNG_STREAM_ALL as a type however with "tcp://", we have to specify it.

The second possible idea is to add specialize calls like:

set_consumer_control_url()
set_consumer_stream_url()

Though?

Cheers!
David

David Goulet:

Quoted 10 lines

After a discussion with Mathieu and Yannick, here is some big changes.
I hope I did not forget anything important.
Cheers! David
This body part will be downloaded on demand.

-----BEGIN PGP SIGNATURE-----

iQEcBAEBCgAGBQJQIp8aAAoJEELoaioR9I02cBYIAJYI9cFpWwTUq7kAImWB/ZAZ 20NLdDhjvYkHkLdHs76++P5d5DowHYZBY4dFrUKDlRTA5INQ/Q3OeZMCiCs9HkDM i4JZCJdIrgI6Y1Wu5aVKU3kjN11z+169qAx4YYarKoXsordWcPzsBfPazRsJNfVy zAhcY0LQFOgxRDnxAg7zxVIQFimYS/OZBM976fRCRxwV6YBNscEQj9OYgBq8nCOm 76vR1p5WPb93jX/wqe2/ilHAhRslVWedn0p+OT1kNWW0puPyWf2NHxY/KqqhkhAy yFkMeVXJtvnGig1UPgm7H7eouCRAAM04aS6qCVfZz9vBJALEk42UVbcLPO6GzQg= =VobI
-----END PGP SIGNATURE-----

Yannick Brosseau

2012-08-08 20:42 UTC #6 lore raw

In reply to a message not in the archive

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Quoted 21 lines · David Goulet

ADDENDUM:
The set_consumer_url() call needs an extra arguments since we can both set the CONTROL or STREAM path using this call (the stream type).
So, I would like to propose a change:
From:
lttng_set_consumer_url(struct lttng_handle *handle, const char *url);
To:
lttng_set_consumer_url(struct lttng_handle *handle, const char *url, enum lttng_url_stream_type stype);
With:
enum lttng_url_stream_type {
LTTNG_STREAM_CONTROL,
LTTNG_STREAM_DATA,
LTTNG_STREAM_ALL,
};

Quoted 7 lines

An _url_ argument with "net://localhost" for instance implies LTTNG_STREAM_ALL as a type however with "tcp://", we have to specify it.
The second possible idea is to add specialize calls like:
set_consumer_control_url()
set_consumer_stream_url()

Just brainstorming:
lttng_set_consumer_url(struct lttng_handle *handle, const char *control_url, const char *data_url)

Yannick
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.12 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/

iEYEARECAAYFAlAiz0AACgkQFQrZ7GzHX2qd/ACg4uX+tLdSIuBNIz9LvT+6Gy7R O+oAoMevaOacHiR2VI8LA18eeAB0jnCD
=iRYC
-----END PGP SIGNATURE-----

David Goulet

2012-08-08 20:48 UTC #8 lore raw

In reply to a message not in the archive

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA512

Yannick Brosseau:

Quoted 23 lines · David Goulet

Quoted 20 lines
ADDENDUM:
The set_consumer_url() call needs an extra arguments since we can both set the CONTROL or STREAM path using this call (the stream type).
So, I would like to propose a change:
From: lttng_set_consumer_url(struct lttng_handle *handle, const char *url);
To: lttng_set_consumer_url(struct lttng_handle *handle, const char *url, enum lttng_url_stream_type stype);
With: enum lttng_url_stream_type { LTTNG_STREAM_CONTROL, LTTNG_STREAM_DATA, LTTNG_STREAM_ALL, };
An _url_ argument with "net://localhost" for instance implies LTTNG_STREAM_ALL as a type however with "tcp://", we have to specify it.

Quoted 6 lines

Quoted 3 lines
The second possible idea is to add specialize calls like:
set_consumer_control_url() set_consumer_stream_url()
Just brainstorming: lttng_set_consumer_url(struct lttng_handle *handle, const char *control_url, const char *data_url)

Just a bit difficult when you have --control-url and --data-url option possible on the command line... pass NULL to one to set only one.. ? so this call *can* accept NULL value of one of the arg ?

David

Quoted 7 lines

Yannick
_______________________________________________ lttng-dev mailing list [email protected]
http://lists.lttng.org/cgi-bin/mailman/listinfo/lttng-dev

-----BEGIN PGP SIGNATURE-----

iQEcBAEBCgAGBQJQItCBAAoJEELoaioR9I02fJ4H/R213HDtvvu4hbcciu/4mxLR XlDaz3nIWmxPVcpJSiHnEChMjCD1aRh40aUdVbnG5gd/L3MGXV7dbmu/XCcH5OSo gLzk/T86ijvobjgFE6bwXFdGWxCoLTuTk2buzb1v1ppVLC9NeBo8W8wkPURYCR5+ ACFOAMY12X2p543hkp1/B6VSCjdrED59s9QPHpWE4i4FIBSMQrXrXOLLHUwbIrhq x4/14HFYDLkPJeLDOQezbvW1r6B0yovU+NDWimiyr2uG5CPO1Rp5fGl8wjQTh8p+ gcnigccnrONW2ZjQnKlDFeGQmMq8Werznm5QBc38E3SA0+N8BRNRRqoKqqNpsUE= =DUoy
-----END PGP SIGNATURE-----