stoplight-statsd 0.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 10b6fa4537afd4535b2f688c867e9696ca0e1e533493ce4eefdbb83ae693bee4
+  data.tar.gz: 62f42990dc70ce1b679bf4b8626d0225463277cbc67dd8f4a2dcc7502081fe21
+SHA512:
+  metadata.gz: 4377451407e84fc48d17e5c9245871fc55cbbf1ea2f697aa7e3e6693bb7c4cac6b4a17afd1e68cc3c565aec5aca1bc339e90ce87ebeca42be0924360483472e9
+  data.tar.gz: 584de22665a30ee2076d71a184e684294eceaedbcbc0d85fc08a57fb568e2a04ff2dc31abf78177c4589a2d564ce0082426f139a6ce405c5d8ef288f5abf42da

data/README.md

@@ -0,0 +1,95 @@
+# 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
+
+```bash
+bundle add stoplight-statsd
+```
+
+## Usage
+
+Call `Stoplight::Statsd.subscribe` once, wherever you set up Stoplight, and pass it a DogStatsD
+client:
+
+```ruby
+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](#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:
+
+```ruby
+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`.
+
+```ruby
+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](https://opensource.org/licenses/MIT).
+
+
+[DogStatsD]: https://docs.datadoghq.com/developers/dogstatsd/
+[Stoplight]: https://github.com/bolshakov/stoplight

data/lib/stoplight/statsd/subscription_group.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Statsd
+    # Aggregates multiple bus subscriptions behind one caller-facing handle.
+    class SubscriptionGroup
+      def initialize(telemetry:, subscriptions:)
+        @telemetry = telemetry
+        @subscriptions = subscriptions
+      end
+
+      def unsubscribe
+        @subscriptions.each { |subscription| @telemetry.unsubscribe(subscription) }
+        nil
+      end
+    end
+  end
+end

data/lib/stoplight/statsd/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Statsd
+    VERSION = "0.0.0"
+  end
+end

data/lib/stoplight/statsd.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+require "stoplight"
+require "zeitwerk"
+
+# steep:ignore:start
+loader = Zeitwerk::Loader.for_gem_extension(Stoplight)
+loader.setup
+# steep:ignore:end
+
+module Stoplight
+  module Statsd
+    class Error < StandardError; end
+
+    def self.subscribe(telemetry, statsd:, sample_rate: 1.0)
+      unless (0.0..1.0).cover?(sample_rate)
+        raise Error, "sample_rate must be between 0.0 and 1.0, got #{sample_rate.inspect}"
+      end
+
+      subscriptions = [subscribe_run_completed(telemetry, statsd: statsd, sample_rate:),
+        subscribe_recovery_probe_completed(telemetry, statsd: statsd),
+        subscribe_state_transitioned(telemetry, statsd: statsd), subscribe_light_registered(telemetry, statsd: statsd)]
+      SubscriptionGroup.new(telemetry:, subscriptions:)
+    end
+
+    def self.envelope_tags(envelope)
+      ["system_name:#{envelope.system_name}", "light_name:#{envelope.light_name}"]
+    end
+
+    def self.subscribe_run_completed(telemetry, statsd:, sample_rate:)
+      telemetry.subscribe(Stoplight::Telemetry::RunCompleted) do |envelope|
+        record_run_completed(envelope, statsd: statsd, sample_rate: sample_rate)
+      end
+    end
+
+    def self.record_run_completed(envelope, statsd:, sample_rate:)
+      identity_tags = envelope_tags(envelope)
+      outcome_tag = "outcome:#{envelope.payload.outcome}"
+
+      statsd.increment("stoplight.run.completed", tags: [
+        *identity_tags, outcome_tag,
+        "color:#{envelope.payload.color}",
+        "fallback_used:#{envelope.payload.fallback_used}"
+      ], sample_rate:)
+      return unless envelope.payload.duration_ms
+
+      statsd.histogram("stoplight.run.duration", envelope.payload.duration_ms,
+        tags: [*identity_tags, outcome_tag], sample_rate:)
+    end
+
+    def self.subscribe_recovery_probe_completed(telemetry, statsd:)
+      telemetry.subscribe(Stoplight::Telemetry::RecoveryProbeCompleted) do |envelope|
+        identity_tags = envelope_tags(envelope)
+        outcome_tag = "outcome:#{envelope.payload.outcome}"
+
+        statsd.increment("stoplight.recovery_probe.completed", tags: [*identity_tags, outcome_tag], sample_rate: 1.0)
+        statsd.histogram("stoplight.recovery_probe.duration", envelope.payload.duration_ms,
+          tags: [*identity_tags, outcome_tag], sample_rate: 1.0)
+      end
+    end
+
+    # The event's text is always the color transition, never the failure's exception message - that
+    # message is the host application's own text, written for its own logs, and can carry data (a
+    # failed URL, a DB value, echoed user input) never meant to leave the process to a third-party
+    # service. state_transitioned_variant_tags already exposes the bounded, developer-controlled
+    # exception_class as a tag, which is safe to export.
+    def self.subscribe_state_transitioned(telemetry, statsd:)
+      telemetry.subscribe(Stoplight::Telemetry::StateTransitioned) do |envelope|
+        record_state_transitioned(envelope, statsd: statsd)
+      end
+    end
+
+    def self.record_state_transitioned(envelope, statsd:)
+      payload = envelope.payload
+      event_name = state_transitioned_event_name(payload)
+      tags = state_transitioned_tags(envelope, payload, event_name)
+
+      statsd.increment("stoplight.state.transitioned", tags: tags, sample_rate: 1.0)
+      statsd.event("#{envelope.system_name}/#{envelope.light_name}: #{event_name}",
+        "#{payload.from_color} -> #{payload.to_color}", alert_type: state_transitioned_alert_type(payload),
+        tags: tags, truncate_if_too_long: true)
+    end
+
+    def self.state_transitioned_tags(envelope, payload, event_name)
+      [
+        *envelope_tags(envelope),
+        "event:#{event_name}",
+        "from_color:#{payload.from_color}",
+        "to_color:#{payload.to_color}"
+      ] + state_transitioned_variant_tags(payload)
+    end
+
+    def self.state_transitioned_event_name(payload)
+      case payload
+      when Stoplight::Telemetry::TrafficBreached then "traffic_breached"
+      when Stoplight::Telemetry::RecoveryStarted then "recovery_started"
+      when Stoplight::Telemetry::RecoverySucceeded then "recovery_succeeded"
+      when Stoplight::Telemetry::RecoveryFailed then "recovery_failed"
+      when Stoplight::Telemetry::LockChanged then "lock_changed"
+      else raise Error, "unhandled state_transitioned payload: #{payload.class}"
+      end
+    end
+
+    def self.state_transitioned_alert_type(payload)
+      case payload
+      when Stoplight::Telemetry::TrafficBreached, Stoplight::Telemetry::RecoveryFailed then "error"
+      when Stoplight::Telemetry::RecoverySucceeded then "success"
+      when Stoplight::Telemetry::RecoveryStarted, Stoplight::Telemetry::LockChanged then "info"
+      else raise Error, "unhandled state_transitioned payload: #{payload.class}"
+      end
+    end
+
+    # Tags beyond system_name/light_name/event/from_color/to_color, which every variant carries.
+    def self.state_transitioned_variant_tags(payload)
+      case payload
+      when Stoplight::Telemetry::TrafficBreached, Stoplight::Telemetry::RecoveryFailed
+        ["policy:#{payload.policy}"] + state_transitioned_failure_tags(payload.failure)
+      when Stoplight::Telemetry::RecoverySucceeded then ["policy:#{payload.policy}"]
+      when Stoplight::Telemetry::LockChanged then ["from_state:#{payload.from_state}", "to_state:#{payload.to_state}"]
+      when Stoplight::Telemetry::RecoveryStarted then []
+      end
+    end
+
+    def self.state_transitioned_failure_tags(failure)
+      failure ? ["tracked:#{failure.tracked}", "exception_class:#{failure.exception.class}"] : []
+    end
+
+    def self.subscribe_light_registered(telemetry, statsd:)
+      telemetry.subscribe(Stoplight::Telemetry::LightRegistered) do |envelope|
+        statsd.increment("stoplight.light.registered", tags: envelope_tags(envelope), sample_rate: 1.0)
+      end
+    end
+
+    private_class_method :subscribe_run_completed, :record_run_completed, :subscribe_recovery_probe_completed,
+      :subscribe_state_transitioned, :record_state_transitioned, :state_transitioned_tags,
+      :state_transitioned_event_name, :state_transitioned_alert_type, :state_transitioned_variant_tags,
+      :state_transitioned_failure_tags, :subscribe_light_registered
+  end
+end

data/sig/stoplight/statsd.rbs

@@ -0,0 +1,31 @@
+module Stoplight
+  module Statsd
+    VERSION: String
+
+    class Error < StandardError
+    end
+
+    class SubscriptionGroup
+      @telemetry: Stoplight::Domain::_Telemetry
+      @subscriptions: Array[Stoplight::Domain::Telemetry::Subscription]
+
+      def initialize: (telemetry: Stoplight::Domain::_Telemetry, subscriptions: Array[Stoplight::Domain::Telemetry::Subscription]) -> void
+      def unsubscribe: () -> void
+    end
+
+    def self.subscribe: (Stoplight::Domain::_Telemetry, statsd: Datadog::Statsd, ?sample_rate: Float) -> SubscriptionGroup
+
+    private def self.envelope_tags: [P < Stoplight::Domain::Telemetry::event] (Stoplight::Domain::Telemetry::Envelope[P]) -> Array[String]
+    private def self.subscribe_run_completed: (Stoplight::Domain::_Telemetry, statsd: Datadog::Statsd, sample_rate: Float) -> Stoplight::Domain::Telemetry::Subscription
+    private def self.record_run_completed: (Stoplight::Domain::Telemetry::Envelope[Stoplight::Domain::Telemetry::RunCompleted], statsd: Datadog::Statsd, sample_rate: Float) -> void
+    private def self.subscribe_recovery_probe_completed: (Stoplight::Domain::_Telemetry, statsd: Datadog::Statsd) -> Stoplight::Domain::Telemetry::Subscription
+    private def self.subscribe_state_transitioned: (Stoplight::Domain::_Telemetry, statsd: Datadog::Statsd) -> Stoplight::Domain::Telemetry::Subscription
+    private def self.record_state_transitioned: (Stoplight::Domain::Telemetry::Envelope[Stoplight::Domain::Telemetry::state_transitioned], statsd: Datadog::Statsd) -> void
+    private def self.state_transitioned_tags: (Stoplight::Domain::Telemetry::Envelope[Stoplight::Domain::Telemetry::state_transitioned], Stoplight::Domain::Telemetry::state_transitioned, String) -> Array[String]
+    private def self.state_transitioned_event_name: (Stoplight::Domain::Telemetry::state_transitioned) -> String
+    private def self.state_transitioned_alert_type: (Stoplight::Domain::Telemetry::state_transitioned) -> String
+    private def self.state_transitioned_variant_tags: (Stoplight::Domain::Telemetry::state_transitioned) -> Array[String]
+    private def self.state_transitioned_failure_tags: (Stoplight::Domain::Telemetry::Failure?) -> Array[String]
+    private def self.subscribe_light_registered: (Stoplight::Domain::_Telemetry, statsd: Datadog::Statsd) -> Stoplight::Domain::Telemetry::Subscription
+  end
+end

metadata

@@ -0,0 +1,91 @@
+--- !ruby/object:Gem::Specification
+name: stoplight-statsd
+version: !ruby/object:Gem::Version
+  version: 0.0.0
+platform: ruby
+authors:
+- Tëma Bolshakov
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: dogstatsd-ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: stoplight
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Subscribes to Stoplight's telemetry bus and forwards circuit breaker
+  events as DogStatsD metrics to whatever StatsD/Datadog-compatible receiver you already
+  run.
+email:
+- tema@bolshakov.dev
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/stoplight/statsd.rb
+- lib/stoplight/statsd/subscription_group.rb
+- lib/stoplight/statsd/version.rb
+- sig/stoplight/statsd.rbs
+homepage: https://github.com/bolshakov/stoplight-statsd
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/bolshakov/stoplight-statsd
+  source_code_uri: https://github.com/bolshakov/stoplight-statsd
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: DogStatsD exporter for Stoplight's telemetry bus
+test_files: []