doc/java-agent.txt

   1 ======================
   2  Using the Java agent
   3 ======================
   4
   5 The agent can be built in three different configurations:
   6
   7 1) Java agent with JUL support:
   8
   9 $ ./configure --enable-java-agent-jul
  10
  11 2) Java agent with Log4j support:
  12
  13 $ export CLASSPATH=$CLASSPATH:/path/to/log4j.jar
  14 $ ./configure --enable-java-agent-log4j
  15
  16 3) Java agent with JUL + Log4j support
  17
  18 $ export CLASSPATH=$CLASSPATH:/path/to/log4j.jar
  19 $ ./configure --enable-java-agent-all
  20
  21 To build the agent with log4j support, make sure that the log4j jar
  22 is in your Java classpath.
  23
  24 The configure script will automatically detect the appropriate Java
  25 binaries to use in order to build the Java agent.
  26
  27 Enabling the JUL support will build a "lttng-ust-agent-jul.jar" file. Enabling
  28 the log4j support will build a "lttng-ust-agent-log4j.jar". Both of these jars
  29 depend on a third "lttng-ust-agent-common.jar", which will always be built.
  30
  31 All these archives will be installed in the arch-agnostic "$prefix/share/java"
  32 path, e.g: "/usr/share/java". You need to make sure the .jar for the logging
  33 API you want to use (either lttng-ust-agent-jul.jar or -log4j.jar) is on your
  34 application's classpath.
  35
  36 Both logging libraries also require an architecture-specific shared object
  37 (e.g: "liblttng-ust-jul-jni.so"), which is installed by the build system when
  38 doing "make install". Make sure that your Java application can find this shared
  39 object, by using the "java.library.path" property if necessary.
  40
  41 In order to use UST tracing in your Java application, you simply need to
  42 instantiate a LttngLogHandler or a LttngLogAppender (for JUL or Log4j,
  43 respectively), then attach it to a JUL or Log4j Logger class.
  44
  45 Refer to the code examples in examples/java-jul/ and examples/java-log4j/.
  46
  47 LTTng session daemon agents will be initialized as needed. If no session daemon
  48 is available, the execution will continue and the agents will retry connecting
  49 every 3 seconds.
  50
  51
  52 ==============
  53  Object model
  54 ==============
  55
  56 The object model of the Java agent implementation is as follows:
  57
  58 ---------
  59 Ownership
  60 ---------
  61 Log Handlers: LttngLogHandler, LttngLogAppender
  62   n handlers/appenders, managed by the application.
  63   Can be created programmatically, or via a configuration file,
  64   Each one registers to a specific agent singleton (one per logging API) that is loaded on-demand
  65
  66 Agent singletons: LttngJulAgent, LttngLog4jAgent
  67   Keep track of all handlers/appenders registered to them.
  68   Are disposed when last handler deregisters.
  69   Each agent instantiates 2 TCP clients, one for the root session daemon, one for the user one.
  70   One type of TCP client class for now. TCP client may become a singleton in the future.
  71
  72 -------
  73 Control
  74 -------
  75 Messages come from the session daemon through the socket connection.
  76 Agent passes back-reference to itself to the TCP clients.
  77 Clients use this reference to invoke callbacks, which modify the state of the agent (enabling/disabling events, etc.)
  78
  79 ---------
  80 Data path
  81 ---------
  82 Log messages are generated by the application and sent to the Logger objects,
  83 which then send them to the Handlers.
  84
  85 When a log event is received by a Handler (publish(LogRecord)), the handler
  86 checks with the agent if it should log it or not, via
  87 ILttngAgent#isEventEnabled() for example.
  88
  89 Events that are logged call the native tracepoint through JNI, which generates
  90 a UST event. There is one type of tracepoint per domain (Jul or Logj4).
  91