Guide to using the Ruby agent API

The New Relic Ruby agent provides a public API available on GitHub that you can use to set up custom instrumentation of your Ruby app and collect more in-depth data. Below, you can find common goals, solutions, and links to relevant parts of the documentation.

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

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 are not useful. For example:

Use these methods when you want to change how New Relic instruments a transaction that is 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 See Monitor custom background jobs.
Mark a transaction as a web transaction Pass a :category => :controller option to set_transaction_name(). For more information, see Naming transactions.
Prevent a transaction from affecting your Apdex score See Ignoring Apdex contributions.

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 See Sending New Relic handled errors.
Prevent the agent from reporting an error at all Mark the error as ignored. See Error Collector to use the error_collector.ignore_errors config option.
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 :expected to true.

Send custom event and metric data from your app

New Relic 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 New Relic Insights Create a custom event. See record_custom_event().
Tag your events with metadata to filter and facet them in Insights or error analytics Add custom attributes. Pass a hash of attributes to record_custom_event().
Report custom performance data once a minute Create a custom metric. See record_metric().

Control the New Relic Browser agent

Usually the Browser 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 New Relic Browser. However, you can also retrieve the New Relic 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 wrap().
Capture SQL queries along with timing See notice_sql().
Capture non-SQL queries along with timing See notice_statement().

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 start_segment().
Add cross-account tracing (CAT) headers to an outbound HTTP request Use add_request_headers().
Read CAT headers from an inbound HTTP request Use read_response_headers().
Generate an obfuscated string to transport CAT information in an outbound request Use get_request_metadata().
Process an obfuscated string containing CAT information received from an inbound request Use process_response_metadata().

Instrument calls for distributed tracing

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...
Create a payload to be sent to a called service See create_distributed_trace_payload().
Accept a payload sent from the first service, which will link these services together in a trace See accept_distributed_trace_payload().

For more help

Recommendations for learning more: