Java

Javabrake is the official notifier library for Airbrake for the Java programming language. Airbrake’s goal is to help developers produce better software faster so that we can get back to enjoying technology. Any java error or panic can be sent to the Airbrake dashboard using Javabrake SDK. The library is very small and has very little overhead.

Key Features

  • Simple to install and configure
  • Java Error Detection with Full Stack Traces
  • Performance monitoring features such as HTTP route statistics, SQL queries, and Job execution statistics
  • Add custom parameters to error before they are sent to Airbrake Dashboard.
  • Filters support (filter out sensitive or unwanted data that shouldn’t be sent)
  • Ignore errors based on class, message, status, file, or any other filters based on configuration.
  • Supports logging framworks such as log4j and logback
  • Asynchronous exception reporting
  • Resends the Error notice or Performance data if the Airbrake Server malfunctions. Several configurations must be made as shown below. (Have a question? Look here at FAQ)
  • Support for environments

Supported Frameworks

Support for Middleware’s to be added soon.

Installation & Configuration

Install the Javabrake as per you build tool. Javabrake supports Java 8 and above.

Installation

Gradle

implementation 'io.airbrake:javabrake:0.3.0'

Maven

<dependency>
  <groupId>io.airbrake</groupId>
  <artifactId>javabrake</artifactId>
  <version>0.3.0</version>
</dependency>

Ivy

<dependency org='io.airbrake' name='javabrake' rev='0.3.0'>
  <artifact name='javabrake' ext='pom'></artifact>
</dependency>

Configuration

To add Javabrake to your application projectId & projectKey are required, to find it browse to your project’s Settings and copy the data from the right sidebar of the Airbrake portal.

import io.airbrake.javabrake.Notifier;
import io.airbrake.javabrake.Config;

Config config = new Config();
config.projectId = 12345;
config.projectKey = "FIXME";
Notifier notifier = new Notifier(config);

Additional Settings

List of Parameter Notifier will expect

Configuration parameter which can configure different functionality by Notifier

Parameter NameTypeDescriptionRequiredDefault Value
projectIdIntInteger Airbrake project id from Airbrake.ioYes
projectKeyStringSecret key of Airbrake project in string format from Airbrake.ioYes
performanceStatsBooleanEnable/disable performance monitoring if False, javabrake will not send any monitoring stats to Airbrake.io. Which include (route, query, & queue).NoTrue
queryStatsBooleanEnable/disable query stats monitoring if False, javabrake will not send query monitoring stats to Airbrake.io.NoTrue
queueStatsBooleanEnable/disable queue stats monitoring if False, javabrake will not send queue monitoring stats to Airbrake.io.NoTrue
environmentStringProject running environment, Like: development, testing, production. Can make own environment.Noproduction
remoteConfigBooleanConfigure javabrake using Airbrake.io, a remote server. If True, javabrake will ignore any configutation done during the initialization of the notifier.NoFalse

Error Monitoring

Sending errors to Airbrake

Using notifier directly
try {
  do();
} catch (IOException e) {
  notifier.report(e);
}
Using Airbrake proxy class
import io.airbrake.javabrake.Airbrake;

try {
  do();
} catch (IOException e) {
  Airbrake.report(e);
}

Sending errors synchronously

By default report sends errors asynchronously returning a Future, but synchronous API is also available:

import io.airbrake.javabrake.Notice;

Notice notice = Airbrake.reportSync(e);
if (notice.exception != null) {
    logger.info(notice.exception);
} else {
    logger.info(notice.id);
}

Adding custom params

To set custom params you can build and send notice in separate steps:

import io.airbrake.javabrake.Notice;

Notice notice = Airbrake.buildNotice(e);
notice.setContext("component", "mycomponent");
notice.setParam("param1", "value1");
Airbrake.send(notice);

You can also set custom params on all reported notices:

notifier.addFilter(
    (Notice notice) -> {
      notice.setParam("myparam", "myvalue");
      return notice;
    });

Linking errors to routes

You can link error notices with the routes by setting the route e.g. /hello and httpMethod e.g. GET, POST in the custom parameters for error notices. For example:

Notice notice = notifier.buildNotice(e);
notice.setContext("route", "route-name");
notice.setContext("httpMethod", "http-method-name");

Ignoring notices

Ignore specific notice:

