# newrelic-rpm: the New Relic Ruby agent, from Gemfile to first transaction

> The newrelic_rpm gem instruments Rails, Rack and background Ruby processes and ships data to New Relic. It is a commercial-backend agent, not a self-hosted APM, and the repository is mostly instrumentation code plus a test harness.

**newrelic/newrelic-ruby-agent** — New Relic RPM Ruby Agent

- Repository: https://github.com/newrelic/newrelic-ruby-agent
- Website: https://docs.newrelic.com/docs/apm/agents/ruby-agent/getting-started/introduction-new-relic-ruby/
- Stars: 1,209 · Forks: 609
- Language: Ruby
- License: Apache-2.0
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/newrelic-newrelic-ruby-agent

## What newrelic-ruby-agent is for, and who should care

The New Relic Ruby agent is an APM instrumentation library. Its stated job is to monitor applications so you can identify and solve performance issues, and the README adds a second purpose: collecting and analyzing business data to improve customer experience and support data-driven decisions. Both purposes route through New Relic's platform, so the audience is teams that already pay for or plan to use New Relic, not teams shopping for a standalone profiler.

The agent is dual-purposed as a Gem or a Rails plugin, and the README points at RubyGems.org for the released gem. It is not limited to web apps: a section titled Other Environments covers frameworks and non-framework processes, which is where background workers and plain Ruby scripts land. If your stack is Rails with Sidekiq, or a Rack service behind a load balancer, this is the intended shape. If you are running a small script and want a flame graph on your laptop, the agent is the wrong size of tool.

## How the agent attaches to a Ruby process

The mechanism visible in the repository is instrumentation plus a configuration file plus a reporting loop. The gem ships a newrelic.yml at the top level, which is the configuration surface the docs describe. Loading the gem hooks into frameworks and libraries, records transactions, and sends that data to New Relic's collector using the account credentials in the config.

Two entry points matter. With Bundler, requiring the gem is enough in the common Rails case, because the agent starts itself. Outside that path, the README says you may need to tell the agent to start, and gives NewRelic::Agent.manual_start for the purpose. That distinction is the practical boundary between "it just works" and "I see no data": a script that never requires the gem, or a process where the framework integration does not fire, produces nothing until manual_start is called.

The repository layout backs the instrumentation story. lib/ holds the agent code, test/ holds the suite, and there is an infinite_tracing/ directory alongside a docker-compose.yml that stands up Elasticsearch 7, 8 and 9, MySQL, RabbitMQ, Memcached and more for tests. Those services are test fixtures for the instrumented libraries, not part of a production deployment. The Dockerfile is equally a development image: it takes a ruby_version build argument defaulting to 3.1, copies the tree, runs bundle install, and its CMD is bundle exec rake. Nothing there is a production runtime recipe.

## Installing the newrelic_rpm gem and starting it in a real app

With Bundler, the README gives a single Gemfile line. Add it and run bundle install.

```ruby
gem 'newrelic_rpm'
```

Without Bundler, the README gives the gem command instead.

```bash
gem install newrelic_rpm
```

Then require the agent in your Ruby start-up sequence.

```ruby
require 'newrelic_rpm'
```

For frameworks and non-framework environments where the agent does not start on its own, the README says to add this to the start-up sequence.

```ruby
NewRelic::Agent.manual_start
```

What you should see after this is the agent loading and connecting to New Relic using the credentials from newrelic.yml. The README does not walk through generating that file or filling in the licence key; it defers the complete install instructions to the docs site, linking separate pages for Rails plugin installation, AWS Lambda, GAE Flexible Environment, pure Rack apps, Heroku and background jobs. Treat those links as the real install path. The repository gives you the gem and the start call, not the account setup.

## Where the agent stops being the right tool

The agent reports to New Relic. Nothing in the README describes a local-only mode, a file exporter, or a second backend, so if your requirement is data residency in your own store or a vendor-neutral OpenTelemetry pipeline, this gem does not satisfy it. The README's privacy section is explicit that New Relic defines personal data broadly, including IP addresses, and asks users to scrub logs and diagnostic information before posting them publicly. That is a statement about support forums, but it signals the general posture: data leaves your process.

A second limitation is coverage. The README does not enumerate instrumented libraries or Ruby versions in the repository; it points to a supported-frameworks page on the docs site. That means version compatibility is a moving target you must check outside the repository. The Dockerfile's ruby_version default of 3.1 is a development convenience, not a compatibility statement, and reading it as one would be a mistake.

