rseq: do 8 rseq attempts before using refcount fallback
[lttng-ust.git] / doc / java-agent.txt
CommitLineData
d60dfbe4
AM
1======================
2 Using the Java agent
3======================
4
3707dfc5 5The agent can be built in three different configurations:
6f3cecd7
CB
6
71) Java agent with JUL support:
8
9$ ./configure --enable-java-agent-jul
10
112) Java agent with Log4j support:
12
13$ export CLASSPATH=$CLASSPATH:/path/to/log4j.jar
14$ ./configure --enable-java-agent-log4j
15
163) Java agent with JUL + Log4j support
17
18$ export CLASSPATH=$CLASSPATH:/path/to/log4j.jar
19$ ./configure --enable-java-agent-all
20
21To build the agent with log4j support, make sure that the log4j jar
22is in your Java classpath.
23
24The configure script will automatically detect the appropriate Java
25binaries to use in order to build the Java agent.
26
3707dfc5
AM
27Enabling the JUL support will build a "lttng-ust-agent-jul.jar" file. Enabling
28the log4j support will build a "lttng-ust-agent-log4j.jar". Both of these jars
29depend on a third "lttng-ust-agent-common.jar", which will always be built.
6f3cecd7 30
3707dfc5
AM
31All these archives will be installed in the arch-agnostic "$prefix/share/java"
32path, e.g: "/usr/share/java". You need to make sure the .jar for the logging
33API you want to use (either lttng-ust-agent-jul.jar or -log4j.jar) is on your
34application's classpath.
6f3cecd7 35
3707dfc5
AM
36Both 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
38doing "make install". Make sure that your Java application can find this shared
d60dfbe4
AM
39object, by using the "java.library.path" property if necessary.
40
41In order to use UST tracing in your Java application, you simply need to
42instantiate a LttngLogHandler or a LttngLogAppender (for JUL or Log4j,
43respectively), then attach it to a JUL or Log4j Logger class.
44
45Refer to the code examples in examples/java-jul/ and examples/java-log4j/.
46
47LTTng session daemon agents will be initialized as needed. If no session daemon
48is available, the execution will continue and the agents will retry connecting
49every 3 seconds.
50
51
52==============
53 Object model
54==============
55
56The object model of the Java agent implementation is as follows:
57
58---------
59Ownership
60---------
61Log 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
66Agent 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-------
73Control
74-------
75Messages come from the session daemon through the socket connection.
76Agent passes back-reference to itself to the TCP clients.
77Clients use this reference to invoke callbacks, which modify the state of the agent (enabling/disabling events, etc.)
78
79---------
80Data path
81---------
82Log messages are generated by the application and sent to the Logger objects,
83which then send them to the Handlers.
6f3cecd7 84
d60dfbe4
AM
85When a log event is received by a Handler (publish(LogRecord)), the handler
86checks with the agent if it should log it or not, via
87ILttngAgent#isEventEnabled() for example.
6f3cecd7 88
d60dfbe4
AM
89Events that are logged call the native tracepoint through JNI, which generates
90a UST event. There is one type of tracepoint per domain (Jul or Logj4).
6f3cecd7 91
78439abe
AM
92-----------------------
93Filtering notifications
94-----------------------
95FilterChangeNotifier is the singleton notifier class.
96Applications implement an IFilterChangeListener, and register it to the notifier.
97
98Whenever new event rules are enabled or disabled, the relevant agent informs the
99notifier, which then sends notifications to all registered listeners by invoking
100their callbacks.
101
102Upon registration, a new listener will receive notifications for all currently
103active rules.
104
105The notifier keeps track of its own event rule refcounting, to handle the case
106of multiple sessions or multiple agents enabling identical event rules.
107
108The FilterChangeNotifier does not have threads of its own. The listeners's
109callbacks will be invoked by these threads:
110* In the case of a notification being received while a listener is already
111 registered, the callback is executed by the TCP client's thread. This
112 effectively blocks the "lttng" command line until all callbacks are processed
113 (assuming no timeouts).
114* In the case of a listener registering and receiving the currently-active
115 rules, the callbacks will be executed by the application's thread doing the
116 registerListener() call.
117
118The notifier is entirely synchronized. This ensure that if a rule is enabled
119at the same time a listener is registered, that listener does not miss or
120receive duplicate notifications.
This page took 0.031066 seconds and 5 git commands to generate.