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 = { }) ⇒ ObjectThis 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.
options = { } | Comments |
|---|---|
| Only records the error trace. This does not affect the error rate or Apdex status. For information on expected errors in the UI, see View expected errors. Replaces the |
| Custom parameters. |
| The request path, minus any request parameters or query string. Usually not needed. Include this only if you are calling |
| The metric name associated with the transaction. Usually not needed. Include this only if you are calling |
| Older Ruby agent versions allowed passing a |
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:
Key | Value |
|---|---|
| The Ruby error class instance. Offers |
| Any custom attributes for the current transaction |
| The current requeset URI if available |
| The HTTP status code (200, 404, etc.) if available |
| The HTTP method (GET, PUT, etc.) if available |
| Whether (true) or not (false) the error was expected |
| The options hash passed to |
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_VERSIONadds the attributetags.service.versionon error event data containing the version of your code that's deployed, often a semantic version such as1.2.3, but not always.NEW_RELIC_METADATA_RELEASE_TAGadds the attributetags.releaseTagon event data containing the release tag (such asv0.1.209orrelease-209).NEW_RELIC_METADATA_COMMITadds the attributetags.commiton event data containing the commit sha. You can use the entire sha or just the first seven characters (for example,734713b).