Manage errors in APM: Collect, ignore, or mark expected

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:

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

New Relic also marks expected errors with an error.expected attribute, so you can alert on a high number of expected errors using alert conditions for NRQL queries.

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:

For more help

Recommendations for learning more: