Ruby agent requirements and supported frameworks

Before you install New Relic's Ruby agent, make sure your system meets these requirements for compatible operating systems, security protocols, Ruby versions, and supported frameworks/libraries.

If you don't have one already, start by creating a New Relic account. It's free, forever.

Operating systems

The Ruby agent supports UNIX-like operating systems such as Linux, Solaris, FreeBSD, and macOS. Windows is not officially supported for production environments but may work for development.

Security requirements

Data Collection: As a standard security measure for data collection, your app server must support SHA-2 (256-bit) for SSL communication with New Relic. SHA-1 is not supported.
TLS: New Relic requires TLS 1.2 or higher for all inbound connections from the agent.

Ruby versions

The New Relic Ruby agent does not support experimental or non-official Ruby versions. The agent is continuously tested against official Ruby releases.

Ruby Implementation	Supported	Notes
CRuby (MRI)	3.4.x, 3.3.x, 3.2.x, 3.1.x, 3.0.x, 2.7.x, 2.6.x, 2.5.x, 2.4.x	Ruby 2.3.x, 2.2.x: Last fully supported by agent v8.16.0. Ruby 2.1.x, 2.0.x: Last fully supported by agent v6.15.0. Ruby 1.9.3: Last agent v3.18.1. Ruby 1.8.7: Last agent v3.18.1.
JRuby	9.x	JRuby 1.7.x: Last agent v3.18.1. Older versions are not supported.

Note: "Last fully supported by agent vX.Y.Z" means that agent version X.Y.Z was the last to guarantee support. Newer agents may still function but are not actively tested against those older Ruby versions.

Web servers

The Ruby agent supports the following web servers. Instrumentation typically hooks into Rack.

Web Server	Supported	Notes
Puma	6.x, 5.x, 4.x, 3.x	Versions < 3.x: Support may vary.
Unicorn	6.x, 5.x	Versions < 4.x: Support may vary.
Passenger	6.x, 5.x	Versions < 5.x: Support may vary.
Thin	1.x
Webrick	Bundled with supported Ruby versions	Generally supported for development and basic Rack apps.
Falcon	0.30.x and above

Web frameworks

The Ruby agent provides robust instrumentation for these web frameworks.

Framework	Supported	Notes
Rails	8.0.x, 7.1.x, 7.0.x, 6.1.x, 6.0.x, 5.2.x	Rails 5.1.x, 5.0.x, 4.2.x also extensively tested. Rails 3.2.x: Last fully supported by agent v8.16.0. Older versions (e.g., 2.x, 3.0.x, 3.1.x) are not supported by recent agents.
Sinatra	3.x, 2.x	Sinatra 1.4.x: Last fully supported by agent v8.16.0. Older versions are not supported.
Rack	5.x, 4.x, 3.x
Grape	1.7.x, 1.6.x, 1.5.x, 1.4.x, 1.3.x, 1.2.x	Grape 0.2.0: Last fully supported by agent v8.16.0. Older versions may not be fully supported.
Padrino	0.15.x	Older versions (e.g., 0.14.x) last fully supported by agent v8.16.0.
Roda	3.x

Datastores and ORMs

The agent instruments a wide variety of database drivers and Object-Relational Mappers.

Datastore / ORM	Gem Name	Supported	Notes
ActiveRecord	`activerecord`	See Rails versions	Standalone use also supported. Redshift adapter recognized.
Sequel	`sequel`	5.17.0 and above	Sequel 3.37.x, 4.0.x: Last fully supported by agent v8.16.0.
MongoDB	`mongo`	2.4.0 and above	Mongo 1.8.x - 2.3.x: Last fully supported by agent v8.16.0.
Redis	`redis`	5.x, 4.x, 3.x	`redis-client` (used by redis-rb 5+) is also instrumented.
Memcached (Dalli)	`dalli`	3.x, 2.7.x
Memcached (memcached gem)	`memcached`	1.8.x
Elasticsearch	`elasticsearch`	8.x, 7.x	`elasticsearch.capture_cluster_name` config option available.
OpenSearch	`opensearch-ruby`	3.x, 2.1.x	Experimental support, provides telemetry similar to Elasticsearch.
DynamoDB (AWS SDK)	`aws-sdk-dynamodb`	3.x

New Relic collects instance details for a variety of databases and database drivers. The ability to view specific instances and the types of database information in APM depends on your New Relic agent version.

We support the following adapters:

Database	Adapter Gem Name
PostgreSQL	`pg`
MySQL	`mysql2`, `trilogy`
SQLite	`sqlite3`

This is not a comprehensive list.

To request instance-level information from datastores currently not listed for your New Relic agent, get support at support.newrelic.com.

Background job and messaging systems

Instrumentation for popular background job processing and message queue libraries.

