README ------ ABRT Java Connector is a JVM agent which reports a Java exceptions to ABRT. The agent can report both caught and uncaught exceptions but by default it reports only uncaught exceptions. In order to be able to report even uncaught exceptions, the agent must register several JVMTI event callbacks and the processing inside of those callbacks have not-insignificant impact on the performance of an entire application. Usage ----- It needs to be compiled as a shared native library (.so) and then loaded into JVM using either -agentlib or -agentpath command line parameter. The first parameter requires the library's file name and works only if the library is placed in one of the ld searched directories or a directory included in LD_LIBRARY_PATH environment variable. The latter command line argument works with an arbitrary, valid absolute path pointing to the library. The default path to the abrt-java-connector library is '/usr/lib/abrt-java-connector/libabrt-java-connector.so' and must be passed to JVM using '-agentpath' command line argument mentioned above. It is guaranteed that the agent properly works with java-1.7.0-openjdk and java-1.8.0-openjdk. Configuration ------------- The agent can be configured either via configuration file or via command line arguments. The command line arguments have higher priority and overwrites values loaded from the configuration file. The default path to the configuration file is '/etc/abrt/plugins/java.conf'. Examples -------- Before you can run the examples, you need to make sure that libabrt-java-connector.so is placed somewhere in the ld searched directories or configure LD_LIBRARY_PATH environment variable to point to a directory containing the library. $MyClass is a placeholder for your Java class. Example1: - this example prints the detected errors to the terminal only - reporting to ABRT is disabled by default $ java -agentlib:abrt-java-connector $MyClass -platform.jvmtiSupported true Example2: - this example shows how to enable reporting errors to ABRT - ABRT gets enabled by passing option 'abrt' with value 'on' - options sent to the agent are specified right behind it's name $ java -agentlib:abrt-java-connector=abrt=on $MyClass -platform.jvmtiSupported true Example3: - this example shows how to configure the log output destination - 'output' option is designed for this purpose - abrt-java-connector does not print any logs by default - the first command prints logs to /tmp/abrt_checker_$PID.log $ java -agentlib:abrt-java-connector=output=/tmp $MyClass -platform.jvmtiSupported true - the second command prints agent's output to /tmp/abrt-agent.log file $ java -agentlib:abrt-java-connector=output=/tmp/abrt-agent.log $MyClass -platform.jvmtiSupported true Example4: - this example shows how to enable reporting of caught exceptions - 'caught' option is designed for this purpose - by default no caught exception is reported - user must provide a colon separated list of exception type names $ java -agentlib:abrt-java-connector=caught=java.io.FileNotFoundException:java.io.FileNotFoundException $MyClass -platform.jvmtiSupported true Example5: - this example shows hot to enable syslog and disable journald - abrt-java-connector reports detected problems to journald by default - problems reported to journald has stack trace stored in STACK_TRACE field - problems reported to syslog are written to syslog with entire backtrace - disable journald $ java -agentlib:abrt-java-connector=journald=off $MyClass -platform.jvmtiSupported true - enable syslog $ java -agentlib:abrt-java-connector=syslog=on $MyClass -platform.jvmtiSupported true Example5: - this example shows how to configure abrt-java-connector to fill 'executable' ABRT file with a path to a class on the bottom of the stack trace (the first method of thread) - this feature can be enabled via 'executable' option which can contain either 'mainclass' or 'threadclass' $ java -agentlib:abrt-java-connector=executable=threadclass $MyClass -platform.jvmtiSupported true - 'mainclass' is used when 'executable' option is not passed and 'executable' file is filled with full path $MyClass Example6: - this example shows how to enrich the exception report with extra debug information - abrt-java-connector is capable to call a static method returning String at time of processing exception - while creating the exception report methods from the list stored in 'debugmethod' option are called, not all of them, but only those whose defining class was already loaded by 'System Class Loader' $ java -agentlib:abrt-java-connector=debugmethod=com.example.$MyClass.getMethod $MyClass Example7: - this example shows how to change the path to configuration file - the default configuration file path is '/etc/abrt/plugins/java.conf' - empty 'conffile' option means do not read any configuration file $ java -agentlib:abrt-java-connector=conffile=/etc/foo/example.conf $MyClass Building from sources --------------------- This project uses CMake build system but a Makefile for GNU Make, which defines all the targets you usually need to run, is also provided. $ make build $ make run $ make check $ make rpm $ make distclean All build results are stored in ./bin directory. The `check' make target will fail if you run it under root user. There are some test cases that try to generate 'File Access Denied' exceptions and the easiest way to achieve that is to try to access a root's file.