New Relic APM agents automatically collect error data for supported frameworks. However, you may want to collect error data from a framework without default instrumentation, or catch an error that New Relic is not noticing by default. Similarly, sometimes New Relic detects an error that you don't want reported because it's too common and is affecting your error rate.
This document covers how to manage errors for your New Relic APM agent to optimize your instrumentation and alerting.
Collect errors not instrumented by default
New Relic APM agents include API calls to collect (or "notice") and report errors. These are useful when New Relic does not instrument your framework automatically, or when there are particular errors that New Relic is not catching for your supported framework.
To tell the agent to report an error, see the API documentation for your agent:
Ignore an error or mark it as expected
Sometimes the APM agent instruments an error you don't want reported. For example, the error may contain sensitive information, or it may simply be a very frequent error that is affecting your error rate. Common examples are user login errors, or HTTP status codes like 401, 403 and 5xx errors.
For errors you don't want reported to the New Relic collector at all, you can ignore the error. This tells the APM agent to discard the error entirely. For many agents you can also ignore errors based on their HTTP status code.
To tell the agent to ignore an error, see the configuration documentation for your agent:
ignore_status_codes. For additional information, see Java agent error configuration.
In the Java and Ruby agents, you can also mark an error as "expected." An expected error is still reported to the collector and visible in New Relic APM UI and New Relic Insights, but it doesn't affect the Apdex or error rate (including alert conditions based on error rate). This ensures common errors are not affecting your data, but are still visible in case something unusual going on (such as a large spike in login errors indicating a hacking attempt).
To tell the agent to mark an error as expected, see the agent documentation:
View errors in the UI
Among other places, error data appears in these parts of the New Relic UI:
- Use error analytics for in-depth charts and visual analysis of your errors.
- View high-level error rates on the APM Overview page.
- Create alert conditions based on error rate.
- Use the
transactionErrorevent in New Relic Insights. It contains the underlying error data, which you can query with NRQL.