<SYSTEM>java reference: Documentation for the Honeybadger Java client library (SDK) and platform.</SYSTEM>

# Honeybadger for Java

> Honeybadger monitors your Java applications for errors and exceptions so that you can fix them wicked fast.

**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 [Section titled “Getting started”](#getting-started) [Source Code](https://github.com/honeybadger-io/honeybadger-java) • [Maven](https://search.maven.org/#search%7Cga%7C1%7Cg%3A%22io.honeybadger%22) 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 [Section titled “1. Install the jar”](#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: 
```xml
<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: 
```plaintext
libraryDependencies += "io.honeybadger" % "honeybadger-java" % "]1,)"
```
 For other dependency managers an example is provided on the [Maven Central site](https://search.maven.org/#search%7Cgav%7C1%7Cg%3A%22io.honeybadger%22%20AND%20a%3A%22honeybadger-java%22). 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 [Section titled “2. Install a slf4j compatible logging library or binding in your project”](#2-install-a-slf4j-compatible-logging-library-or-binding-in-your-project) *Note*: If you are using [Spring Boot](http://projects.spring.io/spring-boot/) or the [Play Framework](https://www.playframework.com/), 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](http://logback.qos.ch/) * [log4j2](http://logging.apache.org/log4j/2.x/log4j-slf4j-impl/index.html) ### 3. Set your API key and configuration parameters [Section titled “3. Set your API key and configuration parameters”](#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 [Section titled “Stand-alone usage”](#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](https://github.com/honeybadger-io/honeybadger-java/tree/master/honeybadger-java/src/main/java/io/honeybadger/reporter/config/ConfigContext.java)) 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: 
```java
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 [Section titled “Servlet usage”](#servlet-usage) A servlet based implementation may look like: In your web.xml file: 
```xml
    <!-- 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>
```
 #### Play Framework usage [Section titled “Play Framework usage”](#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](#1-install-the-jar), you can enable Honeybadger as an error handler by adding the following lines to your conf/application.conf file: 
```plaintext
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 [Section titled “Spring Framework usage”](#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](#1-install-the-jar), you can enable Honeybadger as an error handler by adding the `honeybadger.api_key` configuration parameter to your [Spring configuration](http://docs.spring.io/spring-boot/docs/current/reference/html/boot-features-external-config.html). 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: 
```plaintext
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](http://docs.spring.io/spring-boot/docs/current/reference/html/boot-features-profiles.html) 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 [Section titled “Configuration”](#configuration) ### Advanced configuration [Section titled “Advanced configuration”](#advanced-configuration) There are a few ways to configure the Honeybadger library. Each one of the ways is implemented as a [ConfigContext](https://github.com/honeybadger-io/honeybadger-java/tree/master/honeybadger-java/src/main/java/io/honeybadger/reporter/config/ConfigContext.java) that can be passed in the constructor of the [HoneybadgerReporter](https://github.com/honeybadger-io/honeybadger-java/tree/master/honeybadger-java/src/main/java/io/honeybadger/reporter/HoneybadgerReporter.java) class. The implementations available are: * [DefaultsConfigContext](https://github.com/honeybadger-io/honeybadger-java/tree/master/honeybadger-java/src/main/java/io/honeybadger/reporter/config/DefaultsConfigContext.java) - This configuration context provides defaults that can be read by other context implementations. * [MapConfigContext](https://github.com/honeybadger-io/honeybadger-java/tree/master/honeybadger-java/src/main/java/io/honeybadger/reporter/config/MapConfigContext.java) - This reads configuration from a Map that is supplied to its constructor. * [PlayConfigContext](https://github.com/honeybadger-io/honeybadger-java/tree/master/honeybadger-java/src/main/java/io/honeybadger/reporter/config/PlayConfigContext.java) - This reads configuration from the Play Framework’s internal configuration mechanism. * [ServletFilterConfigContext](https://github.com/honeybadger-io/honeybadger-java/tree/master/honeybadger-java/src/main/java/io/honeybadger/reporter/config/ServletFilterConfigContext.java) - This reads configuration from a servlet filter configuration. * [SpringConfigContext](https://github.com/honeybadger-io/honeybadger-java/tree/master/honeybadger-java/src/main/java/io/honeybadger/reporter/config/SpringConfigContext.java) - This reads configuration from the Spring framework’s internal configuration mechanism. * [StandardConfigContext](https://github.com/honeybadger-io/honeybadger-java/tree/master/honeybadger-java/src/main/java/io/honeybadger/reporter/config/StandardConfigContext.java) - This reads configuration from the system parameters, environment variables and defaults and is **the default configuration provider**. * [SystemSettingsConfigContext](https://github.com/honeybadger-io/honeybadger-java/tree/master/honeybadger-java/src/main/java/io/honeybadger/reporter/config/SystemSettingsConfigContext.java) - This reads configuration purely from system settings. #### Configuring with environment variables or system properties (12-factor style) [Section titled “Configuring with environment variables or system properties (12-factor style)”](#configuring-with-environment-variables-or-system-properties-12-factor-style) All configuration options can also be read from environment variables or [Java system properties](https://docs.oracle.com/javase/tutorial/essential/environment/sysprop.html) when using the default [StandardConfigContext](https://github.com/honeybadger-io/honeybadger-java/tree/master/honeybadger-java/src/main/java/io/honeybadger/reporter/config/StandardConfigContext.java). Framework specific configuration contexts use of environment variables or system properties depends on the framework’s implementation. ### Configuration options [Section titled “Configuration options”](#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 [Section titled “Custom error pages”](#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](https://mustache.github.io/) in your classpath and specifying its path via the `honeybadger.feedback_form_template_path` configuration option. ## Collecting user feedback (ServletFilter) [Section titled “Collecting user feedback (ServletFilter)”](#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 [Section titled “Using tags”](#using-tags) This version of honeybadger-java supports sending tags, but it requires invoking a new overload of 
```plaintext
  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 [Section titled “Supported JVM”](#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](https://github.com/honeybadger-io/honeybadger-java/issues/new). ## Supported frameworks [Section titled “Supported frameworks”](#supported-frameworks) | Framework | Version | Notes | | ---------------- | ------- | ----------------------------------------------------------------------------------------------------------------- | | Servlet API | 4.0.1 | | | Play Framework | 2.7.2 | We still call one deprecated API. See [Issue #110](https://github.com/honeybadger-io/honeybadger-java/issues/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](https://github.com/honeybadger-io/honeybadger-java/tree/master/honeybadger-java/src/main/java/io/honeybadger/reporter/servlet/HoneybadgerFilter.java) 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](https://github.com/honeybadger-io/honeybadger-java/tree/master/honeybadger-java/src/main/java/io/honeybadger/reporter/HoneybadgerReporter.java). You can find more information about this in the stand-alone usage section.