notifier.addFilter(
    (Notice notice) -> {
      if (notice.context.get("environment") == "development") {
          // Ignore notice.
          return null;
      }
      return notice;
    });

Debugging notices

To debug why notices are not sent you can use onReportedNotice hook:

notifier.onReportedNotice(
    (notice) -> {
      if (notice.exception != null) {
        logger.info(notice.exception);
      } else {
        logger.info(String.format("notice id=%s url=%s", notice.id, notice.url));
      }
    });

HTTP proxy

Can I configure Airbrake to send errors through a proxy?

Yes, you can! If your server is not able to directly reach the Airbrake servers you can configure the Airbrake java notifier to send errors through your proxy.

Configuring Airbrake to use your proxy is as simple as setting the relevant proxy options in the initializer

Javabrake uses OkHttp as an HTTP client. So in order to use proxy all you have to do is to configure OkHttpClient:

import java.net.InetSocketAddress;

import okhttp3.OkHttpClient;
import okhttp3.Proxy;

import io.airbrake.javabrake.OkSender;

Proxy proxy = new Proxy(Proxy.Type.HTTP, InetSocketAddress.createUnresolved("192.168.1.105", 8081);
OkHttpClient httpClient =
    new OkHttpClient.Builder()
        .connectTimeout(3000, TimeUnit.MILLISECONDS)
        .readTimeout(3000, TimeUnit.MILLISECONDS)
        .writeTimeout(3000, TimeUnit.MILLISECONDS)
        .proxy(proxy)
        .build();
OkSender.setOkHttpClient(httpClient);

Logging

We support two major logging frameworks:

log4javabrake2 integration

log4javabrake2 is a logging middleware build upon org.apache.logging.log4j. To check installation and Configuration, see log4j

logback integration

logback is a logging middleware build upon ch.qos.logback. To check installation and Configuration, see logback

Performance Monitoring

You can read more about our Performance Monitoring offering in our docs.

Sending route stats

notifier.routes.notify allows sending route stats to Airbrake. You can also use this API manually:

import io.airbrake.javabrake.RouteMetric;

RouteMetric metric = new RouteMetric(request.getMethod(), request.getRequestURI());
metric.statusCode = response.getStatus();
metric.contentType = response.getContentType();
metric.endTime = new Date();

notifier.routes.notify(metric);

Sending route breakdowns

notifier.routes.notify allows sending performance breakdown stats to Airbrake. You can use this API manually:

import io.airbrake.javabrake.RouteMetric;

RouteMetric metric = new RouteMetric(request.getMethod(), request.getRequestURI());

metric.startSpan("span1 name", new Date());
try {
do();
} catch (Exception e) {
e.printStackTrace();
}
metric.endSpan("span1 name", new Date());

metric.startSpan("span2 name", new Date());
try {
do();
} catch (Exception e) {
e.printStackTrace();
}
metric.endSpan("span2 name", new Date());
metric.end();

metric.statusCode = response.getStatus();
metric.contentType = response.getContentType();

notifier.routes.notify(metric);

Sending query stats

notifier.queries.notify allows sending SQL query stats to Airbrake. You can also use this API manually:

Date startTime = new Date();
try
{
  do();
}catch(
Exception e)
{
  e.printStackTrace();
}
Date endTime = new Date();

notifier.queries.notify(request.getMethod(),request.getRequestURI()
,"SELECT * FROM foos",startTime,endTime);

Sending queue stats

notifier.queues.notify allows sending queue (job) stats to Airbrake. You can also use this API manually:

import io.airbrake.javabrake.QueueMetric;

QueueMetric metric = new QueueMetric("foo_queue");

metric.startSpan("span1 name", new Date());
try {
    do();
} catch (Exception e) {
    e.printStackTrace();
}
metric.endSpan("span1 name", new Date());

metric.startSpan("span2 name", new Date());
try {
  do();
} catch (Exception e) {
  e.printStackTrace();
}
metric.endSpan("span2 name", new Date());
metric.end();

notifier.queues.notify(metric);

Notes

Exception limit

The maximum size of an exception is 64KB. Exceptions that exceed this limit will be truncated to fit the size.

Taking Javabrake further

Now that you have configured Airbrake to report exceptions from your Java and above app, we recommend you add extra context to your errors and add Airbrake to your existing logger. Please visit the Javabrake GitHub repo for the full list of notifier features.