Typical application error lifecycle

Typically, an error happens in the following way:

1. erroneous code gets executed
2. error occurres
3. error-treating code gets executed (e.g. in a catch block):
3.a. error gets treated
3.b. error gets logged
4. the application continues on recoverable errors

Whenever an error occurres, the developer likes to be informed about the details; if the application is within "range" of the devs, they can monitor available logs and act upon necessity but if it is out of range, BugTrap can be used to create incident reports and deal with the reporting.

Logging an incident using BugTrap

There are 2 approaches for the logging and reporting of incidents:

1. indirect logging using the logging framework already in use: this approach doesn`t need additional logging code - instead the error gets logged as usual. An additional appender is to be registered at the logger which passes the message to BugTrap. BugTrap creates an incident report based on the available data and puts the report into the internal data queue. Depending on the given configuration, the incident report will be populated with further data, reported to a data sink or persistently stored.

Advantage: no additional code necessary, only a BugTrap configuration has to be present, everything gets treated automatically

Disadvantage: the developer has no influence on the logged data (beside the logging message) e.g. the dev cannot populate the incident report with further potentially interesting properties (see below).

Proceed to Logging via Log4J for a description of this approach.

2. direct Logging using custom error handling code: this approach requires a modification of the existing error treatment code, namely a call of the BugTrap-logging methods. The amount of the modification depends on the desired incident richness, typically it requires 3-4 additional LOC.

Advantage: the dev has full control of the logged data. After the initial creation of the incident report (which is a simple Properties object), additional interesting details can be put into the report object. The incident reports is stored in the internal data queue und is treated according to the given configuration (see below).

Disadvantage: additional code is to be written.

Proceed to Logging via Adapters for a description (including example code) of this approach.

What happens to incident data once it resides in the data queue?

It depends on the given configuration that specifies the used plugins and their desired work mode. Proceed to Plugin Overview for a description of the available plugins.