X-Git-Url: http://git.lttng.org./?a=blobdiff_plain;f=doc%2Fjava-agent.txt;h=b5f722c7d6a8e06ea1f2a54dde2453545e57934a;hb=5dafeeaa324690afac7c81ab7583523c907f2483;hp=51b0e8c010d707ea43366673809e4fecb1e47c1f;hpb=6f3cecd756f20a8c6b9fceb39a4824631371e0df;p=lttng-ust.git

diff --git a/doc/java-agent.txt b/doc/java-agent.txt
index 51b0e8c0..b5f722c7 100644
--- a/doc/java-agent.txt
+++ b/doc/java-agent.txt
@@ -1,4 +1,8 @@
-The agent can now be built in three different configurations:
+======================
+ Using the Java agent
+======================
+
+The agent can be built in three different configurations:
 
 1) Java agent with JUL support:
 
@@ -20,32 +24,68 @@ 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".
+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
 
-In order to support older applications using the "org.lttng.ust.jul"
-package, a transitional package is built with the same name.
+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.
 
-All applications should move to use the "org.lttng.ust.agent" package.
+-------
+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.)
 
-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".
+---------
+Data path
+---------
+Log messages are generated by the application and sent to the Logger objects,
+which then send them to the Handlers.
 
-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.
+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.
 
-import org.lttng.ust.agent.LTTngAgent;
-[...]
-	private static LTTngAgent lttngAgent;
-	[...]
-	lttngAgent = LTTngAgent.getLTTngAgent();
+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).
 
-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.