System / Library	Gem Name	Supported	Notes
Sidekiq	`sidekiq`	8.x, 7.x, 6.x, 5.x	Sidekiq 4.2.x: Last fully supported by agent v8.16.0. `sidekiq-delay_extensions` also supported.
Resque	`resque`	2.x, 1.27.x	Support for `FORK_PER_JOB`.
Delayed::Job	`delayed_job`	4.1.x	Active Record and Mongoid backends. Delayed_Job 2.0.x - 4.0.x: Last fully supported by agent v8.16.0.
ActiveJob	`activejob`	See Rails versions
Bunny (RabbitMQ)	`bunny`	2.x	Bunny 2.0.x - 2.6.x: Last fully supported by agent v8.16.0.
Kafka (ruby-kafka)	`ruby-kafka`	1.x
Kafka (rdkafka)	`rdkafka`	0.15.x+
Kinesis (AWS SDK)	`aws-sdk-kinesis`	3.x
Firehose (AWS SDK)	`aws-sdk-firehose`	3.x
SQS (AWS SDK)	`aws-sdk-sqs`	3.x
SolidQueue	`solid_queue`	See ActiveJob	Used with ActiveJob. `ThreadError: queue empty` ignored by default.

HTTP clients and networking

The agent instruments various HTTP client libraries for external service monitoring.

Library	Gem Name	Supported	Notes
Net::HTTP	(Ruby Standard Library)	Bundled with supported Ruby versions	Core HTTP client.
HTTPClient	`httpclient`	2.8.3 and above	HttpClient 2.2.0 - 2.8.0 (below current 2.8.x): Last fully supported by agent v8.16.0.
Typhoeus	`typhoeus`	1.4.x and above	Typhoeus 0.5.3 - 1.2.x: Last fully supported by agent v8.16.0. Hydra support.
Excon	`excon`	0.56.0, and above	Excon < 0.55.0: Last fully supported by agent v8.16.0.
Ethon	`ethon`	0.12.0 and above
Curb	`curb`	0.9.x and above
HTTPX	`httpx`	1.0.0 and above
HTTP.rb (http gem)	`http`	5.x, 4.x, 3.x, 2.x	HttpRb 0.9.9 - 2.2.1: Last fully supported by agent v8.16.0.
Faraday	`faraday`		Instrumentation works via instrumented adapters (e.g., Net::HTTP, Excon).
Async::HTTP	`async-http`	0.59.0 and above
gRPC	`grpc`	1.48.0 and above	For gRPC server and client instrumentation.

AI and Machine Learning libraries

New Relic is expanding its support for AI/ML libraries.

Library	Gem Name	Supported	Notes
OpenAI	`ruby-openai`	3.4.0 and above	Requires `ai_monitoring.enabled = true`. Captures calls to embedding and chat completion endpoints. Custom attributes can be added with `llm.` prefix.

Other libraries and technologies

Library	Gem Name	Supported	Notes
ActionCable	`actioncable`	See Rails versions
ActiveMerchant	`activemerchant`	1.65.0 and above	ActiveMerchant 1.25.0 - 1.64.x: Last fully supported by agent v8.16.0.
Capistrano	`capistrano`	2.15.5 and above
Concurrent Ruby	`concurrent-ruby`	1.1.5 and above
Fiber			Instrumentation of Ruby's Fiber class.
GraphQL	`graphql`		Instrumentation provided by GraphQL gem
Lambda (AWS SDK)	`aws-sdk-lambda`		See AWS Lambda Monitoring for more information.
Logger	`logger`		Support for APM log forwarding using Ruby's Logger library.
Logstasher	`logstasher`	1.x.x and above	Support for APM log forwarding.
Stripe	`stripe`	5.38.0 and above
Thread			Instrumentation of Ruby's Thread class.
View Component		2.53.x and above
Yajl-Ruby	`yajl-ruby`	1.2.1 and above

Notes on Supported versions

The agent may be compatible with a broader range of versions (older or newer) than explicitly listed. However, the listed versions receive the most rigorous testing.
For the most up-to-date information on newly supported versions or deprecations, always refer to the Ruby agent release notes.
If a library is not listed, it may still be instrumented if it relies on an underlying technology that is instrumented (e.g., a framework built on Rack, or an ORM using a standard database adapter). For critical unlisted libraries, you can explore custom instrumentation or submit a feature request.

If you have questions about specific versions or libraries not covered here, please visit our Explorers Hub community forum.

Other APM software

If your application uses other application performance monitoring (APM) software besides our agent, we can't guarantee that our agent will work correctly and we can't offer technical support. For more information, see Errors when using other monitoring software.

Connect the agent to other parts of New Relic

The Ruby agent integrates with other New Relic capabilities to give you end-to-end visibility.

Capability	Description
AI monitoring	You can collect AI data using the Ruby agent and the `ruby-openai` gem. This feature was introduced in Ruby agent version 9.8.0 and supports `ruby-openai` versions 3.4.0 and above.
Browser monitoring	The Ruby agent automatically injects the browser JavaScript agent when you enable auto-instrumentation. After enabling browser injection, you can view data in the APM Summary page and quickly switch between the APM and browser data for a particular app. For configuration options and manual instrumentation, see the browser and Ruby agent documentation.
Infrastructure monitoring	When you install the infrastructure and APM agents on the same host, they automatically detect one another. You can then view a list of hosts in the APM UI, and filter your hosts by APM app in the infrastructure UI. For more information, see APM data in the infrastructure UI.
Synthetic monitoring	Synthetic transaction traces connect requests from synthetic monitors to the underlying APM transaction.