• EnglishEspañol日本語한국어Português
  • Log inStart now

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.

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:

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

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

Copyright © 2024 New Relic Inc.

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.