--- title: Guide to using the Ruby agent API source: https://docs.newrelic.com/docs/apm/agents/ruby-agent/api-guides/guide-using-ruby-agent-api --- The New Relic Ruby agent provides a public API with documentation available on RubyDoc. The RubyDoc documentation tells you how to set up custom instrumentation of your Ruby app and collect more in-depth data: - [Overview](https://www.rubydoc.info/gems/newrelic_rpm/) - [Public API methods](https://www.rubydoc.info/gems/newrelic_rpm/NewRelic/Agent) 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](https://docs.newrelic.com/docs/release-notes/agent-release-notes/ruby-release-notes/ruby-agent-3170325) or higher. ## Instrument missing sections of your code with transactions [#creating-transactions] To instrument your app, New Relic separates each path through your code into its own [transaction](https://docs.newrelic.com/docs/accounts-partnerships/education/getting-started-new-relic/glossary#transaction). New Relic times (or "instruments") the parent method in these transactions to measure your app's overall performance, and collects [transaction traces](https://docs.newrelic.com/docs/apm/transactions/transaction-traces/introduction-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](https://docs.newrelic.com/docs/agents/ruby-agent/customization/ruby-custom-instrumentation#transaction-tracers). | | Time something other than a single method call | Use the [Tracer API](https://docs.newrelic.com/docs/agents/ruby-agent/customization/ruby-custom-instrumentation#advanced-tracing). | | Prevent a transaction from reporting to New Relic | [Ignore](https://docs.newrelic.com/docs/agents/ruby-agent/customization/ignoring-specific-transactions) the transaction. | ## Time specific methods using segments [#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](https://docs.newrelic.com/docs/agents/ruby-agent/customization/ruby-custom-instrumentation#method_tracers). | | Time something other than a single method call | Use the [Tracer API](https://docs.newrelic.com/docs/agents/ruby-agent/customization/ruby-custom-instrumentation#advanced-tracing). | ## Enhance the metadata of a transaction [#metadata] 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](https://docs.newrelic.com/docs/agents/manage-apm-agents/troubleshooting/metric-grouping-issues#video). - You want to add [custom attributes](https://docs.newrelic.com/docs/agents/manage-apm-agents/agent-data/collect-custom-attributes) to your transactions so you can filter them in the [query builder](https://docs.newrelic.com/docs/query-your-data/explore-query-data/query-builder/use-advanced-nrql-mode-specify-data). 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](https://docs.newrelic.com/docs/agents/ruby-agent/customization/ruby-custom-instrumentation#naming-transactions). | | Add metadata (such as your customer's account name or subscription level) to your transactions | Use [custom attributes](https://docs.newrelic.com/docs/agents/manage-apm-agents/agent-data/collect-custom-attributes). See [Adding custom attributes](https://docs.newrelic.com/docs/agents/ruby-agent/attributes/ruby-agent-attributes#add-custom-attributes). | | Mark a transaction as a background job | See [Monitor custom background jobs](https://docs.newrelic.com/docs/agents/ruby-agent/background-jobs/monitor-ruby-background-processes#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](https://docs.newrelic.com/docs/agents/ruby-agent/customization/ruby-custom-instrumentation#naming-transactions). | | Prevent a transaction from affecting your [Apdex score](https://docs.newrelic.com/docs/apm/new-relic-apm/apdex/apdex-measuring-user-satisfaction) | See [Ignoring Apdex contributions](https://docs.newrelic.com/docs/agents/ruby-agent/customization/ignoring-specific-transactions#apdex). | ## See related logs [#logs] To see logs directly within the context of your application's errors and traces, use these API calls to annotate your logs: - [`linking_metadata`](https://www.rubydoc.info/gems/newrelic_rpm/NewRelic/Agent#linking_metadata-instance_method) - [`current_trace_id`](https://www.rubydoc.info/gems/newrelic_rpm/NewRelic/Agent/Tracer#current_trace_id-class_method) - [`current_span_id`](https://www.rubydoc.info/gems/newrelic_rpm/NewRelic/Agent/Tracer#current_span_id-class_method) For more information about correlating log data with other telemetry data, see our [logs in context](https://docs.newrelic.com/docs/logs/logs-context/configure-logs-context-ruby/) documentation. ## Collect or ignore errors [#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](https://docs.newrelic.com/docs/apm/applications-menu/error-analytics/ignoring-errors-new-relic-apm). | If you want to... | Do this... | | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Report an error the agent does not report automatically | See [Sending New Relic handled errors](https://docs.newrelic.com/docs/agents/ruby-agent/customization/sending-new-relic-handled-errors). | | Prevent the agent from reporting an error at all | Mark the error as ignored. See [Error Collector](https://docs.newrelic.com/docs/agents/ruby-agent/configuration/ruby-agent-configuration#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](https://docs.newrelic.com/docs/agents/ruby-agent/customization/sending-new-relic-handled-errors), and set `:expected` to `true`. | ## Send custom event and metric data from your app [#custom-data] APM includes a number of ways to record arbitrary custom data. For an explanation of New Relic data types, see [Data collection](https://docs.newrelic.com/docs/data-analysis/metrics/analyze-your-metrics/data-collection-metric-timeslice-event-data). | If you want to... | Do this... | | --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Send data about an event so you can analyze it in dashboards | Create a [custom event](https://docs.newrelic.com/docs/insights/insights-data-sources/custom-events). See [`record_custom_event()`](https://www.rubydoc.info/gems/newrelic_rpm/NewRelic/Agent#record_custom_event-instance_method). | | Tag your events with metadata to filter and facet them in dashboards or error analytics | Add [custom attributes](https://docs.newrelic.com/docs/agents/manage-apm-agents/agent-data/collect-custom-attributes). Pass a hash of attributes to [`record_custom_event()`](https://www.rubydoc.info/gems/newrelic_rpm/NewRelic/Agent#record_custom_event-instance_method). | | Report custom performance data | Create a [custom metric](https://docs.newrelic.com/docs/agents/manage-apm-agents/agent-data/custom-metrics). See [`record_metric()`](https://www.rubydoc.info/gems/newrelic_rpm/NewRelic/Agent#record_metric-instance_method). | ## Control the browser agent [#browser] Usually the browser monitoring 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](https://docs.newrelic.com/docs/browser/new-relic-browser/installation-configuration/add-apps-new-relic-browser). However, you can also retrieve the browser agent via APM agent API calls. For more information, see `browser_timing_header()`. ## Instrument calls to datastores [#async] 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 [#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 [#distributed] > #### ⚠️ IMPORTANT > > The following API examples require Ruby agent version 6.9.0 or higher. These APIs require [distributed tracing to be enabled](https://docs.newrelic.com/docs/enable-distributed-tracing). [Distributed tracing](https://docs.newrelic.com/docs/apm/distributed-tracing/getting-started/introduction-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](https://docs.newrelic.com/docs/enable-distributed-tracing#agent-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()`. |