X-Git-Url: http://git.lttng.org/?a=blobdiff_plain;f=doc%2Fjava-agent.txt;h=ae653820ef5181c57604151879319c84d9c721bd;hb=b33b46f7161604cb9168e9bbc854413cf18269be;hp=51b0e8c010d707ea43366673809e4fecb1e47c1f;hpb=6f3cecd756f20a8c6b9fceb39a4824631371e0df;p=lttng-ust.git diff --git a/doc/java-agent.txt b/doc/java-agent.txt index 51b0e8c0..ae653820 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,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 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.