Honeybadger for Java

Typical installation time: ~10 minutes

Hi there! You’ve found Honeybadger’s guide to Java exception and error tracking. Once installed, Honeybadger will automatically report errors from your Java application.

Getting started

Source Code • Maven

Honeybadger works out of the box with many popular Java frameworks. Installation is just a matter of including the jar library and setting your API key. In this section, we’ll cover the basics. More advanced installations are covered later.

1. Install the jar

The first step is to add the honeybadger jar to your dependency manager (Maven, SBT, Gradle, Ivy, etc). In the case of Maven, you would add it as so:

<dependency>
    <groupId>io.honeybadger</groupId>
    <artifactId>honeybadger-java</artifactId>
    <!-- Set the specific version below in order to ensure API compatibility in future versions -->
    <version>LATEST</version>
</dependency>

In the case of SBT:

libraryDependencies += "io.honeybadger" % "honeybadger-java" % "]1,)"

For other dependency managers an example is provided on the Maven Central site.

If you are not using a dependency manager, download the jar directly and add it to your classpath.

2. Install a slf4j compatible logging library or binding in your project

Note: If you are using Spring Boot or the Play Framework, a slf4j compatible logger is installed by default.

All dependencies needed for running are included in the distributed JAR with one exception - slf4j-api. We expect that you are using some logging library and that you have imported the sl4j-api in order to provide a common interface for the logger to imported libraries.

Almost every logging library provides a means for it to be compatible with the slf4j API. These are two good candidates if you aren’t sure about which one to choose:

• Logback
• log4j2

3. Set your API key and configuration parameters

Next, you’ll set the API key and some configuration parameters for this project.

Stand-alone usage

If you want to send all unhandled errors to Honeybadger and have them logged to slf4j via the error log level, you will need to set the correct system properties (or provide a ConfigContext) and add a single line to the thread in which you want to register the error handler.

A typical stand-alone implementation may look like:

import io.honeybadger.reporter.HoneybadgerUncaughtExceptionHandler;

public class MyApp {
 public static void main(String argv[]) {
     HoneybadgerUncaughtExceptionHandler.registerAsUncaughtExceptionHandler();
     // The rest of the application goes here
 }
}

You would invoke it with the -Dhoneybadger.api_key=<my_api_key> system parameter and any other configuration values via system parameters it would load with the correct state. It would then register itself as the default error handler.

Servlet usage

A servlet based implementation may look like:

