Stoplight::Statsd

A DogStatsD exporter for Stoplight's telemetry bus.

Stoplight is a Ruby circuit breaker: you wrap a risky call (a flaky API, a slow database) in a "light", and once it fails too often, the light turns red and stops making the call for a while, giving the dependency time to recover. Stoplight already emits detailed telemetry about what its lights are doing internally - this gem listens to that telemetry and forwards it to DogStatsD, so those events show up as metrics and events in Datadog (or any other StatsD-compatible receiver) without you having to wire that up yourself.

bundle add stoplight-statsd

Call Stoplight::Statsd.subscribe once, wherever you set up Stoplight, and pass it a DogStatsD client:

require "datadog/statsd"
require "stoplight/statsd"

statsd = Datadog::Statsd.new("localhost", 8125)
Stoplight::Statsd.subscribe(Stoplight.telemetry, statsd:)

That's it - from then on, every light reports its runs, recovery attempts, and state changes to statsd automatically. See Events below for the full list of what gets sent.

subscribe returns a handle you can use to stop forwarding later, e.g. when tearing down in tests:

subscription = Stoplight::Statsd.subscribe(Stoplight.telemetry, statsd:)
subscription.unsubscribe

Light#run fires on every call made through a light, so on a busy fleet it can dominate metric volume. Pass sample_rate: (0.0-1.0, default 1.0) to forward only a fraction of stoplight.run.completed/stoplight.run.duration - the only two metrics whose volume scales with traffic (each sampled independently, so a 0.1 rate isn't guaranteed to keep the same runs in both series, just the same average share). Everything else stays low-volume on its own, so it always sends at full rate regardless of sample_rate.

Stoplight::Statsd.subscribe(Stoplight.telemetry, statsd:, sample_rate: 0.1)

"Count" metrics are plain counters; "histogram" metrics record a distribution of values (here, milliseconds) so you can graph percentiles instead of just an average.

• stoplight.run.completed (count) - every call made through a light, tagged with the outcome (success/failure/blocked). Respects sample_rate.
• stoplight.run.duration (histogram, ms) - how long that call took, when known. Respects sample_rate.
• stoplight.recovery_probe.completed (count) - every recovery probe, i.e. the trial call Stoplight makes while a light is yellow to decide whether it can go back to green. Always sent at full rate.
• stoplight.recovery_probe.duration (histogram, ms) - how long that probe took, when known. Always sent at full rate.
• stoplight.state.transitioned (count, plus a matching Datadog event) - a light trips to red, a recovery attempt starts, succeeds, or fails, or a light gets locked/unlocked. Always sent at full rate.
• stoplight.light.registered (count) - a light is registered for the first time. Always sent at full rate.

After checking out the repo, run bin/setup to install dependencies. Then run rake spec to run the tests. bin/console gives you an interactive prompt.

To install this gem onto your local machine, run bundle exec rake install.

Bug reports and pull requests are welcome on GitHub at https://github.com/bolshakov/stoplight-statsd.

The gem is available as open source under the terms of the MIT License.