Honeybadger for Java

This is the notifier JVM library for integrating applications with the ⚡ Honeybadger.io error notification service. When an uncaught exception occurs, Honeybadger will POST the relevant data to the Honeybadger server specified in your environment.

Supported JVM versions

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 web 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.

Getting Started

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 = {{PROJECT_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 = {{PROJECT_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.

API Only Usage

If you want to send exceptions to HoneyBadger without having to register an uncaught exception handler, you can create an instance of HonebadgerReporter and call the reportError(Throwable error) method directly.

This is an example of calling how you might configure the Honeybadger library and use it to send an error to the API programmatically.

package com.myapp;

import io.honeybadger.reporter.HoneybadgerReporter;
import io.honeybadger.reporter.NoticeReporter;
import io.honeybadger.reporter.config.StandardConfigContext;

public class ApiUsage {
    public static void main(String[] argv) {
        StandardConfigContext config = new StandardConfigContext();
        config.setApiKey("ab3fg93xs")
              .setEnvironment("staging")
              .setApplicationPackage("com.myapp");
        
        NoticeReporter reporter = new HoneybadgerReporter(config);
        Throwable t = new RuntimeException("I'm a custom error");
        reporter.reportError(t);
    }
}

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 (ServletFilter)

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.

Changelog

See https://github.com/honeybadger-io/honeybadger-java/blob/master/changes.txt

Contributing

If you're adding a new feature, please submit an issue as a preliminary step; that way you can be (moderately) sure that your pull request will be accepted.

To contribute your code:

1. Fork it.
2. Create a topic branch git checkout -b my_branch
3. Configure integration tests to use your API keys (see below).
4. Run unit and integration tests ./mvn verify
5. Commit your changes git commit -am "Boom"
6. Push to your branch git push origin my_branch
7. Send a pull request

Testing

For the purpose of one off testing, you can use the CLI utility. Just execute it using mvn exec:java -Dexec.mainClass="io.honeybadger.reporter.HoneybadgerCLI" from the honeybadger-java subdirectory and you can enter in your API key and message to be sent to Honeybadger.

Running the tests

This library by requires access to the remote Honeybadger API, so in order to run automated tests you will need to specify system properties to Java in order configure the remote API key and other settings.

If you are running the tests from maven, the simplest solution is to set environment variables to do this.

ENV=test HONEYBADGER_API_KEY=b889a6b2 HONEYBADGER_READ_API_KEY=1b331858d937b5ba8f4c07c1f39c0127903980c8e013367e15a40fcee2fcb74e

mvn verify

If you are executing your tests from an IDE like IntelliJ, you may need to manually set the system variables as part of the test run configuration.

For developers pushing to Maven repositories, you will need to specify the location of your signing keys in ~/.m2/settings.xml.

Properties for signing look like:

<settings>
  <servers>
    <server>
      <id>ossrh</id>
      <username>your-jira-id</username>
      <password>your-jira-pwd</password>
    </server>
  </servers>
</settings>

signing.keyId=345A20CE
signing.password=J6N0phB*f3aRH4bZ
signing.secretKeyRingFile=/home/user/.gnupg/secring.gpg

ossrhUsername=user
ossrhPassword=AFbz3BjdE4Q9g2E&

Testing with Docker

A Docker environment is available to make testing/releasing more consistent. To run the tests:

docker build . -t honeybadger-java
docker run -it --rm -v $HOME/.m2:/root/.m2 --env-file .env honeybadger-java mvn verify

Platform differences

We collect performance metrics on the machine in which an error occurs. This means that we have to do platform specific operations. Currently, these operations are best supported on Linux systems and have minimal support on other platforms.

Credits

Originally forked by Elijah Zupancic from honeybadger-java - thanks to both of you for doing the hard work of getting this library started.

License

The Honeybadger gem is MIT licensed. See the LICENSE file in this repository for details.