--- title: Sending handled errors to New Relic source: https://docs.newrelic.com/docs/apm/agents/ruby-agent/api-guides/sending-handled-errors-new-relic --- To send error data that you are handling in your own code to New Relic, use the Ruby agent API [`NewRelic::Agent.notice_error`](https://www.rubydoc.info/gems/newrelic_rpm/NewRelic/Agent#notice_error-instance_method) call within your error handler. ## Notify the New Relic Ruby agent of an error [#solution] This API call takes the exception and an optional options hash. Use this format: ```rb NewRelic::Agent.notice_error(exception, options = { }) ⇒ Object ``` This function records the given error and passes it through the normal error filtering process, including [configuration-based ignoring of errors](https://docs.newrelic.com/docs/agents/ruby-agent/installation-configuration/ruby-agent-configuration#error_collector.ignore_errors) and the global `#ignore_error_filter` method if defined. The `exception` is the exception to be recorded, or an error message. If needed, you can also include `options = { }`. The following parameters will receive special treatment, and any other parameters you supply will be treated as custom parameters. | **options = { }** | **Comments** | | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `:expected` | [Only records the error trace](https://docs.newrelic.com/docs/agents/manage-apm-agents/agent-data/manage-errors-apm-collect-ignore-mark-expected#expected-links). This does not affect the error rate or Apdex status. For information on expected errors in the UI, see [View expected errors](https://docs.newrelic.com/docs/agents/manage-apm-agents/agent-data/manage-errors-apm-collect-ignore-or-mark-expected#expected). Replaces the `:trace_only` option, which was deprecated in version [4.3.x](https://docs.newrelic.com/docs/release-notes/agent-release-notes/ruby-release-notes/ruby-agent-430335) of the Ruby agent. | | `:custom_params` | Custom parameters. | | `:uri` | The request path, minus any request parameters or query string. Usually not needed. Include this only if you are calling `notice_error` outside a transaction. | | `:metric` | The metric name associated with the transaction. Usually not needed. Include this only if you are calling `notice_error` outside a transaction. | | `:request_params` (deprecated) | Older Ruby agent versions allowed passing a `:request_params` option, but those are now ignored. If you need to record the request parameters, call this method inside a transaction, or pass the information in `:custom_params`. | ## Error fingerprinting: Dynamically apply an error group to each noticed error [#error-fingerprinting] Are your error occurrences grouped poorly? Set your own error fingerprint via a callback function. A `Proc` based callback can be supplied to the agent to dynamically apply a desired [error group](https://docs.newrelic.com/docs/errors-inbox/errors-inbox/#how-groups-work) to each noticed error. Use the Ruby agent API [`NewRelic::Agent.set_error_group_callback`](https://www.rubydoc.info/gems/newrelic_rpm/NewRelic/Agent#set_error_group_callback-instance_method) to provide the agent with a callback. This API call takes a callback method (must be of type `Proc`) as its only argument. The argument is required. The API call only needs to be made once per New Relic Ruby agent launch, so the call can be placed in a Rails initializer or similar. If subsequent calls to the API are made, the callback method will update to the newest one provided. Here's an example of a callback being defined and passed to the `NewRelic::Agent.set_error_group_callback` API method: ```rb proc = proc { |hash| "Access" if hash[:'http.statusCode'] == 401 } NewRelic::Agent.set_error_group_callback(proc) ``` In the example shown, a callback proc is created that will accept a hash as its only argument and then return the string "Access" for the desired error group name if the hash contains an HTTP status code key with a value of 401. The callback proc is expected to receive exactly one input argument, a hash. The hash contains the following: | **Key** | **Value** | | -------------------- | ---------------------------------------------------------------------------- | | `:error` | The Ruby error class instance. Offers `#class`, `#message`, and `#backtrace` | | `:customAttributes` | Any custom attributes for the current transaction | | `:'request.uri'` | The current requeset URI if available | | `:'http.statusCode'` | The HTTP status code (200, 404, etc.) if available | | `:'http.method'` | The HTTP method (GET, PUT, etc.) if available | | `:'error.expected'` | Whether (true) or not (false) the error was expected | | `:'options'` | The options hash passed to `NewRelic::Agent.notice_error` | The callback proc is expected to return a string representing the desired error group name if one can be determined. If the proc returns a `nil` or empty string (`''`), then the error will receive server-side grouping logic. ## User tracking: Associating a user ID with each transaction and error [#user-tracking] You can now see the number of users impacted by an error group. Transactions and errors can be associated with a user ID if one is known to the New Relic Ruby agent. Use the Ruby agent API [`NewRelic::Agent.set_user_id`](https://www.rubydoc.info/gems/newrelic_rpm/NewRelic/Agent#set_user_id-instance_method) to provide the agent with a user ID. This API call requires a single argument of a string representing a unique identifier for an end user. This string can be a UUID, a database id, or similar. The API call should be made at least once per transaction to inform the New Relic Ruby agent of what user ID to associate the transaction with. Then in turn, when the agent notices errors during the lifespan of the transaction, the errors will bear an `enduser.id` agent attribute that holds the user ID value. Because the API is intended to be called every time a new user ID has entered scope, it will ideally be called via middleware that is aware of user session creation. Once the New Relic Ruby agent has been made aware of the user ID, it will supply the `enduser.id` agent attribute on the current transaction as well as on any errors noticed during the current transaction's lifespan. ## Version tracking: Use metadata to see what version produced an error [#version-tracking] [Errors inbox](https://docs.newrelic.com/docs/errors-inbox/version-tracking/) will automatically track which versions of your software are producing errors. Any version data will also display in [CodeStream](https://docs.newrelic.com/docs/codestream/how-use-codestream/performance-monitoring/#buildsha). Set one of the following environment variables to help identify which versions of your software produce errors. - `NEW_RELIC_METADATA_SERVICE_VERSION` adds the attribute `tags.service.version` on error event data containing the version of your code that's deployed, often a semantic version such as `1.2.3`, but not always. - `NEW_RELIC_METADATA_RELEASE_TAG` adds the attribute `tags.releaseTag` on event data containing the release tag (such as `v0.1.209` or `release-209`). - `NEW_RELIC_METADATA_COMMIT` adds the attribute `tags.commit` on event data containing the commit sha. You can use the entire sha or just the first seven characters (for example, `734713b`).