Commit | Line | Data |
---|---|---|
d60dfbe4 AM |
1 | ====================== |
2 | Using the Java agent | |
3 | ====================== | |
4 | ||
3707dfc5 | 5 | The agent can be built in three different configurations: |
6f3cecd7 CB |
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 | ||
3707dfc5 AM |
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. | |
6f3cecd7 | 30 | |
3707dfc5 AM |
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. | |
6f3cecd7 | 35 | |
3707dfc5 AM |
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 | |
d60dfbe4 AM |
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. | |
6f3cecd7 | 84 | |
d60dfbe4 AM |
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. | |
6f3cecd7 | 88 | |
d60dfbe4 AM |
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). | |
6f3cecd7 | 91 |