The New Relic Ruby agent provides a public API with documentation available on GitHub. The GitHub documentation tells you how to set up custom instrumentation of your Ruby app and collect more in-depth data:
The following sections explain common goals, solutions, and links to relevant parts of the documentation.
Important
When using the Ruby agent API, ensure that you have the latest Ruby agent release. Several APIs used in the following examples require Ruby agent version 4.6.0 or higher.
Instrument missing sections of your code with transactions
To instrument your app, New Relic separates each path through your code into its own transaction. New Relic times (or "instruments") the parent method in these transactions to measure your app's overall performance, and collects transaction traces from long-running transactions for additional detail.
Use these methods when New Relic is not instrumenting a particular part of your code at all:
If you want to... | Do this... |
|---|---|
Time a method New Relic is not instrumenting automatically | Create a new transaction. See Tracing transaction entry points. |
Time something other than a single method call | Use the Tracer API. |
Prevent a transaction from reporting to New Relic | Ignore the transaction. |
Time specific methods using segments
If a transaction is already visible in the New Relic UI, but you don't have enough data about a particular method that was called during that transaction, you can create segments to time those individual methods in greater detail. For example, you might want to time a particularly critical method with complex logic.
Use these methods when you want to instrument a method within an existing transaction:
If you want to... | Do this... |
|---|---|
Time a particular method | See Method tracers. |
Time something other than a single method call | Use the Tracer API. |
Enhance the metadata of a transaction
Sometimes the code you are targeting is visible in the New Relic UI, but some details of the method aren't useful. For example:
- The default name is causing a metric grouping issue.
- You want to add custom attributes to your transactions so you can filter them in the query builder.
Use these methods when you want to change how New Relic instruments a transaction that's already visible in the New Relic UI:
If you want to... | Do this... |
|---|---|
Change the name of a transaction | See Naming transactions. |
Add metadata (such as your customer's account name or subscription level) to your transactions | Use custom attributes. See Adding custom attributes. |
Mark a transaction as a background job | |
Mark a transaction as a web transaction | Pass a |
Prevent a transaction from affecting your Apdex score |
See related logs
To see logs directly within the context of your application's errors and traces, use these API calls to annotate your logs:
For more information about correlating log data with other telemetry data, see our logs in context documentation.
Collect or ignore errors
Usually the agent detects errors automatically. However, you can manually mark an error with the agent. You can also mark errors as ignored or expected.
If you want to... | Do this... |
|---|---|
Report an error the agent does not report automatically | |
Prevent the agent from reporting an error at all | Mark the error as ignored. See Error Collector to use the |
Prevent an error from affecting your Apdex or error rate, but still report it to New Relic | Mark the error as expected. See Sending New Relic handled errors, and set |
Send custom event and metric data from your app
APM includes a number of ways to record arbitrary custom data. For an explanation of New Relic data types, see Data collection.
If you want to... | Do this... |
|---|---|
Send data about an event so you can analyze it in dashboards | Create a custom event. See |
Tag your events with metadata to filter and facet them in dashboards or error analytics | Add custom attributes. Pass a hash of attributes to |
Report custom performance data | Create a custom metric. See |
Control the browser agent
Usually the agent is added automatically to your pages or deployed by copy/pasting the JavaScript snippet. For more information about these recommended methods, see Add apps to browser monitoring. However, you can also retrieve the browser agent via APM agent API calls. For more information, see browser_timing_header().
Instrument calls to datastores
Use these methods to collect data about your app's connections to other datastores:
If you want to... | Do this... |
|---|---|
Time a call to a datastore not instrumented automatically by New Relic | See |
Time a datastore call that can't cleanly be wrapped in a Ruby block | See |
Capture SQL queries along with timing | See |
Capture non-SQL queries along with timing | See |
Instrument calls to externals
Use these methods to collect data for external requests:
If you want to... | Do this... |
|---|---|
Time a call to an external request not instrumented automatically by New Relic | Use |
Add cross-application tracing (CAT) headers to an outbound HTTP request | Use |
Read CAT headers from an inbound HTTP request | Use |
Generate an obfuscated string to transport CAT information in an outbound request | Use |
Process an obfuscated string containing CAT information received from an inbound request | Use |
Instrument calls for distributed tracing
Important
The following API examples require Ruby agent version 6.9.0 or higher.
These APIs require distributed tracing to be enabled.
Distributed tracing lets you see the paths requests take as they travel through a distributed system.
For general instructions on how to use the calls below to implement distributed tracing, see Use distributed tracing APIs.
If you want to... | Do this... |
|---|---|
Send a payload/header to the called service. | See |
Accept a payload/header received from the first service, which will link these services together in a trace | See |