|
Packit |
c04fcb |
======================
|
|
Packit |
c04fcb |
Using the Java agent
|
|
Packit |
c04fcb |
======================
|
|
Packit |
c04fcb |
|
|
Packit |
c04fcb |
The agent can be built in three different configurations:
|
|
Packit |
c04fcb |
|
|
Packit |
c04fcb |
1) Java agent with JUL support:
|
|
Packit |
c04fcb |
|
|
Packit |
c04fcb |
$ ./configure --enable-java-agent-jul
|
|
Packit |
c04fcb |
|
|
Packit |
c04fcb |
2) Java agent with Log4j support:
|
|
Packit |
c04fcb |
|
|
Packit |
c04fcb |
$ export CLASSPATH=$CLASSPATH:/path/to/log4j.jar
|
|
Packit |
c04fcb |
$ ./configure --enable-java-agent-log4j
|
|
Packit |
c04fcb |
|
|
Packit |
c04fcb |
3) Java agent with JUL + Log4j support
|
|
Packit |
c04fcb |
|
|
Packit |
c04fcb |
$ export CLASSPATH=$CLASSPATH:/path/to/log4j.jar
|
|
Packit |
c04fcb |
$ ./configure --enable-java-agent-all
|
|
Packit |
c04fcb |
|
|
Packit |
c04fcb |
To build the agent with log4j support, make sure that the log4j jar
|
|
Packit |
c04fcb |
is in your Java classpath.
|
|
Packit |
c04fcb |
|
|
Packit |
c04fcb |
The configure script will automatically detect the appropriate Java
|
|
Packit |
c04fcb |
binaries to use in order to build the Java agent.
|
|
Packit |
c04fcb |
|
|
Packit |
c04fcb |
Enabling the JUL support will build a "lttng-ust-agent-jul.jar" file. Enabling
|
|
Packit |
c04fcb |
the log4j support will build a "lttng-ust-agent-log4j.jar". Both of these jars
|
|
Packit |
c04fcb |
depend on a third "lttng-ust-agent-common.jar", which will always be built.
|
|
Packit |
c04fcb |
|
|
Packit |
c04fcb |
All these archives will be installed in the arch-agnostic "$prefix/share/java"
|
|
Packit |
c04fcb |
path, e.g: "/usr/share/java". You need to make sure the .jar for the logging
|
|
Packit |
c04fcb |
API you want to use (either lttng-ust-agent-jul.jar or -log4j.jar) is on your
|
|
Packit |
c04fcb |
application's classpath.
|
|
Packit |
c04fcb |
|
|
Packit |
c04fcb |
Both logging libraries also require an architecture-specific shared object
|
|
Packit |
c04fcb |
(e.g: "liblttng-ust-jul-jni.so"), which is installed by the build system when
|
|
Packit |
c04fcb |
doing "make install". Make sure that your Java application can find this shared
|
|
Packit |
c04fcb |
object, by using the "java.library.path" property if necessary.
|
|
Packit |
c04fcb |
|
|
Packit |
c04fcb |
In order to use UST tracing in your Java application, you simply need to
|
|
Packit |
c04fcb |
instantiate a LttngLogHandler or a LttngLogAppender (for JUL or Log4j,
|
|
Packit |
c04fcb |
respectively), then attach it to a JUL or Log4j Logger class.
|
|
Packit |
c04fcb |
|
|
Packit |
c04fcb |
Refer to the code examples in examples/java-jul/ and examples/java-log4j/.
|
|
Packit |
c04fcb |
|
|
Packit |
c04fcb |
LTTng session daemon agents will be initialized as needed. If no session daemon
|
|
Packit |
c04fcb |
is available, the execution will continue and the agents will retry connecting
|
|
Packit |
c04fcb |
every 3 seconds.
|
|
Packit |
c04fcb |
|
|
Packit |
c04fcb |
|
|
Packit |
c04fcb |
==============
|
|
Packit |
c04fcb |
Object model
|
|
Packit |
c04fcb |
==============
|
|
Packit |
c04fcb |
|
|
Packit |
c04fcb |
The object model of the Java agent implementation is as follows:
|
|
Packit |
c04fcb |
|
|
Packit |
c04fcb |
---------
|
|
Packit |
c04fcb |
Ownership
|
|
Packit |
c04fcb |
---------
|
|
Packit |
c04fcb |
Log Handlers: LttngLogHandler, LttngLogAppender
|
|
Packit |
c04fcb |
n handlers/appenders, managed by the application.
|
|
Packit |
c04fcb |
Can be created programmatically, or via a configuration file,
|
|
Packit |
c04fcb |
Each one registers to a specific agent singleton (one per logging API) that is loaded on-demand
|
|
Packit |
c04fcb |
|
|
Packit |
c04fcb |
Agent singletons: LttngJulAgent, LttngLog4jAgent
|
|
Packit |
c04fcb |
Keep track of all handlers/appenders registered to them.
|
|
Packit |
c04fcb |
Are disposed when last handler deregisters.
|
|
Packit |
c04fcb |
Each agent instantiates 2 TCP clients, one for the root session daemon, one for the user one.
|
|
Packit |
c04fcb |
One type of TCP client class for now. TCP client may become a singleton in the future.
|
|
Packit |
c04fcb |
|
|
Packit |
c04fcb |
-------
|
|
Packit |
c04fcb |
Control
|
|
Packit |
c04fcb |
-------
|
|
Packit |
c04fcb |
Messages come from the session daemon through the socket connection.
|
|
Packit |
c04fcb |
Agent passes back-reference to itself to the TCP clients.
|
|
Packit |
c04fcb |
Clients use this reference to invoke callbacks, which modify the state of the agent (enabling/disabling events, etc.)
|
|
Packit |
c04fcb |
|
|
Packit |
c04fcb |
---------
|
|
Packit |
c04fcb |
Data path
|
|
Packit |
c04fcb |
---------
|
|
Packit |
c04fcb |
Log messages are generated by the application and sent to the Logger objects,
|
|
Packit |
c04fcb |
which then send them to the Handlers.
|
|
Packit |
c04fcb |
|
|
Packit |
c04fcb |
When a log event is received by a Handler (publish(LogRecord)), the handler
|
|
Packit |
c04fcb |
checks with the agent if it should log it or not, via
|
|
Packit |
c04fcb |
ILttngAgent#isEventEnabled() for example.
|
|
Packit |
c04fcb |
|
|
Packit |
c04fcb |
Events that are logged call the native tracepoint through JNI, which generates
|
|
Packit |
c04fcb |
a UST event. There is one type of tracepoint per domain (Jul or Logj4).
|
|
Packit |
c04fcb |
|
|
Packit |
c04fcb |
-----------------------
|
|
Packit |
c04fcb |
Filtering notifications
|
|
Packit |
c04fcb |
-----------------------
|
|
Packit |
c04fcb |
FilterChangeNotifier is the singleton notifier class.
|
|
Packit |
c04fcb |
Applications implement an IFilterChangeListener, and register it to the notifier.
|
|
Packit |
c04fcb |
|
|
Packit |
c04fcb |
Whenever new event rules are enabled or disabled, the relevant agent informs the
|
|
Packit |
c04fcb |
notifier, which then sends notifications to all registered listeners by invoking
|
|
Packit |
c04fcb |
their callbacks.
|
|
Packit |
c04fcb |
|
|
Packit |
c04fcb |
Upon registration, a new listener will receive notifications for all currently
|
|
Packit |
c04fcb |
active rules.
|
|
Packit |
c04fcb |
|
|
Packit |
c04fcb |
The notifier keeps track of its own event rule refcounting, to handle the case
|
|
Packit |
c04fcb |
of multiple sessions or multiple agents enabling identical event rules.
|
|
Packit |
c04fcb |
|
|
Packit |
c04fcb |
The FilterChangeNotifier does not have threads of its own. The listeners's
|
|
Packit |
c04fcb |
callbacks will be invoked by these threads:
|
|
Packit |
c04fcb |
* In the case of a notification being received while a listener is already
|
|
Packit |
c04fcb |
registered, the callback is executed by the TCP client's thread. This
|
|
Packit |
c04fcb |
effectively blocks the "lttng" command line until all callbacks are processed
|
|
Packit |
c04fcb |
(assuming no timeouts).
|
|
Packit |
c04fcb |
* In the case of a listener registering and receiving the currently-active
|
|
Packit |
c04fcb |
rules, the callbacks will be executed by the application's thread doing the
|
|
Packit |
c04fcb |
registerListener() call.
|
|
Packit |
c04fcb |
|
|
Packit |
c04fcb |
The notifier is entirely synchronized. This ensure that if a rule is enabled
|
|
Packit |
c04fcb |
at the same time a listener is registered, that listener does not miss or
|
|
Packit |
c04fcb |
receive duplicate notifications.
|