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.

🚧 Status: under development, not yet released. Nothing in this README is installable yet.

Installation

bundle add stoplight-statsd

Usage

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

Sampling busy traffic

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)

Events

"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.

Development

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.

Contributing

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

License

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