apidepth 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: fe52fa09e05f825f4300ebb638df967a43087c59bbd833eead51101ad784e092
+  data.tar.gz: 90b843525ebc7ee2e8124833593f6f13284baff8e20ba031a9df64abd6dd6867
+SHA512:
+  metadata.gz: a570c48989e019f50c32e5c8d56de9b88eac99035bea44fdf2fa9abfd7021a1e4d86141d2837fdbacbf91435110572394cf0efd10139af83faee51f6eaf301bc
+  data.tar.gz: afa912c7e24d9823d1eee500ba521981577df34e7a7dd3200b0d336d0e16a7674d8a26db5624ab2c8dd537c5ce45f92b8a1798a9fbb3e9b9e30013e01b9062ce

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Apidepth
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,267 @@
+# apidepth
+
+Passive outbound API latency monitoring for Rails. Captures real production latency to third-party APIs — Stripe, OpenAI, Twilio, and others — without synthetic probes, without payload capture, and without changes to your application code beyond a one-time initializer.
+
+---
+
+## How it works
+
+Most API monitoring tools run scheduled probes from their own servers and measure latency to a vendor endpoint. That tells you how fast the vendor responds to *them*, from *their* location, to a test request. It doesn't tell you what your users are experiencing.
+
+Apidepth instruments `Net::HTTP` directly. Every outbound HTTP call your application makes to a known vendor is timed at the socket level, tagged with outcome and environment metadata, and batched to the Apidepth collector in the background. No payloads are captured. No credentials touch our infrastructure. The latency measurement is from your server to the vendor — the number your users feel.
+
+The second differentiator is benchmarking. Because Apidepth aggregates anonymized timing data across all customers, your dashboard can show not just "your Stripe p95 is 420ms" but "the fleet median is 280ms — you may have a regional routing issue." That comparison is only possible with real traffic from real deployments, which is why no synthetic probe tool can offer it.
+
+---
+
+## Installation
+
+Add to your `Gemfile`:
+
+```ruby
+gem "apidepth"
+```
+
+Run:
+
+```
+bundle install
+```
+
+---
+
+## Quick start
+
+Create `config/initializers/apidepth.rb`:
+
+```ruby
+Apidepth.configure do |config|
+  config.api_key = ENV["APIDEPTH_API_KEY"]
+end
+```
+
+That's it. The Railtie wires the instrumentation automatically. No code changes elsewhere.
+
+Get your API key at [apidepth.io](https://apidepth.io).
+
+---
+
+## Configuration
+
+All options with their defaults:
+
+```ruby
+Apidepth.configure do |config|
+  # Required. Your account API key.
+  config.api_key = ENV["APIDEPTH_API_KEY"]
+
+  # Disable in test environments. Default: true.
+  config.enabled = !Rails.env.test?
+
+  # Fraction of events to capture. 1.0 = 100%, 0.1 = 10%.
+  # Use a lower value if your application makes thousands of vendor
+  # calls per minute and you want to reduce collector traffic.
+  # Default: 1.0
+  config.sample_rate = 1.0
+
+  # Hosts to exclude from instrumentation entirely.
+  # Useful for internal services or staging vendors you don't want measured.
+  # Default: []
+  config.ignored_hosts = ["api.internal.mycompany.com"]
+
+  # Override the environment tag on events. Defaults to Rails.env at boot.
+  # Only set this if you need something other than Rails.env — for example,
+  # if you want to distinguish "production-us" from "production-eu".
+  # Default: Rails.env (set automatically by the Railtie)
+  config.environment = "production-us"
+
+  # Called on every flush failure, in addition to the built-in warn log.
+  # Use this to route failures to your existing error tracker.
+  # Default: nil
+  config.on_flush_error = ->(error, context) {
+    Sentry.capture_exception(error, extra: context)
+  }
+
+  # How often (in seconds) background events are batched and sent.
+  # Lower values reduce per-flush event volume; higher values reduce
+  # collector traffic. Default: 20
+  config.flush_interval = 20
+
+  # Path for the local vendor registry cache. Must be an absolute path.
+  # The registry is fetched from Apidepth's servers and cached here so
+  # cold starts don't block on a network fetch.
+  # Default: "/tmp/apidepth_registry.json"
+  config.registry_cache_path = "/tmp/apidepth_registry.json"
+
+  # Custom vendors your app calls that aren't in the global registry.
+  # Key: vendor name (matches the vendor field in your dashboard).
+  # Value: the hostname the SDK should watch for.
+  # Tracking starts immediately at boot — no dashboard visit required.
+  # Mappings sync to your dashboard automatically on the next event flush.
+  # Default: {}
+  config.extra_vendors = {
+    "my-payments-api" => "api.payments.internal.com",
+    "fulfillment"     => "fulfillment.myco.io",
+  }
+end
+```
+
+---
+
+## What gets captured
+
+Every event contains:
+
+| Field | Description |
+|-------|-------------|
+| `vendor` | Vendor slug, e.g. `"stripe"`, `"openai"` |
+| `endpoint` | Normalized path, e.g. `"/v1/charges/:id"` |
+| `method` | HTTP verb: `"GET"`, `"POST"`, etc. |
+| `status` | HTTP status code, or `nil` on timeout |
+| `outcome` | `:success`, `:client_error`, `:server_error`, `:timeout`, `:unknown` |
+| `duration_ms` | Wall-clock time in milliseconds, including DNS and SSL on first connection |
+| `cold_start` | `true` if this request paid for SSL handshake; excluded from p95 calculations |
+| `env` | Environment tag from `config.environment` or `Rails.env` |
+| `ts` | Unix timestamp in milliseconds |
+
+### What is never captured
+
+- Request or response **bodies**
+- Request or response **headers** (including Authorization)
+- **Query string parameters**
+- Any credential, token, or secret your application uses to authenticate with a vendor
+- User identifiers or PII of any kind
+
+Path normalization strips resource IDs before the event leaves your server. `/v1/charges/ch_3Ox4Kz2e` becomes `/v1/charges/:id`. If a vendor's path contains something that looks like user data (an email address in a path segment, for example), it may not be normalized — review your vendor's URL structure if this is a concern.
+
+---
+
+## Supported vendors
+
+The bundled registry covers the following vendors out of the box. New vendors and endpoint patterns are pushed to all SDK installs via the remote registry without requiring a gem update.
+
+| Vendor | Host |
+|--------|------|
+| Stripe | `api.stripe.com` |
+| OpenAI | `api.openai.com` |
+| Anthropic | `api.anthropic.com` |
+| Twilio | `api.twilio.com` |
+| Resend | `api.resend.com` |
+| GitHub | `api.github.com` |
+
+Calls to hosts not in the registry are ignored by default. Use `config.extra_vendors` to track additional hosts — internal APIs, homegrown services, or vendors not yet in the global registry. Custom vendors use generic path normalization (UUID stripping, long numeric ID stripping) rather than vendor-specific patterns.
+
+To request a vendor be added to the global registry: [open an issue](https://github.com/apidepth/apidepth-ruby/issues).
+
+---
+
+## Rate limit header extraction (v0.2.0+)
+
+When a vendor response includes rate limit quota headers, the SDK automatically extracts them and attaches three fields to the event: `rl_remaining`, `rl_limit`, and `rl_reset_at`. The collector uses these to power the burn-down projection on the Rate Limits dashboard page.
+
+No configuration is needed. Header extraction is passive and adds no overhead when headers are absent — `RateLimitHeaders.extract` returns `nil` and the fields are omitted from the event.
+
+### Supported headers
+
+Headers are checked in priority order per field:
+
+| Field | Headers (checked in order) |
+|-------|---------------------------|
+| remaining | `x-ratelimit-remaining-requests`, `x-ratelimit-remaining`, `ratelimit-remaining` |
+| limit | `x-ratelimit-limit-requests`, `x-ratelimit-limit`, `ratelimit-limit` |
+| reset_at | `x-ratelimit-reset-requests`, `x-ratelimit-reset`, `ratelimit-reset`, `retry-after` |
+
+The `reset_at` value is normalised to epoch milliseconds regardless of vendor format:
+- **Unix timestamp** (`n ≥ 1 × 10⁹`) — GitHub, HubSpot, IETF draft
+- **Seconds from now** (small integer) — Stripe `Retry-After` on 429
+- **Duration string** (`"1s"`, `"20ms"`, `"1m30s"`) — OpenAI, Anthropic
+
+Vendors with no quota headers on 2xx responses (Twilio, Salesforce, Jira, Zendesk, Slack) still contribute to 429 frequency tracking — the collector counts `status = 429` events regardless of SDK version.
+
+---
+
+## Puma cluster mode
+
+The Railtie handles `after_fork` automatically on Rails 7.1+ via `ActiveSupport::ForkTracker`. If you're on Rails 6.x or 7.0, add one line to `config/puma.rb` to ensure each worker gets a clean collector instance:
+
+```ruby
+# config/puma.rb
+on_worker_boot { Apidepth::Collector.reset! }
+```
+
+To flush the master process queue before workers fork (recommended):
+
+```ruby
+# config/puma.rb
+before_fork { Apidepth::Collector.instance.flush! }
+on_worker_boot { Apidepth::Collector.reset! }
+```
+
+---
+
+## Debugging
+
+Check the collector's internal state from a Rails console:
+
+```ruby
+Apidepth::Collector.instance.stats
+# => {
+#      queue_size: 0,
+#      consecutive_failures: 0,
+#      total_dropped: 0,
+#      last_flush_at: 2026-05-11 14:32:07 UTC
+#    }
+```
+
+`last_flush_at` is only updated when events are actually delivered to the collector. If it's nil or stale, check your `api_key` and network connectivity.
+
+`total_dropped` counts events discarded due to backpressure (queue full). A non-zero value means your flush interval is too long for your traffic volume — lower `config.flush_interval` or raise `config.sample_rate` below 1.0.
+
+If flush errors are reaching `on_flush_error`, the error message includes the HTTP status code without echoing back credentials or response bodies.
+
+---
+
+## Compatibility
+
+| | Minimum |
+|-|---------|
+| Ruby | 2.7 |
+| Rails | 6.1 |
+| Rack | 2.2.12 |
+
+The gem uses `Module#prepend` to instrument `Net::HTTP`. Most HTTP clients in the Ruby ecosystem (`Faraday`, `HTTParty`, `RestClient`, `http.rb`) delegate to `Net::HTTP` internally and are instrumented automatically without additional configuration.
+
+If another gem in your stack uses `alias_method` to redefine `Net::HTTP#request` after the Apidepth initializer runs, instrumentation will be silently bypassed. Symptoms: events stop appearing in your dashboard. Fix: move `require "apidepth"` or the initializer to load last. Known affected gems: none currently identified.
+
+Fiber-based servers (Falcon, Async::HTTP): `Thread.current` locals used by Apidepth are not inherited by fibers. Instrumentation is skipped for requests running in a fiber context. Support is on the roadmap.
+
+---
+
+## Contributing
+
+```
+git clone https://github.com/apidepth/apidepth-ruby
+cd apidepth-ruby
+bundle install
+bundle exec rspec
+```
+
+The test suite requires no external services — all HTTP is stubbed via WebMock.
+
+For end-to-end verification against a live collector, use the integration test script:
+
+```bash
+COLLECTOR_URL=https://your-collector.railway.app \
+API_KEY=apd_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \
+ruby scripts/integration_test.rb
+```
+
+This exercises the full pipeline: `Net::HTTP` instrumentation → event capture → flush → collector ingest → query API verification. It requires a running collector and a valid API key. It is separate from the unit suite and does not run in CI.
+
+To add a vendor to the bundled registry, edit `BUNDLED_BASELINE` in `lib/apidepth/vendor_registry.rb` and add corresponding tests to `spec/apidepth/sdk_spec.rb`. Path normalization patterns should be ordered most-specific first.
+
+---
+
+## License
+
+MIT. See [LICENSE](LICENSE).

data/lib/apidepth/collector.rb

@@ -0,0 +1,305 @@
+# lib/apidepth/collector.rb
+
+require "net/http"
+require "json"
+require "uri"
+
+module Apidepth
+  class Collector
+    MAX_BATCH_SIZE    = 100
+    MAX_QUEUE_SIZE    = 5_000
+    FAILURE_THRESHOLD = 3
+    WATCHDOG_INTERVAL = 60
+
+    DEFAULT_URL = "https://collector.apidepth.io/v1/events".freeze
+
+    @instance_mutex = Mutex.new
+
+    def self.instance
+      @instance_mutex.synchronize { @instance ||= new }
+    end
+
+    # Tear down the existing Collector cleanly before clearing the singleton.
+    # Without teardown, every reset! leaks a flush thread and a watchdog thread.
+    # This matters in Puma cluster mode — on_worker_boot calls reset! per worker.
+    def self.reset!
+      @instance_mutex.synchronize do
+        @instance&.send(:teardown)
+        @instance = nil
+      end
+    end
+
+    attr_reader :consecutive_failures, :total_dropped, :last_flush_at
+
+    def initialize
+      @queue                = Queue.new
+      @stats_mutex          = Mutex.new
+      @send_mutex           = Mutex.new
+      @consecutive_failures = 0
+      @total_dropped        = 0
+      @last_flush_at        = nil
+      @http                 = nil
+      @cached_url           = nil
+
+      start_flush_thread
+      start_watchdog_thread
+    end
+
+    def record(event)
+      if @queue.size >= MAX_QUEUE_SIZE
+        @stats_mutex.synchronize { @total_dropped += 1 }
+        return
+      end
+      @queue.push(event)
+    end
+
+    def flush!
+      events = drain_queue
+      return if events.empty?
+
+      send_batch(events)
+
+      # Mirror safe_flush's stats update so last_flush_at reflects at_exit
+      # delivery, not just background flushes.
+      @stats_mutex.synchronize do
+        @consecutive_failures = 0
+        @last_flush_at        = Time.now
+      end
+    rescue StandardError => e
+      failures = @stats_mutex.synchronize { @consecutive_failures += 1 }
+
+      begin
+        Apidepth.configuration.on_flush_error&.call(e, {
+                                                      dropped_events: events&.size || 0,
+                                                      consecutive_failures: failures,
+                                                      total_dropped: @total_dropped
+                                                    })
+      rescue StandardError
+        nil
+      end
+
+      Apidepth.logger&.warn("[Apidepth] Final flush failed: #{e.class}: #{e.message}")
+    end
+
+    def stats
+      @stats_mutex.synchronize do
+        {
+          queue_size: @queue.size,
+          consecutive_failures: @consecutive_failures,
+          total_dropped: @total_dropped,
+          last_flush_at: @last_flush_at
+        }
+      end
+    end
+
+    PRIVATE_HOST_PATTERN = /
+      \Alocalhost\z          |
+      \A127\.                |
+      \A0\.0\.0\.0\z         |
+      \A169\.254\.           |
+      \A10\.                 |
+      \A172\.(1[6-9]|2\d|3[01])\. |
+      \A192\.168\.           |
+      \A\[?::1\]?\z          |
+      \A\[?fc                |
+      \A\[?fe80:
+    /xi.freeze
+
+    private
+
+    def start_flush_thread
+      @flush_thread = Thread.new do
+        loop do
+          sleep Apidepth.configuration.flush_interval
+          safe_flush
+        end
+      end
+      @flush_thread.abort_on_exception = false
+      @flush_thread.name = "apidepth-flush"
+    end
+
+    def start_watchdog_thread
+      @watchdog_thread = Thread.new do
+        loop do
+          sleep WATCHDOG_INTERVAL
+          next if @flush_thread&.alive?
+
+          Apidepth.logger&.warn(
+            "[Apidepth] Flush thread died unexpectedly — restarting. " \
+            "If this recurs, open an issue with your Ruby and Rails versions."
+          )
+          start_flush_thread
+        end
+      end
+      @watchdog_thread.abort_on_exception = false
+      @watchdog_thread.name = "apidepth-watchdog"
+    end
+
+    # Kill background threads and close the HTTP connection.
+    # Called by reset! before the singleton is cleared.
+    # Uses kill without join — threads are daemon-style and release their
+    # resources as soon as they die. No join needed to unblock reset!.
+    def teardown
+      [@flush_thread, @watchdog_thread].compact.each do |t|
+        t.kill
+      rescue StandardError
+        nil
+      end
+      close_http_connection
+    end
+
+    def safe_flush
+      events = drain_queue
+
+      # Nothing to send — skip entirely. Crucially, don't update last_flush_at:
+      # that timestamp signals "data was delivered", not "the loop ticked".
+      return if events.empty?
+
+      send_batch(events)
+
+      @stats_mutex.synchronize do
+        @consecutive_failures = 0
+        @last_flush_at        = Time.now
+      end
+    rescue StandardError => e
+      failures = @stats_mutex.synchronize { @consecutive_failures += 1 }
+
+      begin
+        Apidepth.configuration.on_flush_error&.call(e, {
+                                                      dropped_events: events&.size || 0,
+                                                      consecutive_failures: failures,
+                                                      total_dropped: @total_dropped
+                                                    })
+      rescue StandardError
+        nil
+      end
+
+      if failures >= FAILURE_THRESHOLD
+        Apidepth.logger&.warn(
+          "[Apidepth] Flush has failed #{failures} times consecutively. " \
+          "Events are being dropped. Check your API key and network connectivity. " \
+          "Last error: #{e.class}: #{e.message}"
+        )
+      end
+    end
+
+    def drain_queue
+      events = []
+      events << @queue.pop(true) while events.size < MAX_BATCH_SIZE
+      events
+    rescue ThreadError
+      events
+    end
+
+    # Memoized on first flush. Intentional: collector_url is a boot-time setting.
+    # Changing configuration.collector_url after the first flush has no effect.
+    def collector_url
+      @collector_url ||= begin
+        url = URI.parse(Apidepth.configuration.collector_url || DEFAULT_URL)
+        validate_collector_url!(url)
+        url
+      end
+    end
+
+    # Returns the persistent HTTP connection.
+    # Only ever called under @send_mutex — no concurrent access.
+    # Reconnects automatically when the connection has been closed or errored.
+    def http_connection
+      return @http if @http&.started?
+
+      url = collector_url
+      @http = Net::HTTP.new(url.host, url.port)
+      @http.use_ssl            = true
+      @http.verify_mode        = OpenSSL::SSL::VERIFY_PEER
+      @http.open_timeout       = 3
+      @http.read_timeout       = 5
+      @http.keep_alive_timeout = 30
+      @http.start
+      @http
+    rescue StandardError
+      close_http_connection
+      raise
+    end
+
+    def close_http_connection
+      begin
+        @http&.finish
+      rescue StandardError
+        nil
+      end
+      @http = nil
+    end
+
+    def send_batch(events)
+      return if events.empty?
+
+      key = Apidepth.configuration.api_key
+      # Nil or empty key: Railtie already warned at boot — skip silently rather
+      # than sending a broken "Bearer " header and burning a failure increment.
+      return if key.nil? || key.empty?
+
+      validate_api_key!(key)
+
+      extra = Apidepth.configuration.extra_vendors
+      payload = {
+        batch: events,
+        sdk: Apidepth.sdk_metadata,
+        extra_vendors: extra.nil? || extra.empty? ? nil : extra
+      }.compact
+
+      Thread.current[:apidepth_skip] = true
+
+      @send_mutex.synchronize do
+        url  = collector_url
+        http = http_connection
+
+        req                  = Net::HTTP::Post.new(url.path.empty? ? "/" : url.path)
+        req["Content-Type"]  = "application/json"
+        req["Authorization"] = "Bearer #{key}"
+        req.body             = JSON.generate(payload)
+
+        response = http.request(req)
+
+        unless (200..299).cover?(response.code.to_i)
+          close_http_connection # server closed the connection or rejected us
+          raise "Collector returned HTTP #{response.code} — verify your api_key and collector_url"
+        end
+      end
+    ensure
+      Thread.current[:apidepth_skip] = false
+    end
+
+    def validate_collector_url!(url)
+      unless url.scheme == "https"
+        raise ArgumentError,
+              "Apidepth collector_url must use HTTPS (got #{url.scheme.inspect}). " \
+              "HTTP connections are rejected to prevent SSRF and credential exposure."
+      end
+
+      host = url.host.to_s.downcase
+
+      if host.match?(/\A\d+\z/)
+        int = host.to_i
+        if int.positive? && int <= 0xFFFFFFFF
+          host = [int >> 24, (int >> 16) & 0xFF, (int >> 8) & 0xFF,
+                  int & 0xFF].join(".")
+        end
+      end
+
+      return unless host.empty? || PRIVATE_HOST_PATTERN.match?(host)
+
+      raise ArgumentError,
+            "Apidepth collector_url must not target private, loopback, or link-local " \
+            "addresses (got #{url.host.inspect})."
+    end
+
+    def validate_api_key!(key)
+      return if key.nil? || key.empty?
+      return unless key.match?(/[\r\n]/)
+
+      raise ArgumentError,
+            "Apidepth api_key contains illegal line-break characters. " \
+            "This may indicate header injection — check your APIDEPTH_API_KEY value."
+    end
+  end
+end

data/lib/apidepth/configuration.rb

@@ -0,0 +1,30 @@
+# lib/apidepth/configuration.rb
+
+module Apidepth
+  class Configuration
+    attr_accessor :api_key,
+                  :collector_url,
+                  :enabled,
+                  :flush_interval,
+                  :registry_refresh_interval,
+                  :registry_cache_path,
+                  :ignored_hosts,
+                  :on_flush_error,
+                  :environment,      # e.g. "production" — set by Railtie from Rails.env
+                  :sample_rate,      # Float 0.0–1.0, default 1.0 (100% of events captured)
+                  :extra_vendors     # Hash of vendor_name => host, e.g. { "my-api" => "api.myservice.com" }
+
+    def initialize
+      @enabled                   = true
+      @flush_interval            = 20
+      @registry_refresh_interval = 6 * 60 * 60
+      @registry_cache_path       = "/tmp/apidepth_registry.json"
+      @collector_url             = nil
+      @ignored_hosts             = []
+      @on_flush_error            = nil
+      @environment               = nil   # Railtie sets this to Rails.env at boot
+      @sample_rate               = 1.0   # capture everything by default
+      @extra_vendors             = {}    # customer-defined host mappings
+    end
+  end
+end

data/lib/apidepth/event.rb

@@ -0,0 +1,36 @@
+# lib/apidepth/event.rb
+#
+# Lightweight schema for events queued to the Collector.
+#
+# WHY validate here rather than at the collector?
+# An event missing duration_ms or vendor is garbage. If we let it reach
+# the collector, the collector ingests it, it pollutes the time-series,
+# and you find out when a customer asks why their p95 chart is broken.
+# Failing loudly at Event.build time means the bug surfaces in tests
+# and development, not in production data.
+#
+# WHY frozen hash rather than a Struct?
+# JSON.generate works directly on a Hash. A Struct requires #to_h before
+# serialization, adding a conversion step on every batch. The frozen hash
+# gives us immutability guarantees without the overhead.
+
+module Apidepth
+  module Event
+    # Fields that must be present on every event regardless of outcome.
+    # error_class is optional (only present on :timeout events).
+    REQUIRED = %i[vendor endpoint method outcome duration_ms ts].freeze
+
+    # Build a validated, frozen event hash. Raises ArgumentError immediately
+    # if any required field is missing so the bug surfaces at call site.
+    def self.build(attrs)
+      missing = REQUIRED - attrs.keys
+      unless missing.empty?
+        raise ArgumentError,
+              "Apidepth event is missing required fields: #{missing.join(', ')}. " \
+              "This is a bug in the SDK — please open an issue."
+      end
+
+      attrs.freeze
+    end
+  end
+end