From: Julien Desfossez Date: Fri, 27 Sep 2013 20:28:40 +0000 (-0400) Subject: Documentation of live usage and protocol X-Git-Tag: v2.4.0-rc1~132 X-Git-Url: https://git.lttng.org/?p=lttng-tools.git;a=commitdiff_plain;h=24bc0841bdd3fb38b76a9244d21f28000d653fcf Documentation of live usage and protocol Signed-off-by: Julien Desfossez --- diff --git a/doc/Makefile.am b/doc/Makefile.am index f57abf42a..6f05d7a78 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -1,6 +1,8 @@ SUBDIRS = man EXTRA_DIST = quickstart.txt streaming-howto.txt python-howto.txt \ - snapshot-howto.txt calibrate.txt kernel-CodingStyle.txt + snapshot-howto.txt calibrate.txt kernel-CodingStyle.txt \ + live-reading-howto.txt live-reading-protocol.txt dist_doc_DATA = quickstart.txt streaming-howto.txt python-howto.txt \ - snapshot-howto.txt calibrate.txt + snapshot-howto.txt calibrate.txt live-reading-howto.txt \ + live-reading-protocol.txt diff --git a/doc/live-reading-howto.txt b/doc/live-reading-howto.txt new file mode 100644 index 000000000..4a54f1c4a --- /dev/null +++ b/doc/live-reading-howto.txt @@ -0,0 +1,53 @@ +LTTng Live trace reading how-to + +Julien Desfossez +September 27th, 2013 + +This document presents a summary on how to use the live trace reading feature +introduced in LTTng 2.4. For the details about the protocol, please refer to +the live-reading-protocol.txt document. + +Live trace reading refers to the feature of reading the trace while it is being +recorded. In order to do that, the trace must be streamed a relay even if the +viewer is running on the same machine as the tracer. + +So, the first thing to do is to start a lttng-relayd process. It can be +anywhere on the network (including localhost) as long as the sessiond/consumerd +and the viewer can communicate with it over TCP/IP. + +$ lttng-relayd -d + +Then, we can create a session configured for streaming with the new --live +parameter. + +$ lttng create --live 1000000 -U net://localhost + +The --live parameter activates a session-wide timer (usec) that is responsible +for checking at a user-defined rate if new data is available. If there is new +data, it is flushed automatically, otherwise a beacon is sent to the relayd to +inform it that the stream is currently empty and the viewer can ignore this +stream up to a certain point in time. + +Once the session is created, the user can activate events as usual. + +In order to view the live trace, the viewer must implement the live-reading +protocol. + +For now, a basic client is available in the branch index2013 of the git +repository : +https://github.com/jdesfossez/babeltrace-dev.git + +This client is still in heavy development and the branch will be rebased, it is +only provided as a proof-of-concept and an exemple on how to use the protocol. +Once compiled and installed, just run : +$ test-live hostname 2>/dev/null + +If you want to see all the debug, just get rid of "2>/dev/null". +Once again, it is a client in development, the name is purposely bad and the +debug output is relatively heavy. + +Known viewer issues : +- adding metadata on the fly (enabling events when a viewer is connected) +- destroy not clean +- aggressive polling when all the streams are inactive (after a lttng stop) +- restart reading from the beginning (SEEK_LAST not implemented yet) diff --git a/doc/live-reading-protocol.txt b/doc/live-reading-protocol.txt new file mode 100644 index 000000000..fcc75b37d --- /dev/null +++ b/doc/live-reading-protocol.txt @@ -0,0 +1,117 @@ +LTTng Live trace reading protocol + +Julien Desfossez +September 18th, 2013 + +This document describes the protocol of live trace reading. It is mainly +intended for trace-viewer developers. + +Live trace reading allows a viewer to read safely a LTTng trace while it is +being recorded. The protocol ensures that the viewer is never in a position +where it can read for which it does not have the metadata, and also allows to +viewer to know about inactive streams and skip those up to a certain point in +time. + +This feature is implemented starting at lttng-tools 2.4 + +* General informations +All the data structures required to implement this protocole are provided in +the lttng-viewer.h header. All integer are encoded in big endian during the +transfer. + +Just like the streaming protocol, this protocol works always in only one +direction : from the viewer to the relay. After each command, the relay sends a +reply to the viewer (or closes the connection on fatal error). + +When the viewer sends a command to the relay, it sends a struct +lttng_viewer_cmd which contains the command (enum lttcomm_relayd_command) and +the size of the actual command if the command requires a payload. +For example, if the viewer wants to list the sessions, it sends a struct +lttng_viewer_cmd with : +cmd = htobe32(VIEWER_CONNECT); +data_size = htobe64(sizeof(struct lttng_viewer_connect)); + +The cmd_version is currently unused, but might get useful when we extend the +protocol later. + +* Protocol sequence +In this section, we describe the normal sequence of event during a live-reading +session. The viewer is abbreviated V and the relay R for conciseness. + +Establishing a connection : +- V connects to R on port TCP/5344 +- V establishes a session by sending a VIEWER_CONNECT command, payload in + struct lttng_viewer_connect. In this struct, it sets its major and minor + version of the protocol it implements, and the type of connection it wants, + for now only VIEWER_CLIENT_COMMAND is supported. +- If the protocol implemented by V and R are compatible, R sends back the same + struct with its own version and the newly assigned viewer_session_id. + Protocols are compatible if they have the same major number. At this point, + if the communication continues and the minor are not the same, it is implied + that the two processes will use the min(minor) of the protocol during this + connection. Protocol versions follow lttng-tools version, so if R implements + the 2.5 protocol and V implements the 2.4 protocol, R will use the 2.4 + protocol for this connection. + +List the sessions : +Once V and R agree on a protocol, V can start interacting with R. The first +thing to do is list the sessions currently active on R. +- V sends the command VIEWER_LIST_SESSIONS with no payload (data_size ignored) +- R sends back a struct lttng_viewer_list_sessions which contains the number of + sessions to receive, and then for each session (sessions_count), it sends a + struct lttng_viewer_session +- V must first receive the struct lttng_viewer_list_sessions and then receive + all the lttng_viewer_session structs. The live_timer corresponds to the value + set by the user who created the tracing session, if it is 0, the session + cannot be read in live. This timer in microseconds is the minimum rate at + which R receives information about the running session. The "clients" field + contains the number of connected clients to this session, for now only one + client at a time can attach to session. + +Attach to a session : +Now V can select a session and attach to it. In order to do so, it sends the +command VIEWER_ATTACH_SESSION with the session_id it wants. The "seek" +parameter allows the viewer to attach to a session from its beginning (it will +receive all trace data still on the relayd) or from now (data will be available +to read starting at the next packet received on the relay). Only one session +can be established by connection. Lots of clock synchronisation issues can +happen when connecting to multiple sessions from multiple hosts at the same +time, we let the viewers have fun with it ;-) +R replies with a struct lttng_viewer_attach_session_response with a status and +the number of streams currently active in this session. Then, for each stream, +it sends a struct lttng_viewer_stream. Just like with the session list, V must +receive the first header and then all the stream structs. The ctf_trace_id +parameter in the struct lttng_viewer_stream is particularly important since it +allows the viewer to match all the streams belonging to the same CTF trace (so +one metadata file and multiple stream files). If the stream is a metadata +stream, metadata_flag will be set to 1. + +#### below needs to be well written, but the essential is here ### + +Get metadata : +A CTF trace cannot be read without the complete metadata. +Send the command VIEWER_GET_METADATA and the struct lttng_viewer_get_metadata. + +Once we have all the metadata, we can start processing the trace. In order to +do that, we work with the indexes. Whenever we need to read a new packet from a +stream, we first ask for the next index for this stream and then ask for a +trace packet at a certain offset and length. + +Get the next index : +Command VIEWER_GET_NEXT_INDEX +struct lttng_viewer_get_next_index +Receive back a struct lttng_viewer_index + +Get data packet : +Command VIEWER_GET_PACKET +struct lttng_viewer_get_packet +Receive back a struct lttng_viewer_trace_packet + +For the VIEWER_GET_NEXT_INDEX and VIEWER_GET_PACKET, the viewer must check the +"flags" element of the struct it receives, because it contains important +information such as the information that new metadata must be received before +being able to receive and read the next packet. +When new metadata is added during a session, the GET_NEXT_INDEX will succeed +but it will have the flag LTTNG_VIEWER_FLAG_NEW_METADATA, but the +GET_DATA_PACKET will fail with the same flag as long as the metadata is not +downloaded.