yabeda-rack-queue

Rack middleware that measures HTTP request queue time. It reports the result to Yabeda as a histogram.

What is queue time?

A request may wait before your app handles it. A proxy or load balancer (like Nginx or Heroku) causes this wait. This is called queue time.

High queue time means your app is too busy. It cannot take new requests. That is a sign you need more capacity.

How it works

Load balancers can add a header to each request. The header records when the request arrived. Common headers are X-Request-Start and X-Queue-Start.

This middleware reads that header. It subtracts the header's timestamp from the current time. Then it reports that value as rack_queue.duration.

Installation

Add to your Gemfile:

gem "yabeda-rack-queue"

Then run:

bundle install

Usage

Add the middleware to your Rack stack. You also need a Yabeda adapter. For example, use yabeda-prometheus.

require "yabeda/rack/queue"
require "yabeda/prometheus"

Yabeda.configure!

use Yabeda::Rack::Queue::Middleware
run MyRackApp

For Rails, add it in config/application.rb:

config.middleware.use Yabeda::Rack::Queue::Middleware

Metric

Name	Group	Type	Unit
duration	rack_queue	histogram	seconds

Access it in code:

Yabeda.rack_queue.duration

With adapters that prepend the group name, such as Prometheus, this becomes rack_queue_duration_seconds.

Histogram buckets: 1 ms, 5 ms, 10 ms, 25 ms, 50 ms, 100 ms, 250 ms, 500 ms, 1 s, 2.5 s, 5 s, 10 s, 30 s, 60 s.

Header formats

The middleware checks X-Request-Start first. If that header is absent, it tries X-Queue-Start.

Supported timestamp formats:

Format	Example
Seconds (float)	1609459200.123
Milliseconds	1609459200123
Microseconds	1609459200123456
t= prefix	t=1609459200.123

The middleware auto-detects the unit. It checks if the number fits a valid recent time.

Puma adjustment

Puma sets puma.request_body_wait (in milliseconds) in the Rack env. This records how long Puma spent reading the request body.

The middleware subtracts this value from queue time. Without this step, large bodies make queue time appear too long.

Configuration

The middleware accepts these keyword arguments:

Argument	Default	Purpose
reporter:	YabedaReporter.new	Writes the value to Yabeda.
logger:	stderr	Gets warning messages.
clock:	Process.clock_gettime(CLOCK_REALTIME)	Returns current time in seconds.

Example with a custom logger:

use Yabeda::Rack::Queue::Middleware, logger: Rails.logger

Requirements

• Ruby >= 3.1.
• yabeda >= 0.14, < 1.0.
• A Yabeda adapter. For example: yabeda-prometheus.

Development

Run tests:

bundle exec rake test

Run the linter:

bundle exec standardrb

Contributing

Bug reports and pull requests are welcome at https://github.com/speedshop/yabeda-rack-queue.

License

MIT. See LICENSE.txt.