[lttng-ust.git] / liblttng-ust-jul / README

This directory contains the LTTng Java Agent for JUL support.

Configuration examples to build this library:

dependency: openjdk-7-jdk
    ./configure --with-java-jdk=/usr/lib/jvm/java-7-openjdk --with-jni-interface

On Debian system for instance you can simply use the "default-java" path:

    ./configure --with-java-jdk=/usr/lib/jvm/default-java --with-jni-interface

Note that the OpenJDK 7 is used for development and continuous integration thus
we directly support that version for this library. However, it has been tested
with OpenJDK 6 also. Please let us know if other Java version (commercial or
not) work with this library.

After building, you can use the "liblttng-ust-jul.jar" file in a Java project.
It requires "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.jul.LTTngAgent;
[...]
	private static LTTngAgent lttngAgent;
	[...]
	lttngAgent = LTTngAgent.getLTTngAgent();

This will initialize automatically the singleton LTTngAgent, it will stall
your application until the session daemon registration is done. If no session
daemon is available, the execution will continue and the agent will retry at
each 3 seconds.

Once registered, it is adds a thread inside your Java application and will be
able to automatically use every Logger object and map them to the jul_event
tracepoint of the JNI interface (see LTTngUst.c/.java).
Commit	Line	Data
43e5396b DG	1	This directory contains the LTTng Java Agent for JUL support.
	2
	3	Configuration examples to build this library:
	4
	5	dependency: openjdk-7-jdk
	6	./configure --with-java-jdk=/usr/lib/jvm/java-7-openjdk --with-jni-interface
	7
	8	On Debian system for instance you can simply use the "default-java" path:
	9
	10	./configure --with-java-jdk=/usr/lib/jvm/default-java --with-jni-interface
	11
	12	Note that the OpenJDK 7 is used for development and continuous integration thus
	13	we directly support that version for this library. However, it has been tested
	14	with OpenJDK 6 also. Please let us know if other Java version (commercial or
	15	not) work with this library.
	16
	17	After building, you can use the "liblttng-ust-jul.jar" file in a Java project.
	18	It requires "liblttng-ust-jul.so" which is installed by the build system when
	19	doing "make install". Make sure that your Java application can find this shared
	20	object with the "java.library.path".
	21
	22	In order to enable the agent in your Java application, you simply have to add
	23	this as early as you can in the runtime process.
	24
	25	import org.lttng.ust.jul.LTTngAgent;
	26	[...]
	27	private static LTTngAgent lttngAgent;
	28	[...]
	29	lttngAgent = LTTngAgent.getLTTngAgent();
	30
	31	This will initialize automatically the singleton LTTngAgent, it will stall
	32	your application until the session daemon registration is done. If no session
	33	daemon is available, the execution will continue and the agent will retry at
	34	each 3 seconds.
	35
	36	Once registered, it is adds a thread inside your Java application and will be
	37	able to automatically use every Logger object and map them to the jul_event
	38	tracepoint of the JNI interface (see LTTngUst.c/.java).