In your web.xml file:

    <!-- Send all uncaught servlet exceptions and servlet request details to Honeybadger -->
    <filter>
        <filter-name>HoneybadgerFilter</filter-name>
        <filter-class>io.honeybadger.reporter.servlet.HoneybadgerFilter</filter-class>
        <init-param>
            <param-name>honeybadger.api_key</param-name>
            <param-value>PROJECT_API_KEY</param-value>
        </init-param>
        <init-param>
            <param-name>honeybadger.excluded_sys_props</param-name>
            <param-value>bonecp.password,bonecp.username</param-value>
        </init-param>
        <init-param>
            <param-name>honeybadger.excluded_exception_classes</param-name>
            <param-value>org.apache.catalina.connector.ClientAbortException</param-value>
        </init-param>
        <!-- By default this is true. Toggle to false if you don't want users to be able
             to send feedback. -->
        <init-param>
            <param-name>honeybadger.display_feedback_form</param-name>
            <param-value>false</param-value>
        </init-param>
    </filter>
    <filter-mapping>
        <filter-name>HoneybadgerFilter</filter-name>
        <url-pattern>/*</url-pattern>
    </filter-mapping>

Note

If you have other code executing in your servlet-based application that doesn’t go through the servlet interface, you will want to register an exception handler for it in order to report errors to Honeybadger. See the Stand-alone Usage section.

Play Framework usage

This library has been tested against Play 2.4.2. After adding Hondeybadger as a dependency to your dependency manager as explained in the Install the jar section, you can enable Honeybadger as an error handler by adding the following lines to your conf/application.conf file:

honeybadger.api_key = [Your project API key]
# You can add any of the Honeybadger configuration parameters here directly
# honeybadger.excluded_exception_classes = com.myorg.AnnoyingException
play.http.errorHandler = io.honeybadger.reporter.play.HoneybadgerErrorHandler

This will allow the library to wrap the default error handler implementation and pass around Honeybadger error ids instead of the default Play error ids.

Spring Framework usage

This library has been tested against Spring 4.2.2 using Spring Boot. After adding Honeybadger as a dependency to your dependency manager as explained in the Install the jar section, you can enable Honeybadger as an error handler by adding the honeybadger.api_key configuration parameter to your Spring configuration. Spring allows for many different vectors of configuration and it is beyond the scope of this document to describe all of them. For example, if you were using a file-based application configuration, you would need to add your Honeybadger configuration parameters as follows:

ENV = production
honeybadger.api_key = [Your project API key]
honeybadger.excluded_exception_classes = com.myorg.AnnoyingException

Note: Spring doesn’t support the concept of a single environment name. Rather, it supports a pattern of using multiple profiles to determine the runtime configuration. This pattern doesn’t map nicely to Honeybadger’s configuration, so you will need to define ENV or JAVA_ENV within your configuration in order for it to map properly to Honeybadger’s way of doing things.

Configuration

Advanced configuration

There are a few ways to configure the Honeybadger library. Each one of the ways is implemented as a ConfigContext that can be passed in the constructor of the HoneybadgerReporter class. The implementations available are:

• DefaultsConfigContext - This configuration context provides defaults that can be read by other context implementations.
• MapConfigContext - This reads configuration from a Map that is supplied to its constructor.
• PlayConfigContext - This reads configuration from the Play Framework’s internal configuration mechanism.
• ServletFilterConfigContext - This reads configuration from a servlet filter configuration.
• SpringConfigContext - This reads configuration from the Spring framework’s internal configuration mechanism.
• StandardConfigContext - This reads configuration from the system parameters, environment variables and defaults and is the default configuration provider.
• SystemSettingsConfigContext - This reads configuration purely from system settings.

Configuring with environment variables or system properties (12-factor style)

All configuration options can also be read from environment variables or Java system properties when using the default StandardConfigContext. Framework specific configuration contexts use of environment variables or system properties depends on the framework’s implementation.

Configuration options

| Option Details | Description | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --- | --- | | CORE | | | | | Name: ENV or JAVA_ENV
Type: String
Required: No
Default: unknown
Sample Value: production | String sent to Honeybadger indicating running environment (eg development, test, staging, production, etc). | | Name: honeybadger.api_key or HONEYBADGER_API_KEY
Type: String
Required: Yes
Default: N/A
Sample Value: 29facd41 | The API key found in the settings tab in the Honeybadger UI. | | Name: honeybadger.application_package
Type: String
Required: No
Default: N/A
Sample Value: my.app.package | Java application package name used to indicate to Honeybadger what stacktraces are within the calling application’s code base. | | Name: honeybadger.excluded_exception_classes
Type: CSV
Required: No
Default: N/A
Sample Value: co.foo.Exception,
com.myorg.AnnoyingException | CSV of Java classes in which errors are never sent to Honeybadger. This is useful for errors that are bubbled up from underlying frameworks or application servers like Tomcat. If you are using Tomcat, you may want to include org.apache.catalina.connector.ClientAbortException. | | Name: honeybadger.excluded_sys_props
Type: CSV
Required: No
Default: honeybadger.api_key,
honeybadger.read_api_key,
honeybadger.excluded_sys_props,
honeybadger.url
Sample Value: bonecp.password,bonecp.username | CSV of Java system properties to exclude from being logged to Honeybadger. This is useful for excluding authentication information. Default values are automatically added. | | Name: honeybadger.excluded_params
Type: CSV
Required: No
Default: N/A
Sample Value: auth_token,
session_data,
credit_card_number | CSV of HTTP GET/POST query parameter values that will be excluded from the data sent to Honeybadger. This is useful for excluding authentication information, parameters that are too long or sensitive. | | Name: honeybadger.maximum_retry_attempts
Type: Integer
Required: No
Default: 3
Sample Value: 3 (must be >= 0) | Number of times HoneybadgerReporter will retry delivering an error report if the first attempt fails. (If set to 3, retries up to 3 times before giving up; if set to 0, tries once and gives up). | |   | | | | | FEEDBACK_FORM | | | | | Name: honeybadger.display_feedback_form
Type: Boolean
Required: No
Default: true
Sample Value: false | Displays the feedback form or JSON output when an error is thrown via a servlet call. | | Name: honeybadger.feedback_form_template_path
Type: String
Required: No
Default: templates/feedback-form.mustache
Sample Value: templates/my-company.mustache | Path within the class path to the mustache template that is displayed when an error occurs in a servlet request. | |   | | | | | NETWORK | | | | | Name: http.proxyHost
Type: String
Required: No
Default: N/A
Sample Value: localhost | Standard Java system property for specifying the host to proxy all HTTP traffic through. | | Name: http.proxyPort
Type: Integer
Required: No
Default: N/A
Sample Value: 8888 | Standard Java system property for specifying the port to proxy all HTTP traffic through. | | Name: honeybadger.socket_timeout
Type: Integer
Required: No
Default: N/A
Sample Value: 60000 | Duration in milliseconds the HTTP socket can be open. | | Name: honeybadger.connect_timeout
Type: Integer
Required: No
Default: N/A
Sample Value: 60000 | Duration in milliseconds the HTTP socket is allowed to be in the connecting phase. | |   | | | | | DEVELOPMENT | | | | | Name: honeybadger.read_api_key or HONEYBADGER_READ_API_KEY
Type: String
Required: When testing
Default: N/A
Sample Value: qjcp6c7Nv9yR-bsvGZ77 | API key used to access the Read API. | | Name: honeybadger.url
Type: String
Required: No
Default: https://api.honeybadger.io
Sample Value: https://other.hbapi.com | URL to the Honeybadger API endpoint. You may want to access it without TLS in order to test with a proxy utility. |

Custom error pages

The Honeybadger library has a few parameters that it looks for whenever it renders an error page. These can be used to display extra information about the error, or to ask the user for information about how they triggered the error. Most of the parameters just link to a resource file that can provide translations for the strings displayed to the user.

Parameter	Description
honeybadger.feedback.error_title	Title of page
honeybadger.feedback.thanks	Thank you message
honeybadger.feedback.heading	Prompt for feedback
honeybadger.feedback.labels.name	Explanation query
honeybadger.feedback.labels.phone	Phone number label
honeybadger.feedback.labels.email	Email label
honeybadger.feedback.labels.comment	Comments label
honeybadger.feedback.submit	Submit button label
honeybadger.link	HB link label
honeybadger.powered_by	Powered by HB text
action	Form POST URI
error_id	Honeybadger Error ID
error_msg	Error message

The default template is setup to collect user feedback and to suppress the display of the error message. This behavior can be changed by placing a new mustache template in your classpath and specifying its path via the honeybadger.feedback_form_template_path configuration option.

Collecting user feedback (ServletFilter)

When an error is sent to Honeybadger, an HTML form can be generated so users can fill out relevant information that led up to that error. Feedback responses are displayed inline in the comments section on the fault detail page.

This behavior is enabled by default. To disable it set the configuration option honeybadger.display_feedback_form to false.

Using tags

This version of honeybadger-java supports sending tags, but it requires invoking a new overload of

  NoticeReporter.reportError(Throwable error, Object request, String message, Iterable<String> tags);

The existing error handler/filter implementations for Play, Spring, and Servlets do not currently invoke this variant. Those implementations can be overridden to customize the tagging behavior for your application.

Supported JVM

JVM	Supported Version
Oracle (Java SE)	1.7, 1.8, 9, [10, 11, 12]*
OpenJDK JDK/JRE	1.7, 1.8, 9, 10, 11, 12

Limitations: We don’t currently test on Oracle’s commercially licensed VMs, due to new licensing rules. Accordingly, Oracle JDK after version 9 is supported on a best-effort basis only. If you discover a defect specific to their commercially-licensed VM, please submit an issue.

Supported frameworks

Framework	Version	Notes
Servlet API	4.0.1
Play Framework	2.7.2	We still call one deprecated API. See Issue #110
Spring Framework	5.1.7

The Play Framework Spring are supported natively (install/configure the library and your done). For the Servlet API, you will need to configure a servlet filter and enable it in your application. As for manual invocation of the API, you will need to configure your application to directly call the reporter class. You can find more information about this in the stand-alone usage section.