Rack

To instrument Rack applications, AppSignal provides a Rack instrumentation middleware. If you use any of the supported Rack frameworks like Rails, Sinatra, Hanami, Grape, or Padrino, we recommend using those instrumentations instead.

Add the instrumentation middleware

Using an older AppSignal Ruby gem? Follow our legacy guide.

To integrate AppSignal in a Rack application, we first need to load, configure, and start AppSignal. Then, instrument the Rack app by adding our Rack EventMiddleware and InstrumentationMiddleware to the middleware stack. This documentation explains how to do this in your application’s config.ru file.

# config.ru
require "appsignal"                           # Load AppSignal

Appsignal.start                               # Start the AppSignal integration

# Add the Rack EventMiddleware first
use Appsignal::Rack::EventMiddleware
# Add the Rack InstrumentationMiddleware
use Appsignal::Rack::InstrumentationMiddleware

# Load your app with a require statement here, like
require_relative "app"

# Add other middleware here if needed

# Finally, run the app
use MyApp.run

Ensure the EventMiddleware and InstrumentationMiddleware are registered in the application middleware stack as early as possible. The earlier these middleware are registered, the more request runtime the middleware will instrument. If other middleware are registered beforehand, our middleware will not instrument these other middleware. After adding the EventMiddleware and InstrumentationMiddleware to your app’s middleware stack, the action needs to be set for each route in your app in AppSignal. Without an action name to group requests, the event middleware will not report request information. For more insights into the operation of your Rack application, we recommend adding additional instrumentation to the application’s endpoints.

The Rack event middleware

We recommend adding our Rack event middleware to all Rack applications. This middleware will ensure we track The AppSignal Rack event middleware has the following features:

Instrumentation of the request and recording a process_request.rack event.
Reporting Exceptions that occur in the app and middleware.
Tracking the response status code as the response_status tag on the trace.
Tracking the response status code as the response_status metric, with the namespace and status tags.

The Rack instrumentation middleware

We recommend that in addition to the Appsignal::Rack::EventMiddleware, the AppSignal::Rack::InstrumentationMiddleware is added to the app. This middleware supplements the event middleware’s instrumentation by adding tags for the request path and request method, as well as tracking response body handling and response body closing operations. The instrumentation middleware has the following features:

Instrumentation of the request and recording a process_request.rack event.
Reporting Exceptions that occur in the app.
Tracking the request path and request method as tags on the trace.
Instrumentation of the response body handling and recording a process_response_body.rack event for this operation.
Instrumentation of the response body closing and recording a close_response_body.rack event for this operation.

Using the legacy instrumentation middleware

The GenericInstrumentation middleware was deprecated in Ruby gem 3.10.0. Please use the new guide instead.

To integrate AppSignal in a Rack application, we first need to load, configure, and start AppSignal. Then, instrument the Rack app by adding our Rack GenericInstrumentation middleware to the middleware stack. This documentation explains how to do this in your application’s config.ru file.

# config.ru
# Load and configure AppSignal
require "appsignal"                           # Load AppSignal

Appsignal.config = Appsignal::Config.new(
  File.expand_path("../", __FILE__),          # Application root path
  ENV["RACK_ENV"],                            # Application environment
)
Appsignal.start                               # Start the AppSignal integration
Appsignal.start_logger                        # Start logger

# Load your app with a require statement here, like
require_relative "app"

# Add the GenericInstrumentation middleware
use Appsignal::Rack::GenericInstrumentation

# Add other middleware here if needed

# Finally, run the app
use MyApp.run

Setting the action name

Set an action name on the AppSignal transaction for a request so we can group endpoints in our issues and metrics. We recommend using a static action name per endpoint, like GET /blog, POST /users, PUT /users/:id, etc. To set an action name for a request, call the Appsignal.set_action helper from the app.

Do not use the request path of the route as the action name if the path has dynamic segments. Using real request paths for action names breaks our request grouping by creating unique issues for each possible request path.

# app.rb
require "rack"

# Example pure-Rack app
class MyApp
  def call(env)
    case [env["REQUEST_METHOD"], env["PATH_INFO"]]
    when ["GET", "/"]
      Appsignal.set_action("GET /") # Action name set here
      body = <<~BODY
        <h1>Rack example app</h1>

        <ul>
          <li><a href="/slow">Slow request</a></li>
          <li><a href="/error">Error request</a></li>
        </ul>
      BODY
      [200, {"Content-Type" => "text/html"}, [body]]
    when ["GET", "/slow"]
      Appsignal.set_action("GET /slow") # Action name set here
      sleep 1
      [200, {"Content-Type" => "text/plain"}, ["Slow response"]]
    when ["GET", "/error"]
      Appsignal.set_action("GET /error") # Action name set here
      raise "uh oh"
    else
      Appsignal.set_action("NotFound") # Action name set here
      [404, {"Content-Type" => "text/plain"}, ["Page not found"]]
    end
  end
end

Span attributes

Collector mode only: this applies when AppSignal for Ruby runs in collector mode. It has no effect otherwise.

The request’s span carries:

http.request.method — the request method.
url.scheme, url.path, and url.query — the address that was requested.
http.response.status_code — the status your application responded with.

A span for a request that raised also carries error.type, the class of the error.

Distributed tracing

Collector mode only: this applies when AppSignal for Ruby runs in collector mode. It has no effect otherwise.

A request that arrives with a traceparent request header continues the trace it names. The request appears inside the calling service’s trace, under the request that caused it. You can follow a slow request from that service into this application without switching traces. The HTTP clients AppSignal supports start the trace. A request without the header starts a new one.

SDKs & telemetry

Language SDKs

Telemetry tools

Add the instrumentation middleware

The Rack event middleware

The Rack instrumentation middleware

Using the legacy instrumentation middleware

Setting the action name

Span attributes

Distributed tracing

​Add the instrumentation middleware

​The Rack event middleware

​The Rack instrumentation middleware

​Using the legacy instrumentation middleware

​Setting the action name

​Span attributes

​Distributed tracing

Add the instrumentation middleware

The Rack event middleware

The Rack instrumentation middleware

Using the legacy instrumentation middleware

Setting the action name

Span attributes

Distributed tracing