[lttng-ust.git] / doc / java-agent.txt

======================
 Using the Java agent
======================

The agent can be built in three different configurations:

1) Java agent with JUL support:

$ ./configure --enable-java-agent-jul

2) Java agent with Log4j support:

$ export CLASSPATH=$CLASSPATH:/path/to/log4j.jar
$ ./configure --enable-java-agent-log4j

3) Java agent with JUL + Log4j support

$ export CLASSPATH=$CLASSPATH:/path/to/log4j.jar
$ ./configure --enable-java-agent-all

To build the agent with log4j support, make sure that the log4j jar
is in your Java classpath.

The configure script will automatically detect the appropriate Java
binaries to use in order to build the Java agent.

Enabling the JUL support will build a "lttng-ust-agent-jul.jar" file. Enabling
the log4j support will build a "lttng-ust-agent-log4j.jar". Both of these jars
depend on a third "lttng-ust-agent-common.jar", which will always be built.

All these archives will be installed in the arch-agnostic "$prefix/share/java"
path, e.g: "/usr/share/java". You need to make sure the .jar for the logging
API you want to use (either lttng-ust-agent-jul.jar or -log4j.jar) is on your
application's classpath.

Both logging libraries also require an architecture-specific shared object
(e.g: "liblttng-ust-jul-jni.so"), which is installed by the build system when
doing "make install". Make sure that your Java application can find this shared
object, by using the "java.library.path" property if necessary.

In order to use UST tracing in your Java application, you simply need to
instantiate a LttngLogHandler or a LttngLogAppender (for JUL or Log4j,
respectively), then attach it to a JUL or Log4j Logger class.

Refer to the code examples in examples/java-jul/ and examples/java-log4j/.

LTTng session daemon agents will be initialized as needed. If no session daemon
is available, the execution will continue and the agents will retry connecting
every 3 seconds.


==============
 Object model
==============

The object model of the Java agent implementation is as follows:

---------
Ownership
---------
Log Handlers: LttngLogHandler, LttngLogAppender
  n handlers/appenders, managed by the application.
  Can be created programmatically, or via a configuration file,
  Each one registers to a specific agent singleton (one per logging API) that is loaded on-demand

Agent singletons: LttngJulAgent, LttngLog4jAgent
  Keep track of all handlers/appenders registered to them.
  Are disposed when last handler deregisters.
  Each agent instantiates 2 TCP clients, one for the root session daemon, one for the user one.
  One type of TCP client class for now. TCP client may become a singleton in the future.

-------
Control
-------
Messages come from the session daemon through the socket connection.
Agent passes back-reference to itself to the TCP clients.
Clients use this reference to invoke callbacks, which modify the state of the agent (enabling/disabling events, etc.)

---------
Data path
---------
Log messages are generated by the application and sent to the Logger objects,
which then send them to the Handlers.

When a log event is received by a Handler (publish(LogRecord)), the handler
checks with the agent if it should log it or not, via
ILttngAgent#isEventEnabled() for example.

Events that are logged call the native tracepoint through JNI, which generates
a UST event. There is one type of tracepoint per domain (Jul or Logj4).

-----------------------
Filtering notifications
-----------------------
FilterChangeNotifier is the singleton notifier class.
Applications implement an IFilterChangeListener, and register it to the notifier.

Whenever new event rules are enabled or disabled, the relevant agent informs the
notifier, which then sends notifications to all registered listeners by invoking
their callbacks.

Upon registration, a new listener will receive notifications for all currently
active rules.

The notifier keeps track of its own event rule refcounting, to handle the case
of multiple sessions or multiple agents enabling identical event rules.

The FilterChangeNotifier does not have threads of its own. The listeners's
callbacks will be invoked by these threads:
* In the case of a notification being received while a listener is already
  registered, the callback is executed by the TCP client's thread. This
  effectively blocks the "lttng" command line until all callbacks are processed
  (assuming no timeouts).
* In the case of a listener registering and receiving the currently-active
  rules, the callbacks will be executed by the application's thread doing the
  registerListener() call.

