RFC - Network consumer Author: David Goulet Contributors: * Mathieu Desnoyers * Julien Desfossez Version: - v0.1: 16/04/2012 * Initial proposal - v0.2: 04/05/2012 * Add snapshot description * Propose a new API and lttng cli command - v0.3: 23/07/2012 * Remove snapshot and focus only on network consumer for straming. 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 consumer ----------------- For version 2.1 of lttngt-tools, we propose to add a network consumer which will be used for streaming. We allow to pass a full URI to the enable consumer command to override the current consumer or define a new one. We should at least support the following protocols: * net://HOST[:PORT_CTRL[:PORT_DATA]] * tcp://HOST:PORT * tcp6://HOST:PORT * udp://HOST:PORT * udp6://HOST:PORT * file:// The net:// URI scheme makes the control and data stream use the default transport protocol which is TCP. The same remote host is also used for both. The ports can be specified and if not the defaults are used which are 5342 for control and 5343 for data. If URI not recognized, we use the arguments as a file name (same behavior as using file:///). The control and data stream are two separate arguments of the API since we allow the user to control the protocol and path (address). However, for a transfer to succeed, the lttng-sessiond and the remote end must establish a session for the control _and_ data path. If one fails to do so, the procedure is aborted. Thus, a different address for the control path from the data path is allowed but the user has to make sure that both communication channels end up at the same physical destination. Note that the control path is a crucial and high priority channel of communication so for now we only allow it to use the TCP protocol. Session with Network Transport ----------------- In order to tell the session daemon where to send the data for streaming, a 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 trace received by a network consumer will have a new "namespace" prepended to the trace output directory hierarchy: 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; enum lttng_dst_type { LTTNG_DST_IPV4, LTTNG_DST_IPV6, LTTNG_DST_HOST, LTTNG_DST_PATH, }; enum lttng_uri_type { LTTNG_URI_HOP, LTTNG_URI_DST, }; enum lttng_stream_type { LTTNG_STREAM_CONTROL, LTTNG_STREAM_DATA }; enum lttng_proto_type { LTTNG_UDP, LTTNG_TCP, }; #define LTTNG_NETWORK_PADDING1_LEN 32 #define LTTNG_NETWORK_PADDING2_LEN 128 struct lttng_uri { enum lttng_dst_type dtype; enum lttng_uri_type utype; enum lttng_stream_type stype; enum lttng_proto proto; in_port_t port; char padding[LTTNG_NETWORK_PADDING1_LEN]; char subdir[PATH_MAX]; union { char ipv4[INET_ADDRSTRLEN]; char ipv6[INET6_ADDRSTRLEN]; char path[PATH_NAME]; char padding[LTTNG_NETWORK_PADDING2_LEN]; } dst; }; /* Set URI in the consumer template*/ lttng_set_consumer_uri(handle, struct lttng_uri *u); /* * Enable consumer template for the session. Once enabled, no more URI setting * are possible for that specific consumer. */ lttng_enable_consumer(handle); /* * Disable the consumer means that the consumer will stop consuming but will * still be exist. Executing the enable_consumer call again will simply re * enable it. */ lttng_disable_consumer(handle); If lttng_set_consumer_uri is executed on a session which already has a network consumer attached to it, the present consumer is freed and a new template is added. We propose to add two commands to the lttng command line actions: i) lttng enable-consumer [URI] [OPTIONS] -s SESSION_NAME -C, --control-uri=[HOP1,]URI -D, --data-uri=[HOP1,]URI ii) lttng disable-consumer -s SESSION_NAME Each option defining URI(s) can contains a list of hops preceeding the final destination. However, the proxy feature is still not supported but we prefer to inform the community of is future existence. So, the regular chain of command to enable a network consumer would be: # lttng create session1 // The command sets the destination but uses the default protocols and ports. # lttng enable-consumer net://192.168.1.10 # lttng enable-event -a -k # lttng start (tracing...) # lttng stop (This example considers that there is a lttng-relayd on the remote end.) 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.