This document details how to instrument third-party gems with the Ruby agent, as well as some best practices for interacting with the agent. This is useful if you are using a gem that the Ruby agent does not instrument by default, or if you are a gem author who wants to add instrumentation for your library.
Anyone can write a gem that builds on top of the Ruby agent. New Relic maintains a repository called extends_newrelic_rpm to track these extensions and to provide links to other gems that build the Ruby agent.
These extensions are not supported by New Relic. New Relic gathers these links as a service to our customers. Issues with those gems should be reported to the respective projects on GitHub.
New Relic encourages third-party extensions to be maintained as gems, with one gem per instrumented library. For example,
newrelic-redis provides instrumentation for the
If your library provides code which should be represented as a full transaction in New Relic (for example: a web request or background job that isn't instrumented by the Ruby agent), then use one of these mechanisms for starting a transaction.
You may want to add timing information to New Relic about calls to a method, but it does not represent a full transaction. New Relic recommends adding a method tracer to accomplish this.
The Ruby agent provides special functionality for recording calls to Datastores. These are intended to support both SQL and NoSQL databases, and provide a consistent interface for use by third-party gems.
Metrics recorded via the
NewRelic::Agent::Datastores module functions will show up in the Databases UI in New Relic.
You can write automated tests when you author a gem that extends New Relic. The test helpers used by the agent itself are available to simplify some common testing tasks.
If you need more help, check out these support and learning resources:
- Browse the Explorers Hub to get help from the community and join in discussions.
- Find answers on our sites and learn how to use our support portal.
- Run New Relic Diagnostics, our troubleshooting tool for Linux, Windows, and macOS.
- Review New Relic's data security and licenses documentation.