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:
Error reporting
Comments
Unhandled errors (includes stack trace)
If an unhandled error occurs within a transaction that the Java agent was tracing, the error will be reported with the full stack trace.
HTTP status codes (no stack trace)
When a transaction in your application generates an HTTP status code, for example, 400 for a client error, it reports the error without a stack trace. The reasons for this are:
The application server has detected an error condition and explicitly set the status code.
OR
The program logic detected the error condition, so there was no exception object or stack.
In order to include the stack trace with these types of transactions, you must use a noticeError(...) API call.
noticeError(...) API calls
If the Java agent makes an explicit call using the noticeError(...) API call, the error will be reported regardless of whether or not it occurs within a transaction. The reported information depends on the parameters used in the noticeError(...) API call, as described in the Javadocs.
Unscoped errors reporting over 100%
The Java agent can report unscoped errors, which are errors that are not tied to any transaction. Because of this, it is possible to have one transaction in a timeslice and multiple errors in the same timeslice. In this situation, New Relic would then show an error rate over 100%.
Configure error reporting
Importante
In order to use this feature, upgrade to the latest release (Java agent 3.40.0 or higher).
The Java agent provides several flexible configuration options to control how errors are reported.
Errors reported by these versions of noticeError can be configured as expected errors in the newrelic.yml. Calls to this API will be overridden if the error is configured as ignored in newrelic.yml. For details, see Error configuration precedence.
Use these noticeError() API calls to report errors that are not reported automatically and configure them as expected errors in newrelic.yml:
Errors reported by these versions of noticeError will override the newrelic.ymlexpected error configuration. Calls to this API will be overridden if the error is configured as ignored in the yml. For details, see Error configuration precedence.
Use these noticeError(...) API calls to report errors that are not reported automatically and configure them as expected errors with the API (overrides yml expected error configuration):
In versions 3.40.0 or higher, you can control how errors are reported by using the YAML-based configuration. This allows you to ignore errors or expect errors based on HTTP status codes or based on a list of exception class names plus an optional error message.
Ignoring errors prevents the specified exception classes or codes from being reported to at all.
Expecting errors prevents the specified exception classes or codes from affecting your application's error rate and Apdex score. This allows you to retain the error information for troubleshooting purposes while avoiding alerts based on error rate or Apdex score.
These settings are dynamic, so running agents will notice changes to newrelic.yml without a JVM restart. For more information and examples, see the Java agent config file.
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
By default, the Java agent includes an error_collector section under which all YAML-based error configuration options are found. Error collection can be enabled or disabled as follows:
error_collector:
enabled:true
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
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.
expected parameter in the noticeError(..) API call
expected_* config in the YAML
Here are examples of the results when combining various API calls and YAML configurations.
YAML configuration:
error_collector:
ignore_classes:
-"com.example.ErrorClass"
and
API call:
noticeError(com.example.ErrorClass)
Result:
The YAML ignore_classes overrides the noticeError API call, and the error is ignored.
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.
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).
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.
Examine logs for error details
You can bring your logs and application's data together to make troubleshooting easier and faster. With logs in context, you can see log messages related to your errors and traces directly in your app's UI.