RFC - Session Daemon Network Session

Author: David Goulet <david.goulet@efficios.com>

Contributors:
    * Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
    * Julien Desfossez <julien.desfossez@efficios.com>

Version:
    - v0.1: 16/04/2012
        * Initial proposal

Introduction
-----------------

This RFC proposes a way for the lttng 2.0 session daemon to handle
network session for streaming purposes and eventually remote control.

The next sections introduce the concept of network session and how it is
envisioned in the lttng 2.0 toolchain.

Please note that this RFC is neither final nor complete without the
community feedbacks. The text below is a proposal.

Network Session
-----------------

For trace streaming i.e. collecting a trace from a target machine to
another node of a network, the concept of network tracing session is
inevitable. In order to tell the session daemon where to send the data
for streaming, a current tracing session has to be aware of some
information of the remote target.

    * Remote end network address (Ex: IP or Hostname)
    * Destination control port
    * Destination data port

Streaming can be initiated by telling the session daemon that a specific
session is set for network streaming. This will make the session daemon
establish a connection with the remote end.  Once tracing starts, the
local consumer will be made aware of this information and will start
sending data following a strict protocol defined in the streaming RFC
written by Julien Desfossez.

Finally, a network session will add a new "namespace" to the trace
output directory hierarchy being the hostname from _where_ the trace is
coming from.

host01
\-- my_session1
    \-- ust
        \-- my_app1[...]
            \-- trace data...
    \-- kernel
        \-- trace data...

Client API integration
-----------------

Adding an API call to set attributes such as network information to a
session.  Since lttng_create_session only takes a name and a path, a new
call is required to pass this information. The naming convention is not
final and can be improved.

struct lttng_handle handle;

#define LTTNG_NETWORK_PADDING1_LEN	32
#define LTTNG_NETWORK_PADDING2_LEN	128
struct lttng_network {
    unsigned int enable;
    in_port_t control_port;
    in_port_t data_port;
    char padding[LTTNG_NETWORK_PADDING1_LEN];
    union {
        char ipv4[INET_ADDRSTRLEN];
        char ipv6[INET6_ADDRSTRLEN];
        char hostname[HOST_NAME_MAX];
        char padding[LTTNG_NETWORK_PADDING2_LEN];
    } address;
}

The 'enable' flag set of unset the streaming for the session.

/*
 * This will set the network attributes contained in the lttng_network
 * structure and apply it to a session for streaming.
 */
lttng_streaming_session(handle, struct lttng_network);

or

/* Same as the above */
lttng_attr_setnetwork(handle, struct lttng_network);

or with functions breaking down network attributes (pthread alike):

lttng_attr_setdataport(handle, in_port_t port);
lttng_attr_setctrlport(handle, in_port_t port);
lttng_attr_setaddress(handle, char addr);
lttng_attr_setaddress6(handle, char addr);
lttng_attr_sethostname(handle, char hostname);

Having an empty or NULL address/hostname would mean to stop/disable the
streaming.

or

we can go with a setsockopt(2) alike call:

enum optname {
    LTTNG_OPT_NETADDR,
    LTTNG_OPT_NETDATAPORT,
    LTTNG_OPT_NETCTRLPORT,
    ...
}

lttng_session_setopt(char session_name, optname, char *optval, size_t optlen);

Now for the command line part. Two possibilities:

i) lttng create session --network HOST:[DATA_PORT:CTRL_PORT]
    * or --streaming

ii) lttng session [--set | --unset] --network HOST:[DATA_PORT:CTRL_PORT]
    * or --streaming
    This command will basically be used to set or unset session
    attributes (for now we only have network attr.)

or
    lttng set [on | off] ...
    * with the same option from above.

iii) lttng enable-streaming HOST:[DATA_PORT:CTRL_PORT] [-s SESSION_NAME]
    * by default will take the current session
    * This will imply a disable-streaming command also since the client
      may want to stop the streaming at some point.

Note: the i) option makes the network attributes only possible to set at
session creation.

Once the community agrees on a command, the detail options will be
added. With the new hostname directory containing the trace data, we
might want to add a --hostname option for control the top level
directory name of the host.

Session daemon integration
-----------------

As mentioned earlier, the session daemon will be in charge of
establishing a streaming session with the target over the network i.e.
creating the control and data path bidirectional socket. Once done, a
network consumer is spawned and those sockets are passed over.

From there, the session daemon can interact with the consumer by
stopping the network streaming or re-establishing a local trace
collection with a non network consumer.