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

Example6:
- 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


Example7:
- 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


Example8:
- 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


Example9:
- this example shows how to enable reporting errors to container-exception-logger (cel)
- cel gets enabled by passing option 'cel' with value 'on'
- container-exception-logger has to be installed in a container

$  java -agentlib:abrt-java-connector=cel=on $MyClass -platform.jvmtiSupported true


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 builddebug
$ make run
$ make check
$ make rpm
$ make distclean

All build results are stored in ./bin directory.

Use the `builddebug` make target if you wish to debug `bin/utils/abrt-action-analyze-java` with `gdb`.

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.

Also, the `check` target will fail if you're running it from anywhere under `/home`. This is because the satyr sr_java_stacktrace_parse function in the "unpackaged" test anonymizes the path to the java testing code which results in the test looking for a non-existent file under `/home/anonymized/`.