Guide to using the Ruby agent API

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.

重要

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

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

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

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 `wrap()`.
Time a datastore call that can't cleanly be wrapped in a Ruby block	See `Tracer.start_datastore_segment()`. You must call `finish` on the object returned by this method.
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 `Tracer.start_external_segment()`. You must call `finish` on the object returned by this method.
Add cross-application 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

重要

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 `insert_distributed_trace_headers()`.
Accept a payload/header received from the first service, which will link these services together in a trace	See `accept_distributed_trace_headers()`.

重要

Instrument missing sections of your code with transactions .css-21sua1{background:none;border:none;width:0;padding:0;}