Documentation‎ > ‎

Application Instrumentation

There are different ways to setup the bug4j agent within your application.
If your application already uses Apache log4j then the simplest method is probably to add a bug4j appender.
The alternative is to call the bug4j agent.
In both cases you will have to include the bug4j client and its dependencies in your application's classpath.
The bug4j client is located in .../client/bug4j.jar. The dependencies are in the .../client/lib directory.

Using Log4J

Edit your log4j.xml and add the bug4j appender:
<!DOCTYPE log4j:configuration SYSTEM "log4j.dtd">
<log4j:configuration xmlns:log4j="http://jakarta.apache.org/log4j/">
    <appender name="console" class="org.apache.log4j.ConsoleAppender">
        <param name="Target" value="System.out"/>
        <layout class="org.apache.log4j.PatternLayout">
            <param name="ConversionPattern" value="%-5p %c{1} - %m%n"/>
        </layout>
    </appender>
    <appender name="bug4j" class="org.bug4j.client.Bug4jAppender">
        <param name="serverUrl" value="http://<bug4j.host.name>:8063/"/>
        <param name="applicationName" value="My Application"/>
        <param name="applicationVersion" value="1.3"/>
        <!--
                <param name="proxy" value="proxy.example.com:8080"/>
        -->
    </appender>

    <root>
        <priority value="info"/>
        <appender-ref ref="console"/>
        <appender-ref ref="bug4j"/>
    </root>

</log4j:configuration>
If you store the configuration in log4j.properties then you will need this instead:
# Set root logger level to DEBUG and its only appender to A1.
log4j
.rootLogger=INFO, A1, BUG4J

# A1 is set to be a ConsoleAppender.
log4j
.appender.A1=org.apache.log4j.ConsoleAppender

# A1 uses PatternLayout.
log4j
.appender.A1.layout=org.apache.log4j.PatternLayout
log4j
.appender.A1.layout.ConversionPattern=%-4r [%t] %-5p %c %x - %m%
n

log4j
.appender.BUG4J=org.bug4j.client.Bug4jAppender
log4j
.appender.BUG4J.serverUrl=http://<bug4j.host.name>:8063/
log4j
.appender.BUG4J.applicationName=My Application
log4j
.appender.BUG4J.applicationVersion=1.3
Don't forget to replace <bug4j.host.name> with the name of the host where you have installed the bug4j server.
Now every call to Logger.error() in addition to report the error in the log file will also report an error to the bug4j server.

Invoking the bug4j agent
If you do not use log4j then you must instrument your application by invoking the agent explicitly.
You first have to setup the agent: Just include a bug4j.properties in your classpath.
server.url=http://<bug4j.host.name>:8063/
application.name=My Application
application.version=1.3
Don't forget to replace <bug4j.host.name> with the name of the host where you have installed the bug4j server.

To invoke the bug4j agent, call 
import org.bug4j.client.*;
...
    } catch (Exeption e) {
        Bug4jAgent.report("Failed to do something", e);
    }
...
The key is to identify the few places where exceptions can be intercepted.
You can also install an default exception handler:
import org.bug4j.client.*;
...
        final Bug4jUncaughtExceptionHandler handler = new Bug4jUncaughtExceptionHandler();
        Thread.setDefaultUncaughtExceptionHandler(handler );
...


Comments