Add compile time assertion that array and sequence have integer elements

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

diff --git a/doc/java-agent.txt b/doc/java-agent.txt
index 51b0e8c010d707ea43366673809e4fecb1e47c1f..ae653820ef5181c57604151879319c84d9c721bd 100644 (file)
--- 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:
 
 
 1) Java agent with JUL support:
 


@@ -20,32 +24,97 @@ 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 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
+
+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).

 
 

-In order to support older applications using the "org.lttng.ust.jul"
-package, a transitional package is built with the same name.
+-----------------------
+Filtering notifications
+-----------------------
+FilterChangeNotifier is the singleton notifier class.
+Applications implement an IFilterChangeListener, and register it to the notifier.

 
 

-All applications should move to use the "org.lttng.ust.agent" package.
+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.

 
 

-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".
+Upon registration, a new listener will receive notifications for all currently
+active rules.

 
 

-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.
+The notifier keeps track of its own event rule refcounting, to handle the case
+of multiple sessions or multiple agents enabling identical event rules.

 
 

-import org.lttng.ust.agent.LTTngAgent;
-[...]
-       private static LTTngAgent lttngAgent;
-       [...]
-       lttngAgent = LTTngAgent.getLTTngAgent();
+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.

 
 

-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.
+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.