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

The agent can now 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.

The name of the agent jar file is now "liblttng-ust-agent.jar".
It will be installed in the arch-agnostic "$prefix/share/java" path
e.g: "/usr/share/java".

In order to support older applications using the "org.lttng.ust.jul"
package, a transitional package is built with the same name.

All applications should move to use the "org.lttng.ust.agent" package.

After building, you can use the "liblttng-ust-agent.jar" file in a
Java project.  Depending on your configuration, the agent will
requires shared objects (e.g: "liblttng-ust-jul.so") which is installed
by the build system when doing "make install". Make sure that your
Java application can find this shared object with the
"java.library.path".

In order to enable the agent in your Java application, you simply have to add
this as early as you can in the runtime process.

import org.lttng.ust.agent.LTTngAgent;
[...]
	private static LTTngAgent lttngAgent;
	[...]
	lttngAgent = LTTngAgent.getLTTngAgent();

This will initialize automatically the singleton LTTngAgent, and will
return when the session daemon registration is done. If no session daemon is
available, the execution will continue and the agent will retry every
3 seconds.
Commit	Line	Data
	1	The agent can now be built in three different configurations:
	2
	3	1) Java agent with JUL support:
	4
	5	$ ./configure --enable-java-agent-jul
	6
	7	2) Java agent with Log4j support:
	8
	9	$ export CLASSPATH=$CLASSPATH:/path/to/log4j.jar
	10	$ ./configure --enable-java-agent-log4j
	11
	12	3) Java agent with JUL + Log4j support
	13
	14	$ export CLASSPATH=$CLASSPATH:/path/to/log4j.jar
	15	$ ./configure --enable-java-agent-all
	16
	17	To build the agent with log4j support, make sure that the log4j jar
	18	is in your Java classpath.
	19
	20	The configure script will automatically detect the appropriate Java
	21	binaries to use in order to build the Java agent.
	22
	23	The name of the agent jar file is now "liblttng-ust-agent.jar".
	24	It will be installed in the arch-agnostic "$prefix/share/java" path
	25	e.g: "/usr/share/java".
	26
	27	In order to support older applications using the "org.lttng.ust.jul"
	28	package, a transitional package is built with the same name.
	29
	30	All applications should move to use the "org.lttng.ust.agent" package.
	31
	32	After building, you can use the "liblttng-ust-agent.jar" file in a
	33	Java project. Depending on your configuration, the agent will
	34	requires shared objects (e.g: "liblttng-ust-jul.so") which is installed
	35	by the build system when doing "make install". Make sure that your
	36	Java application can find this shared object with the
	37	"java.library.path".
	38
	39	In order to enable the agent in your Java application, you simply have to add
	40	this as early as you can in the runtime process.
	41
	42	import org.lttng.ust.agent.LTTngAgent;
	43	[...]
	44	private static LTTngAgent lttngAgent;
	45	[...]
	46	lttngAgent = LTTngAgent.getLTTngAgent();
	47
	48	This will initialize automatically the singleton LTTngAgent, and will
	49	return when the session daemon registration is done. If no session daemon is
	50	available, the execution will continue and the agent will retry every
	51	3 seconds.