New Relic Ruby Agent: What the Gem Does, How It Starts, and Where It Stops
New Relic RPM Ruby Agent
At a glance
- What is it?
- The New Relic Ruby agent is an Apache-2.0 APM instrumentation library that loads into a Ruby process and reports performance and business data to New Relic. It is a good fit if you already pay for that platform, and the wrong fit if you want to store the telemetry yourself.
- Who is it for?
- Adopt it if your team already runs New Relic APM and you want Rails, Rack or background-job traces without writing instrumentation yourself. Do not adopt it if you need the telemetry to stay inside your own infrastructure, because the agent reports to New Relic's collector and the gem gives you no local storage path.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository received new commits within the last day.
- What is it written in?
- Mainly Ruby, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The gap it fills: Ruby processes that report nothing
A Rails app under load does not tell you which controller action is slow, which background worker is stuck, or how often a database call is repeated inside a single request. You can add timing code by hand, but the work multiplies with every framework, gem and job runner in the stack. The New Relic Ruby agent exists to remove that work. The README describes it as monitoring applications to help identify and solve performance issues, and it also collects business data for analysis.
The audience is narrow and specific. This is for teams that already use New Relic as their observability platform and run Ruby, whether that is a Rails application, a pure Rack service, a background job process, or a function on AWS Lambda or Google App Engine flexible environment. The installation docs linked from the README list exactly those scenarios. If you are not a New Relic customer, the agent has nothing to send data to, and installing it buys you nothing.
How the agent attaches to a running Ruby process
The gem is dual-purposed, in the README's wording, as either a Gem or a Rails plugin. That phrasing matters. There is no separate daemon and no sidecar container. The agent is a library that loads inside your process, so it sees method calls and database queries from the inside rather than sampling from outside.
Loading happens through the normal Ruby require path. With Bundler you add the gem to the Gemfile and run bundle install. Without Bundler you install the gem and require it in your start-up sequence. For frameworks and non-framework environments that do not trigger the agent automatically, the README gives one explicit entry point: NewRelic::Agent.manual_start. That call is the boundary between "the gem is installed" and "the agent is collecting". A process that never calls it and is not covered by a framework integration will stay silent, which is the most common reason a deployment shows no data.
The README does not describe the internal instrumentation pipeline, the harvest cycle, or how spans are assembled. Anything beyond the load path and manual_start would be guesswork, so treat the source tree as the place to look if you need that level of detail.
Getting it running: two install paths and one start call
The README gives two installation routes. With Bundler, add this line to your Gemfile:
gem 'newrelic_rpm'
then run bundle install. Without Bundler, run gem install newrelic_rpm and add require 'newrelic_rpm' to your Ruby start-up sequence.
For environments where the agent does not start on its own, the README says to add NewRelic::Agent.manual_start to the start-up sequence. That is the full set of commands the README provides. Configuration keys are not listed there; the README points to a separate configuration page on the docs site, and the troubleshooting guide for the no-data case is likewise external. If you are evaluating the agent from the repository alone, expect to leave the README quickly and read the docs site.
Support runs through New Relic's own channels rather than the issue tracker alone. The README names NRDiag, a client-side diagnostic utility that detects common problems with New Relic agents, suggests troubleshooting steps, and can attach diagnostic data to a support ticket. Bugs and feature requests go to GitHub issues. Contributions require signing a Contributor License Agreement through CLA-Assistant, once per project, with a corporate CLA for company work.
Where the agent is the wrong tool
The agent reports to New Relic. That is the whole design, and it is also the limitation. There is no documented path in the README for writing the collected data to your own storage, so if your requirement is that traces and business data never leave your infrastructure, this gem does not meet it regardless of how well it instruments Ruby. The privacy section reinforces the point from the other direction: it asks users to scrub logs and diagnostic information for personal data before sharing them in public forums, which tells you the vendor expects sensitive material to be handled carefully around the tooling.
A second constraint is version coupling. The README defers the list of supported Ruby versions and frameworks to the docs site rather than stating it in the repository. That means an upgrade of Ruby or of a major framework can outpace the agent, and you will not learn that from the README. Verify your exact combination against the supported-frameworks page before you plan a rollout.
A third is the support model. The README labels this a community plus project and directs troubleshooting to New Relic support, NRDiag and the docs site. If you are not entitled to ticketed support, your fallback is the public issue tracker and the troubleshooting guide. That is workable, but it is a different experience from a vendor-supported agent.
What a self-hosted alternative changes
The obvious comparison is OpenTelemetry's Ruby instrumentation, which is also a library that loads inside your process and also instruments Rails, Rack and common gems. The difference is not the instrumentation style. It is where the data goes. OpenTelemetry emits spans through the OpenTelemetry Protocol to whatever backend you configure, so you can point it at a self-hosted collector and keep the data on your own network. The New Relic agent, as documented here, sends to New Relic.
That single difference drives most of the choice. If you already have a New Relic account and want the agent's Rails, Rack, Lambda and background-job coverage without assembling and maintaining an instrumentation set yourself, the New Relic agent is less work. If you need vendor portability or on-premises storage, OpenTelemetry is the direction that keeps that option open, at the cost of running the collector and choosing a backend. Both are Apache-2.0 licensed open source, so the licence is not the deciding factor.
Maintenance, upgrades and the licence in practice
The repository is on the dev branch and shows a steady release cadence, with 10.7.1 published in August 2026 and 10.7.0 earlier the same month, plus a pre-release build between them. A pre-release tag ahead of a patch release is a normal pattern and suggests fixes are being staged before general availability. The README states the code is actively maintained by New Relic engineering teams and delivered on GitHub, and it links a dedicated page on updating the agent.
The practical upgrade cost is the coupling described earlier. Because supported Ruby and framework versions live on an external page rather than in the repository, every agent bump is a two-step check: read the release notes, then confirm your runtime is still on the supported list. For a large application, that check is the real cost of the dependency, not the gem install itself.
On licensing, the repository is Apache-2.0. That covers the agent code you install. It does not cover the New Relic service the agent reports to, which is governed by your commercial agreement with New Relic, and it does not cover the privacy notice the README references for personal data handling. Read those separately; this is a description of what the repository states, not legal advice.
Editorial conclusion
Adopt it if your team already runs New Relic APM and you want Rails, Rack or background-job traces without writing instrumentation yourself. Do not adopt it if you need the telemetry to stay inside your own infrastructure, because the agent reports to New Relic's collector and the gem gives you no local storage path. Before rolling it out, read the supported-frameworks page for your exact Ruby version, then confirm whether your process needs an explicit NewRelic::Agent.manual_start call or whether the framework integration starts the agent on its own.
Community notes