The Ruby agent automatically instruments Rack middlewares beginning with Ruby agent version 3.9.0. If you are unfamiliar with the basics of Rack middlewares, review the resources linked by the Rails on Rack guide. Additionally, the Ruby agent provides some features via Rack middlewares:
- Cross application traces
- Auto-instrumentation for page load timing (sometimes referred to as real user monitoring or RUM)
New Relic automatically installs these middlewares for Rails (Ruby agent versions 3.0.0 or higher) and Sinatra (Ruby agent versions 3.6.3 or higher).
The two most common ways to configure Rack middlewares are the
Rack::Builder API (most often from config.ru) and Rails' middleware stack configuration:
Middlewares in your config.ru file are configured using
Rack::Builder. For the Ruby agent to instrument middlewares from
Rack::Builder, your app must run version 1.1.0 or higher of the
rackgem. This is the most common use of middlewares with Sinatra or pure-rack applications.
- Rails middlewares
Rails uses its own class (
ActionDispatch::MiddlewareStack) instead of
Rack::Builderto configure middlewares. Even if you haven't explicitly added middlewares to your Rails application, many components of Rails itself are implemented as middleware, so middleware data will appear by default.
The Ruby agent automatically instruments middlewares added via
ActionDispatch::MiddlewareStackon Rails 3.0 or higher. For more information about configuring middlewares with Rails, see the Ruby on Rails guide.
Upgrading to Ruby agent 3.9.0
Applications using versions of the Ruby agent prior to 3.9.0 may see some changes as a result of upgrading. For more information, see Middleware changes in 3.9.0.
Viewing middleware data
You can view middleware data in New Relic APM.
- In the APM Overview page
As of Ruby agent version 3.9.0 or higher, the main chart on your app's New Relic APM Overview page includes a purple bar that shows average time per request spent in all Rack middlewares for your application.
- In the APM Transactions page
You can also see time for individual middlewares for a specific transaction name from your app's APM Transactions page.
- In APM transaction trace details
Transaction traces also capture detailed middleware call information.
Manual Rack instrumentation
Earlier versions of the Ruby agent supported manually instrumenting Rack middlewares via the
NewRelic::Agent::Instrumentation::Rack module. This instrumentation is deprecated in Ruby agent versions 3.9.0 or higher, because it is unnecessary with automatic middleware instrumentation. New Relic recommends that you remove references to this module from your code after upgrading to 3.9.0 or higher.
Disabling Rack instrumentation
Installing Ruby agent middlewares manually
The Ruby agent's implementation of New Relic's Cross Application Tracing feature uses Rack middleware instrumentation to read and write HTTP headers that are necessary to pass information between monitored applications. If you have disabled middleware instrumentation as described above and want to use cross application tracing, you must manually add the
NewRelic::Rack::AgentHooks middleware to your middleware stack. For more information, see Cross application tracing in Ruby.
For more help
Additional documentation resources include Middleware changes in 3.9.0 (changes you may see after upgrading).