RFC - Java JUL domain network protocol

Author: David Goulet <dgoulet@efficios.com>

Version:
	- v0.1: 11/09/2013
		* Initial proposal

Introduction
----------

This proposal is to detail as much as possible the network protocol between
Java JUL [1] component and the session daemon for the UST Java tracing support.

Architecture
------------

To achieve Java tracing with UST using JUL [1], a LTTng agent is needed in the
Java application to communicate with the session daemon. JUL works with Logger
[2] object in which handlers are attached. Once the agent is activated, it
attachs a custom LTTng log handler to all existing loggers to trace events that
passes through those.

The session daemon can list the existing loggers by asking the agent and
enable/disable the handler in those Logger object by removing or adding the
LTTng handler (addHandler/removeHandler).

Considering that, the network protocol for this communication is defined in this
document.

Protocol
--------

This part is split in two sections. First one explains how the agent initiate a
connection to the session daemon AFTER the registration is done by the UST
tracer. The second details the protocol specification.

1. Agent communication

First, the UST tracer registers to the session daemon. This is done by
initializing the library through a JNI [3] call in the agent. During the
registration, the session daemon needs to detect that it's a Java application
and prepare a TCP socket for bidirectionnal communication with the agent.

Once done, the agent creates a TCP connection to the session daemon on a
standard port (5345) on localhost (127.0.0.1).

Using that socket, the session daemon can send commands and receive answers.
The commands are:

	* List loggers by name
	* Enable logger by name
	* Disable logger by name

Each of those uses the format defined in the next section (2).

2. Format specification

(Definition are expressed in a C like fashion)

A command is formed with a header section and a payload. The command and
response use different format since only the session daemon can send command to
the agent.

Session daemon

* Header struct

enum command {
	LIST		= 1,
	ENABLE		= 2,
	DISABLE		= 3,
}

struct {
	uint64_t data_size	/* Size of the payload following the header */
	uint64_t cmd		/* Command value from the defined enum above. */
	uint64_t version	/* Command version. Used for compatibility. */
}

* Payload

struct enable_logger {
	char name[MAX_SIZE]	/* Name of the logger to enable. */
}

struct disable_logger {
	char name[MAX_SIZE]	/* Name of the logger to disable. */
}

Java Agent:

* Reply struct for each command

struct list_logger_cmd {
	uint64_t nb;		/* Number of logger. */
	char logger_name[]	/* Logger name(s). (variable size). */
	uint32_t ret_code	/* Error code. */
}

struct generic_reply {
	uint32_t ret_code	/* Error code. */
}

For enable and disable logger, the generic structure is used.

References
----------

[1] http://docs.oracle.com/javase/7/docs/api/java/util/logging/package-summary.html
[2] http://docs.oracle.com/javase/7/docs/api/java/util/logging/Logger.html
[3] http://docs.oracle.com/javase/7/docs/technotes/guides/jni/