Sending handled errors to 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 call within your error handler.

Notify the New Relic Ruby agent of an error

This API call takes the exception and an optional options hash. Use this format:

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

Error fingerprinting: Dynamically apply an error group to each noticed error

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 to each noticed error. Use the Ruby agent API NewRelic::Agent.set_error_group_callback 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:

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:

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

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

Errors inbox will automatically track which versions of your software are producing errors. Any version data will also display in CodeStream.

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