A third is the failure mode the README itself anticipates. There is a troubleshooting guide whose title is about no data appearing, and New Relic offers NRDiag, a client-side diagnostic utility that detects common agent problems and can attach troubleshooting data to a support ticket. The existence of both, described in the README, tells you the common first experience is a silent agent rather than a loud error.

## Alternatives and the real difference in approach

The honest alternative for a Ruby team that wants traces without a commercial backend is OpenTelemetry's Ruby instrumentation, paired with whatever collector and storage you run. The difference is architectural, not cosmetic. newrelic-ruby-agent is built to talk to one vendor's collector and configuration model, with a newrelic.yml and a licence key; OpenTelemetry's Ruby libraries emit spans to an exporter you choose and configure. With the New Relic agent you get framework-specific instrumentation maintained by the vendor and a support path. With OpenTelemetry you get backend choice and pay for it in wiring: sampling, exporter configuration and a storage backend are all yours.

A narrower alternative is a profiler that stays inside the process, useful when the question is "which method is slow" rather than "which request is slow in production across services". The New Relic agent answers the second question; it is not a replacement for a local profiler during development. Choose based on whether the vendor backend is already a given.

## Maintenance, releases and what the licence does and does not cover

The repository is not archived, and the last push was on 2026-09-10. The release line is active: 10.7.1 was released on 2026-08-20, preceded by 10.7.1-pre on 2026-08-19 and 10.7.0 on 2026-08-06. The README states the code is maintained by New Relic engineering teams. For an agent that must track Ruby and framework releases, that cadence is the relevant signal, not any repository counter.

Upgrade cost is real but bounded. Because the agent hooks into frameworks and libraries, a major Ruby or Rails upgrade can require an agent upgrade in the same change window, and the docs site maintains a separate update page. Pinning a version in your Gemfile and reading the CHANGELOG.md before bumping is the low-drama path; the repository keeps that file at the top level.

The licence is Apache-2.0, which covers the source in this repository. It does not grant you the New Relic service. Using the agent to send data to New Relic's collector is governed by New Relic's own terms and privacy notice, both linked from the README, and support is described as 24/7/365 ticketed support under a separate support plan. Read those documents rather than assuming the open source licence covers the backend relationship.

Contributions go through a Contributor License Agreement signed once per project via CLA-Assistant, with a corporate CLA available by email. That is a governance detail worth knowing before you plan to patch the agent for your own environment.

## Conclusion

Adopt newrelic-ruby-agent if you already run New Relic APM and need Ruby coverage across Rails, Rack and background workers, since the gem is the supported path to that backend and the repository shows a maintained release line. Do not adopt it if you need a self-hosted or backend-neutral APM, because the agent's value depends on New Relic's collector and the README documents no export to another backend. Before rolling it out, verify the current supported Ruby and framework list on the docs site the README links, and confirm the agent version you pin against the 10.7.x release notes.

## FAQ

### What is the newrelic_rpm gem used for?

It is the New Relic Ruby agent, which monitors Ruby applications to help identify and solve performance issues and can also collect business data for analysis. It is dual-purposed as a Gem or a Rails plugin.

### How do I install the newrelic_rpm gem with Bundler?

Add gem 'newrelic_rpm' to your project's Gemfile and run bundle install. Without Bundler, the README gives gem install newrelic_rpm instead.

### How do I start the New Relic Ruby agent in a non-framework app?

The README says to add NewRelic::Agent.manual_start to your Ruby start-up sequence for frameworks and non-framework environments where the agent does not start on its own.

### Does the newrelic-ruby-agent repository include a production runtime?

No. The Dockerfile is a development image that copies the tree, runs bundle install and defaults its CMD to bundle exec rake, and the docker-compose.yml services such as Elasticsearch, MySQL and RabbitMQ are test fixtures.

## Sources

- [License: Apache-2.0](https://github.com/newrelic/newrelic-ruby-agent/blob/dev/LICENSE)
- [newrelic/newrelic-ruby-agent on GitHub](https://github.com/newrelic/newrelic-ruby-agent)
- [Project website](https://docs.newrelic.com/docs/apm/agents/ruby-agent/getting-started/introduction-new-relic-ruby/)
- [README](https://github.com/newrelic/newrelic-ruby-agent/blob/dev/README.md)
- [Releases](https://github.com/newrelic/newrelic-ruby-agent/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/newrelic-newrelic-ruby-agent