RFC - Java JUL LTTng Tools API/ABI

Author: David Goulet <dgoulet@efficios.com>

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

Introduction
----------

This proposal details the API/ABI for Java JUL tracing in LTTng-Tools for the
public part.

LTTng ABI
---------

Located in include/lttng/lttng.h, a new domain is introduced. The Java JUL
domain. The only change to the ABI is that a new value is added.

enum lttng_domain_type {
	LTTNG_DOMAIN_KERNEL                   = 1,
	LTTNG_DOMAIN_UST                      = 2,
	LTTNG_DOMAIN_JAVA_JUL                 = 3,	/* NEW VALUE */
}

For this new domain, creating a new event is slightly different in terms of
needed attributes. The following fields in the lttng_event data structure are
IGNORED since they can't be applied to Java tracing.

* enum lttng_event_type type;
* enum lttng_loglevel_type loglevel_type;
* int loglevel
* union attr

Furthermore, adding context and filter is not possible. Future work can possibly
support filters since JUL offers filtering possibilities.

LTTng Command Line
------------------

In terms of command line new option, the Java JUL domain option is added. A new
option for that domain is available in the UI to select that particular domain.

$ lttng enable-event --java-jul (short: -j)

Now, the concept of "event" is NOT directly mapped to log callsite in JUL but to
a Logger[1] name. Thus, commands using "event name" is a  "logger name" for the
JUL domain. For instance, this following command enables the "A" Logger object
in Java application.

$ lttng enable-event -j A

Same goes for the list command, it lists available registered Logger when used
with the -j option.

References
----------
[1] http://docs.oracle.com/javase/7/docs/api/java/util/logging/Logger.html