• /
  • Log in

Third party instrumentation

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.

Finding third-party extensions

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.

Extensions as gems

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

Starting transactions

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.

Nodes in transaction traces

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.

Custom Datastores

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.

Testing your extension

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.

For more help

If you need more help, check out these support and learning resources:

Create issueEdit page
Copyright © 2021 New Relic Inc.