The notifier is entirely synchronized. This ensure that if a rule is enabled
at the same time a listener is registered, that listener does not miss or
receive duplicate notifications.
Commit	Line	Data
	1	======================
	2	Using the Java agent
	3	======================
	4
	5	The agent can be built in three different configurations:
	6
	7	1) Java agent with JUL support:
	8
	9	$ ./configure --enable-java-agent-jul
	10
	11	2) Java agent with Log4j support:
	12
	13	$ export CLASSPATH=$CLASSPATH:/path/to/log4j.jar
	14	$ ./configure --enable-java-agent-log4j
	15
	16	3) Java agent with JUL + Log4j support
	17
	18	$ export CLASSPATH=$CLASSPATH:/path/to/log4j.jar
	19	$ ./configure --enable-java-agent-all
	20
	21	To build the agent with log4j support, make sure that the log4j jar
	22	is in your Java classpath.
	23
	24	The configure script will automatically detect the appropriate Java
	25	binaries to use in order to build the Java agent.
	26
	27	Enabling the JUL support will build a "lttng-ust-agent-jul.jar" file. Enabling
	28	the log4j support will build a "lttng-ust-agent-log4j.jar". Both of these jars
	29	depend on a third "lttng-ust-agent-common.jar", which will always be built.
	30
	31	All these archives will be installed in the arch-agnostic "$prefix/share/java"
	32	path, e.g: "/usr/share/java". You need to make sure the .jar for the logging
	33	API you want to use (either lttng-ust-agent-jul.jar or -log4j.jar) is on your
	34	application's classpath.
	35
	36	Both logging libraries also require an architecture-specific shared object
	37	(e.g: "liblttng-ust-jul-jni.so"), which is installed by the build system when
	38	doing "make install". Make sure that your Java application can find this shared
	39	object, by using the "java.library.path" property if necessary.
	40
	41	In order to use UST tracing in your Java application, you simply need to
	42	instantiate a LttngLogHandler or a LttngLogAppender (for JUL or Log4j,
	43	respectively), then attach it to a JUL or Log4j Logger class.
	44
	45	Refer to the code examples in examples/java-jul/ and examples/java-log4j/.
	46
	47	LTTng session daemon agents will be initialized as needed. If no session daemon
	48	is available, the execution will continue and the agents will retry connecting
	49	every 3 seconds.
	50
	51
	52	==============
	53	Object model
	54	==============
	55
	56	The object model of the Java agent implementation is as follows:
	57
	58	---------
	59	Ownership
	60	---------
	61	Log Handlers: LttngLogHandler, LttngLogAppender
	62	n handlers/appenders, managed by the application.
	63	Can be created programmatically, or via a configuration file,
	64	Each one registers to a specific agent singleton (one per logging API) that is loaded on-demand
	65
	66	Agent singletons: LttngJulAgent, LttngLog4jAgent
	67	Keep track of all handlers/appenders registered to them.
	68	Are disposed when last handler deregisters.
	69	Each agent instantiates 2 TCP clients, one for the root session daemon, one for the user one.
	70	One type of TCP client class for now. TCP client may become a singleton in the future.
	71
	72	-------
	73	Control
	74	-------
	75	Messages come from the session daemon through the socket connection.
	76	Agent passes back-reference to itself to the TCP clients.
	77	Clients use this reference to invoke callbacks, which modify the state of the agent (enabling/disabling events, etc.)
	78
	79	---------
	80	Data path
	81	---------
	82	Log messages are generated by the application and sent to the Logger objects,
	83	which then send them to the Handlers.
	84
	85	When a log event is received by a Handler (publish(LogRecord)), the handler
	86	checks with the agent if it should log it or not, via
	87	ILttngAgent#isEventEnabled() for example.
	88
	89	Events that are logged call the native tracepoint through JNI, which generates
	90	a UST event. There is one type of tracepoint per domain (Jul or Logj4).
	91
	92	-----------------------
	93	Filtering notifications
	94	-----------------------
	95	FilterChangeNotifier is the singleton notifier class.
	96	Applications implement an IFilterChangeListener, and register it to the notifier.
	97
	98	Whenever new event rules are enabled or disabled, the relevant agent informs the
	99	notifier, which then sends notifications to all registered listeners by invoking
	100	their callbacks.
	101
	102	Upon registration, a new listener will receive notifications for all currently
	103	active rules.
	104
	105	The notifier keeps track of its own event rule refcounting, to handle the case
	106	of multiple sessions or multiple agents enabling identical event rules.
	107
	108	The FilterChangeNotifier does not have threads of its own. The listeners's
	109	callbacks will be invoked by these threads:
	110	* In the case of a notification being received while a listener is already
	111	registered, the callback is executed by the TCP client's thread. This
	112	effectively blocks the "lttng" command line until all callbacks are processed
	113	(assuming no timeouts).
	114	* In the case of a listener registering and receiving the currently-active
	115	rules, the callbacks will be executed by the application's thread doing the
	116	registerListener() call.
	117
	118	The notifier is entirely synchronized. This ensure that if a rule is enabled
	119	at the same time a listener is registered, that listener does not miss or
	120	receive duplicate notifications.