Java agent error configuration

APM's Java agent reports detailed information about errors that occur within your application. This gives you insight into problematic areas that may be affecting your application’s performance or the end user’s experience.

With Java agent versions 3.40.0 or higher, there are several configuration options that let you control how errors are reported, including:

• Configuring expected errors so that they won't affect error rate or Apdex
• Ignoring errors
• Reporting errors that are not reported automatically

For more information on viewing your error data, see Error analytics. For an overview of error data in all agents, see Manage errors in APM.

Common reported error examples

The Java agent reports errors in the following scenarios:

Configure error reporting

The Java agent provides several flexible configuration options to control how errors are reported.

YAML-based configuration for error collection

YAML-based configuration for error collection allows you to entirely ignore specific errors or exempt expected errors from affecting your application’s error rate and Apdex score. You can mark errors as ignored or expected based on the following criteria:

• A given range of HTTP status codes, presented as a comma-separated list or dashed range
• A comma-separated list using the fully qualified name of a package/class and an optionally provided error message string

Enabling error collection

By default, the Java agent includes an error_collector stanza under which all YAML-based error configuration options will be found. Error collection can be enabled or disabled as follows:

error_collector:
  enabled: true

Ignoring specific errors

Errors that are not of any particular interest can be ignored entirely. By identifying errors to ignore:

• They will not be reported to APM.
• They will not affect your application's error rate or Apdex score

Here is an example showing the YAML-based configuration options for ignoring errors:

  error_collector:
    enabled: true

    ignore_classes:
      - "com.example.ErrorClassToIgnore"

    ignore_messages:
      com.example.OtherErrorClassToIgnore:
        - "some error message to ignore"

    ignore_status_codes: 404,507-511

Preventing expected errors from affecting error rate and Apdex

Errors that are expected as part of an application's business logic can be prevented from affecting error rate or Apdex score yet still be reported to APM. This allows you to retain the error information in the UI for troubleshooting purposes while avoiding alerts (based on error rate and Apdex score) caused by these errors.

Here is an example showing the YAML-based configuration options for expected errors:

  error_collector:
    enabled: true

    expected_classes:
      - "com.example.ExpectedErrorClass"

    expected_messages:
      com.example.OtherExpectedErrorClass:
        - some expected error message"

    expected_status_codes: 406,500-504

Error configuration precedence

The priority for errors configuration is:

1. Server-side configuration (overlays values onto YAML file)
2. ignore_* config in the YAML
3. expected parameter in the noticeError(..) API call
4. expected_* config in the YAML

Here are examples of the results when combining various API calls and YAML configurations.

Ignore error classes (YAML overrides API)

YAML configuration:

error_collector:
  ignore_classes:
    - "com.example.ErrorClass"

AND

API call:

noticeError(com.newrelic.Exception)

Result:

The YAML ignore_classes overrides the noticeError API call, and the error is ignored.

Report expected errors (YAML and API)

YAML configuration:

error_collector:
  expected_classes:
    - "com.example.ErrorClass"

AND

API call:

noticeError(com.newrelic.Exception)

Result:

The expected parameter in the noticeError API call is true by default, and the YAML expected_classes configuration contains an error class. Therefore, the error is reported and marked as expected.

Report expected errors (no YAML)

No YAML configuration

AND

API call:

noticeError(com.newrelic.Exception, expected = true)

Result:

The error is reported and marked as expected.

YAML ignore_classes overrides API expected parameter

YAML configuration:

error_collector:
  ignore_classes:
    - "com.example.ErrorClass"

AND

API call:

noticeError(com.newrelic.Exception, expected = true)

Result:

The YAML ignore_classesoverrides the expected parameter in the noticeError API call, so the error is ignored.

API expected parameter overrides YAML expected_classes

YAML configuration:

error_collector:
  expected_classes:
    - "com.example.ErrorClass"

AND

API call:

noticeError(com.newrelic.Exception, expected = false)

Result:

The expected parameter in the noticeError API call overrides expected_classes in the YAML. Therefore, the error is reported as normal (not marked as expected).

Ignore overrides expected in YAML

YAML configuration:

error_collector:
  ignore_classes:
    - "com.example.ErrorClass"

AND

Additional YAML configuration:

error_collector:
  expected_classes:
    - "com.example.ErrorClass"

Result:

The YAML ignore_classes/ignore_messages overrides the YAML expected_classes/expected_messages, so the error is ignored. This same principle applies to ignore_status_codes and expected_status_codes.

Configure ignored and expected errors via UI

To configure expected errors via the APM UI:

1. If it is not already enabled, enable server-side configuration.
2. Go to the server-side configuration menu for the application with errors you want to mark as expected.
3. Under Error collection, for either Ignore or Exclude expected errors, enter the HTTP code or the error class for errors you want to configure.
4. Select Save.

For information on how to view expected errors in the UI, see View expected errors.

For more help