apidepth 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ee27b15f831798b976f293eda67c90c9cccab735e75cb82a225d3ea511331622
-  data.tar.gz: 2ed0a290e8acab029c51eb12a116d295f8dfaa1390eef934cb61e5f9344b63ce
+  metadata.gz: d59e0f9e95678afd4a0f9ce173de1b63ac893ab01cbc68fc1d6bbcedc44bfaad
+  data.tar.gz: 29524e4a1687cafb241caa6c07dbb2c1139ef2e44bc92f8ded25dc15c1305a92
 SHA512:
-  metadata.gz: b32de3265dc5a4add529dd10741d21aa935ba18fccf669614fb74b9b06ed5d8125200d0ec26be7cf0c9349b8f6cc9a56d173ed4b2ba89acd551b5684bd411aa8
-  data.tar.gz: bf7106cbfdf0a003824b625680a047978f1f8a27c862ce8df52551f316405e47dbd4444e3e64361f35cedf6317f74575a9998ed766afdbdd6459d56a5a719404
+  metadata.gz: a4a88ac5df80e6af2987cfa29d354c67c5275c02e30caacbae086558d2a0ee1fe1304a42c11b679b2ec6a1358a1cd0e69c3969a5d9d400c246723592df448599
+  data.tar.gz: 2005a0c7164ed0b20da0e1013cdc250be7d09f66fdfdd65f465168f38f4a105bfa6370e3a98bef015502f7cb2ba961a99189a6232e0098eb47ca11c588d90ed4

data/README.md

@@ -40,7 +40,7 @@ bundle install
 
 ---
 
-## Quick start
+## Getting started
 
 Create `config/initializers/apidepth.rb`:
 
@@ -56,6 +56,46 @@ Get your API key at [apidepth.io](https://apidepth.io).
 
 ---
 
+## CLI
+
+The gem ships two subcommands for setup and connectivity verification.
+
+### `bundle exec apidepth setup`
+
+Interactive wizard that detects your framework (Rails, Sinatra, or generic), generates the correct initializer snippet, and optionally writes it to disk.
+
+```bash
+bundle exec apidepth setup
+```
+
+For CI/CD pipelines, skip all prompts:
+
+```bash
+bundle exec apidepth setup --api-key $APIDEPTH_API_KEY --no-prompt
+```
+
+| Flag | Description |
+|---|---|
+| `--api-key <key>` | Inject your API key into the generated snippet. |
+| `--no-prompt` | Non-interactive mode — print snippet to stdout and exit. |
+| `--framework <name>` | Override auto-detection (`rails`, `sinatra`, `generic`). |
+| `--ignored-hosts <patterns>` | Comma-separated host patterns to add to `ignored_hosts` (glob wildcards supported). |
+| `--collector-url <url>` | Override the collector URL in the generated snippet. |
+
+### `bundle exec apidepth test`
+
+Sends a synthetic test event to the collector and confirms the pipeline is working end-to-end. Reads `APIDEPTH_API_KEY` (and optionally `APIDEPTH_COLLECTOR_URL`) from the environment. Prints the round-trip time on success, or a per-failure-mode error message with next steps on failure.
+
+```bash
+bundle exec apidepth test
+# ✓ received in 142ms
+# Visit your dashboard: https://apidepth.io/dashboard
+```
+
+Exits with code 1 on any error (bad key, unreachable, SSL failure, timeout).
+
+---
+
 ## Configuration
 
 All options with their defaults:
@@ -100,7 +140,8 @@ Apidepth.configure do |config|
   # 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"
+  # Rails default: Rails.root.join("tmp/apidepth_registry.json") (set by the Railtie)
+  # Non-Rails 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.
@@ -133,6 +174,9 @@ Every event contains:
 | `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 |
+| `rl_remaining` | Remaining quota, e.g. `4999` — present when vendor rate limit headers are found |
+| `rl_limit` | Total quota, e.g. `5000` — present when vendor rate limit headers are found |
+| `rl_reset_at` | Quota reset time in epoch milliseconds — present when vendor rate limit headers are found |
 
 ### What is never captured
 

data/bin/apidepth

@@ -0,0 +1,31 @@
+#!/usr/bin/env ruby
+# bin/apidepth — CLI entry point for the Apidepth Ruby SDK.
+#
+# Subcommands:
+#   setup   Configure the SDK for your project (writes initializer)
+#   test    Send a synthetic test event and confirm the pipeline works
+
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+
+subcommand = ARGV.shift
+
+case subcommand
+when "setup"
+  require "apidepth/cli/setup"
+  Apidepth::CLI::Setup.run(ARGV)
+when "test"
+  require "apidepth/cli/test_cmd"
+  Apidepth::CLI::TestCmd.run(ARGV)
+when nil, "--help", "-h"
+  puts "Usage: bundle exec apidepth <subcommand> [options]"
+  puts ""
+  puts "Subcommands:"
+  puts "  setup   Configure the SDK and write your initializer"
+  puts "  test    Send a test event to confirm the pipeline works"
+  puts ""
+  puts "Run `bundle exec apidepth <subcommand> --help` for subcommand options."
+else
+  warn "Unknown subcommand: #{subcommand.inspect}"
+  warn "Run `bundle exec apidepth --help` for usage."
+  exit 1
+end

data/lib/apidepth/cli/framework_detector.rb

@@ -0,0 +1,82 @@
+# lib/apidepth/cli/framework_detector.rb
+#
+# Detects the web framework in the current directory by inspecting well-known
+# files. Returns a framework identifier and the recommended initializer path.
+# Used by `apidepth setup` to produce copy-paste-ready output.
+
+module Apidepth
+  module CLI
+    module FrameworkDetector
+      FRAMEWORKS = %i[rails sinatra].freeze
+
+      DetectedFramework = Struct.new(:name, :initializer_path, :initializer_snippet, keyword_init: true)
+
+      def self.detect(dir: Dir.pwd, api_key: nil, ignored_hosts: [], collector_url: nil)
+        framework = _detect_framework(dir)
+        _build_result(framework, api_key: api_key, ignored_hosts: ignored_hosts, collector_url: collector_url)
+      end
+
+      def self._detect_framework(dir)
+        return :rails   if File.exist?(File.join(dir, "config/application.rb"))
+        return :sinatra if File.exist?(File.join(dir, "config.ru"))
+
+        :generic
+      end
+
+      def self._build_result(framework, api_key:, ignored_hosts:, collector_url:)
+        key_val     = api_key       || "YOUR_API_KEY"
+        url_val     = collector_url || "https://collector.apidepth.io"
+        hosts_val   = ignored_hosts.empty? ? "[]" : ignored_hosts.map { |h| %("#{h}") }.join(", ").then { |s| "[#{s}]" }
+
+        case framework
+        when :rails
+          snippet = <<~RUBY
+            # config/initializers/apidepth.rb
+            Apidepth.configure do |config|
+              config.api_key       = #{key_val.inspect}
+              config.collector_url = #{url_val.inspect}
+              config.ignored_hosts = #{hosts_val}
+            end
+          RUBY
+          DetectedFramework.new(
+            name: :rails,
+            initializer_path: "config/initializers/apidepth.rb",
+            initializer_snippet: snippet
+          )
+        when :sinatra
+          snippet = <<~RUBY
+            # Top of your main app file (e.g. app.rb), before any routes
+            require "apidepth"
+            Apidepth.configure do |config|
+              config.api_key       = #{key_val.inspect}
+              config.collector_url = #{url_val.inspect}
+              config.ignored_hosts = #{hosts_val}
+            end
+            Apidepth.instrument!
+          RUBY
+          DetectedFramework.new(
+            name: :sinatra,
+            initializer_path: nil,
+            initializer_snippet: snippet
+          )
+        else
+          snippet = <<~RUBY
+            # Add to your application startup file
+            require "apidepth"
+            Apidepth.configure do |config|
+              config.api_key       = #{key_val.inspect}
+              config.collector_url = #{url_val.inspect}
+              config.ignored_hosts = #{hosts_val}
+            end
+            Apidepth.instrument!
+          RUBY
+          DetectedFramework.new(
+            name: :generic,
+            initializer_path: nil,
+            initializer_snippet: snippet
+          )
+        end
+      end
+    end
+  end
+end

data/lib/apidepth/cli/setup.rb

@@ -0,0 +1,136 @@
+# lib/apidepth/cli/setup.rb
+#
+# Implements `bundle exec apidepth setup`.
+#
+# Interactive mode (default):
+#   Opens the Apidepth dashboard in a browser so the developer can copy their
+#   API key, then prompts for ignored host patterns and writes the initializer.
+#
+# Non-interactive mode (CI/CD and AI-assisted setup):
+#   bundle exec apidepth setup --api-key $APIDEPTH_API_KEY --no-prompt
+#   All prompts are bypassed; output goes to stdout only.
+
+require "optparse"
+require "apidepth/cli/framework_detector"
+
+module Apidepth
+  module CLI
+    module Setup
+      DASHBOARD_KEYS_URL = "https://apidepth.io/dashboard/api-keys".freeze
+
+      def self.run(argv = ARGV)
+        options = parse_options(argv)
+        api_key = options[:api_key]
+        collector_url = options[:collector_url]
+        ignored_hosts = options[:ignored_hosts] || []
+        no_prompt = options[:no_prompt]
+        framework_override = options[:framework]
+
+        # Interactive: open dashboard and prompt for key
+        unless api_key || no_prompt
+          $stdout.puts "\nApidepth SDK Setup"
+          $stdout.puts "─" * 40
+          $stdout.puts "\nOpening your API keys page..."
+          _open_browser(DASHBOARD_KEYS_URL)
+          $stdout.print "\nPaste your API key: "
+          api_key = $stdin.gets&.strip
+          if api_key.nil? || api_key.empty?
+            warn "No API key provided. Aborting."
+            exit 1
+          end
+        end
+
+        # Interactive: prompt for ignored hosts
+        unless no_prompt
+          $stdout.puts "\nDefault ignored hosts (always skipped):"
+          %w[localhost 127.0.0.1 0.0.0.0 ::1].each { |h| $stdout.puts "  • #{h}" }
+          $stdout.puts "  • #{collector_url || 'collector.apidepth.io'}"
+          $stdout.puts "\nAny internal API patterns to ignore? (comma-separated, wildcards ok)"
+          $stdout.puts "  Examples: *.internal, *.local, *.svc.cluster.local, *.railway.internal"
+          $stdout.print "> "
+          input = $stdin.gets&.strip || ""
+          ignored_hosts += input.split(",").map(&:strip).reject(&:empty?) unless input.empty?
+        end
+
+        result = FrameworkDetector.detect(
+          dir: Dir.pwd,
+          api_key: api_key,
+          ignored_hosts: ignored_hosts,
+          collector_url: collector_url
+        )
+        # Override detected framework if flag provided
+        if framework_override
+          result = FrameworkDetector.detect(
+            dir: Dir.pwd,
+            api_key: api_key,
+            ignored_hosts: ignored_hosts,
+            collector_url: collector_url
+          )
+        end
+
+        _print_result(result, no_prompt: no_prompt)
+      end
+
+      def self.parse_options(argv)
+        options = {}
+        parser = OptionParser.new do |opts|
+          opts.banner = "Usage: bundle exec apidepth setup [options]"
+          opts.on("--api-key KEY", "API key (skips browser OAuth)") { |v| options[:api_key] = v }
+          opts.on("--collector-url URL", "Override collector URL") { |v| options[:collector_url] = v }
+          opts.on("--ignored-hosts HOSTS", "Comma-separated ignored host patterns") do |v|
+            options[:ignored_hosts] = v.split(",").map(&:strip)
+          end
+          opts.on("--no-prompt", "Non-interactive mode; output to stdout only") { options[:no_prompt] = true }
+          opts.on("--framework NAME", "Override framework detection (rails|sinatra|generic)") do |v|
+            options[:framework] = v
+          end
+          opts.on_tail("-h", "--help", "Show this message") do
+            puts opts
+            exit
+          end
+        end
+        begin
+          parser.parse!(argv.dup)
+        rescue OptionParser::InvalidOption => e
+          warn e.message
+          exit 1
+        end
+        options
+      end
+
+      def self._open_browser(url)
+        if RUBY_PLATFORM.include?("darwin")
+          system("open", url)
+        elsif RUBY_PLATFORM.include?("linux")
+          system("xdg-open", url)
+        else
+          $stdout.puts "Visit: #{url}"
+        end
+      end
+
+      def self._print_result(result, no_prompt:)
+        framework_label = result.name.to_s.capitalize
+        $stdout.puts "\nDetected: #{framework_label}" unless no_prompt
+
+        if result.initializer_path && !no_prompt
+          $stdout.puts "\nAdd the following to #{result.initializer_path}:"
+          $stdout.puts
+          $stdout.puts result.initializer_snippet
+          $stdout.print "Write to #{result.initializer_path}? [y/N] "
+          answer = $stdin.gets&.strip&.downcase
+          if answer == "y"
+            full_path = File.join(Dir.pwd, result.initializer_path)
+            FileUtils.mkdir_p(File.dirname(full_path))
+            File.write(full_path, result.initializer_snippet)
+            $stdout.puts "Written to #{result.initializer_path}"
+          else
+            $stdout.puts "(Not written — copy the snippet above into your codebase)"
+          end
+        else
+          $stdout.puts result.initializer_snippet
+        end
+        $stdout.puts "\nRun `bundle exec apidepth test` to confirm events are reaching the collector." unless no_prompt
+      end
+    end
+  end
+end

data/lib/apidepth/cli/test_cmd.rb

@@ -0,0 +1,136 @@
+# lib/apidepth/cli/test_cmd.rb
+#
+# Implements `bundle exec apidepth test`.
+#
+# Fires a synthetic event to the collector with `"test": true` in the payload.
+# The collector writes this to `test_events`, not the main events table.
+# Hard 5-second timeout. Per-failure-mode error messages with concrete next steps.
+
+require "net/http"
+require "uri"
+require "json"
+require "apidepth/version"
+
+module Apidepth
+  module CLI
+    module TestCmd
+      DEFAULT_COLLECTOR_URL = "https://collector.apidepth.io".freeze
+      TIMEOUT_SECONDS = 5
+
+      def self.run(argv = ARGV)
+        api_key, collector_url = _load_config(argv)
+
+        unless api_key
+          warn "No API key configured."
+          warn "Run `bundle exec apidepth setup` or set APIDEPTH_API_KEY."
+          exit 1
+        end
+
+        base_url = (collector_url || DEFAULT_COLLECTOR_URL).chomp("/")
+        $stdout.print "Sending test event to collector... "
+
+        begin
+          elapsed = _send_test_event(api_key, base_url)
+          $stdout.puts "✓ received in #{elapsed}ms"
+          $stdout.puts "Visit your dashboard: https://apidepth.io/dashboard"
+        rescue TestError => e
+          $stdout.puts "✗"
+          warn "\n#{e.message}"
+          warn e.hint if e.hint
+          exit 1
+        end
+      end
+
+      class TestError < StandardError
+        attr_reader :hint
+
+        def initialize(msg, hint: nil)
+          super(msg)
+          @hint = hint
+        end
+      end
+
+      def self._load_config(_argv)
+        # Try the SDK configuration first, fall back to environment variable
+        begin
+          require "apidepth"
+          cfg = Apidepth.configuration
+          api_key = cfg.api_key || ENV.fetch("APIDEPTH_API_KEY", nil)
+          collector_url = cfg.collector_url || ENV.fetch("APIDEPTH_COLLECTOR_URL", nil)
+        rescue StandardError
+          api_key = ENV.fetch("APIDEPTH_API_KEY", nil)
+          collector_url = ENV.fetch("APIDEPTH_COLLECTOR_URL", nil)
+        end
+        [api_key, collector_url]
+      end
+
+      def self._send_test_event(api_key, base_url)
+        uri = URI.parse("#{base_url}/v1/events")
+        payload = {
+          batch: [
+            {
+              vendor: "apidepth-test",
+              endpoint: "/test",
+              method: "GET",
+              status: 200,
+              outcome: "success",
+              duration_ms: 1,
+              cold_start: false,
+              env: "test",
+              ts: (Time.now.to_f * 1000).to_i,
+              test: true
+            }
+          ],
+          sdk: { name: "apidepth-ruby", version: Apidepth::VERSION }
+        }.to_json
+
+        start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == "https"
+        http.read_timeout = TIMEOUT_SECONDS
+        http.open_timeout = TIMEOUT_SECONDS
+
+        request = Net::HTTP::Post.new(uri.path.empty? ? "/" : uri.path)
+        request["Content-Type"]  = "application/json"
+        request["Authorization"] = "Bearer #{api_key}"
+        request.body = payload
+
+        # Bypass our own instrumentation
+        Thread.current[:apidepth_skip] = true
+        response = http.request(request)
+        Thread.current[:apidepth_skip] = false
+
+        case response.code.to_i
+        when 200, 201, 204
+          ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1000).round
+        when 401, 403
+          raise TestError.new(
+            "API key not recognised (HTTP #{response.code}).",
+            hint: "Check the key in your initializer matches your dashboard at https://apidepth.io/dashboard/api-keys"
+          )
+        else
+          raise TestError.new(
+            "Collector returned HTTP #{response.code}.",
+            hint: "Check https://status.apidepth.io for service status."
+          )
+        end
+      rescue Net::OpenTimeout, Net::ReadTimeout
+        raise TestError.new(
+          "No response after #{TIMEOUT_SECONDS} seconds.",
+          hint: "Check for a firewall blocking outbound port 443."
+        )
+      rescue OpenSSL::SSL::SSLError => e
+        raise TestError.new(
+          "SSL certificate verification failed: #{e.message}",
+          hint: "Check your Ruby SSL configuration."
+        )
+      rescue Errno::ECONNREFUSED, SocketError => e
+        raise TestError.new(
+          "Could not reach #{uri.host}: #{e.message}",
+          hint: "Check outbound HTTPS (port 443) is allowed from this environment."
+        )
+      end
+    end
+  end
+end

data/lib/apidepth/collector.rb

@@ -291,6 +291,10 @@ module Apidepth
         if int.between?(0, 0xFFFFFFFF)
           host = [int >> 24, (int >> 16) & 0xFF, (int >> 8) & 0xFF,
                   int & 0xFF].join(".")
+        else
+          raise ArgumentError,
+                "Apidepth collector_url must not target private, loopback, or link-local " \
+                "addresses (got #{url.host.inspect})."
         end
       end
 

data/lib/apidepth/configuration.rb

@@ -1,18 +1,29 @@
 # lib/apidepth/configuration.rb
 
+require "set"
+require "uri"
+
 module Apidepth
   class Configuration
+    # Always ignored regardless of user config. Covers unambiguous loopback
+    # addresses — we deliberately avoid wildcard patterns like *.internal here
+    # because silently swallowing traffic the developer wants to see is worse
+    # than showing mystery vendors. The setup subcommand prompts for custom
+    # patterns interactively.
+    HARD_IGNORED_HOSTS = %w[localhost 127.0.0.1 0.0.0.0 ::1].freeze
+
     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" }
+                  :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" }
+                  :capture_model_names # Boolean — read model field from AI vendor JSON responses
+
+    attr_reader :ignored_hosts, :collector_url
 
     def initialize
       @enabled                   = true
@@ -20,11 +31,48 @@ module Apidepth
       @registry_refresh_interval = 6 * 60 * 60
       @registry_cache_path       = "/tmp/apidepth_registry.json"
       @collector_url             = nil
-      @ignored_hosts             = []
+      @_user_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
+      @capture_model_names       = true  # read model field from AI vendor JSON responses
+      _rebuild_ignored_hosts
+    end
+
+    def collector_url=(url)
+      @collector_url = url
+      _rebuild_ignored_hosts
+    end
+
+    def ignored_hosts=(hosts)
+      @_user_hosts = Array(hosts || [])
+      _rebuild_ignored_hosts
+    end
+
+    # Returns true if +host+ should be skipped. Supports glob wildcards
+    # (* matches any sequence, ? matches one character) so customers can
+    # ignore entire internal domains: "*.internal", "*.svc.cluster.local".
+    def ignored_host?(host)
+      @_exact_ignored.include?(host) ||
+        @_glob_ignored.any? { |pat| File.fnmatch(pat, host) }
+    end
+
+    private
+
+    def _rebuild_ignored_hosts
+      all = HARD_IGNORED_HOSTS.dup + (@_user_hosts || [])
+      if @collector_url
+        begin
+          h = URI.parse(@collector_url).host
+          all << h if h
+        rescue URI::InvalidURIError
+          nil
+        end
+      end
+      @_exact_ignored = all.reject { |p| p.include?("*") || p.include?("?") }.to_set
+      @_glob_ignored  = all.select { |p| p.include?("*") || p.include?("?") }
+      @ignored_hosts  = Set.new(all)
     end
   end
 end

data/lib/apidepth/model_name_extractor.rb

@@ -0,0 +1,51 @@
+# lib/apidepth/model_name_extractor.rb
+require "json"
+require "set"
+#
+# Extracts the model name from AI vendor JSON response bodies.
+#
+# WHY response body rather than headers?
+# AI vendors (OpenAI, Anthropic, Gemini, Mistral, Cohere) return the active
+# model in the response body ({"model":"claude-3-opus-20240229",...}), not in
+# headers. This is the only reliable source.
+#
+# WHY only for known AI vendor hosts?
+# Body reads add a tiny overhead. Scoping to a hard-coded allowlist keeps the
+# hot path for non-AI vendors completely unaffected.
+#
+# Body safety: Net::HTTP::HTTPResponse#body memoizes after the first read.
+# Calling it here and returning the response to the application is safe — the
+# application receives the same cached body bytes.
+#
+# Streaming safety: streamed responses have Content-Type: text/event-stream, not
+# application/json. The content-type guard exits early before any body read.
+# The 8KB truncation is a belt-and-suspenders guard against unusually large bodies.
+
+module Apidepth
+  module ModelNameExtractor
+    AI_VENDOR_HOSTS = %w[
+      api.openai.com
+      api.anthropic.com
+      generativelanguage.googleapis.com
+      api.mistral.ai
+      api.cohere.com
+    ].to_set.freeze
+
+    MAX_BODY_BYTES = 8_192
+
+    def self.extract(host, response)
+      return nil unless Apidepth.configuration.capture_model_names
+      return nil unless AI_VENDOR_HOSTS.include?(host)
+      return nil unless response["content-type"]&.include?("application/json")
+
+      body = response.body
+      return nil if body.nil? || body.empty?
+
+      parsed = JSON.parse(body.byteslice(0, MAX_BODY_BYTES), symbolize_names: true)
+      model = parsed[:model]
+      model.is_a?(String) && !model.empty? ? model : nil
+    rescue JSON::ParserError, Encoding::UndefinedConversionError, TypeError
+      nil
+    end
+  end
+end

data/lib/apidepth/net_http_instrumentation.rb

@@ -10,7 +10,7 @@ module Apidepth
       # 4. Sample rate: probabilistically skip events
       return super if Thread.current[:apidepth_skip]
       return super unless Apidepth.configuration.enabled
-      return super if Apidepth.configuration.ignored_hosts.include?(address)
+      return super if Apidepth.configuration.ignored_host?(address)
       return super unless sampled?
 
       # Snapshot connection state BEFORE calling super.
@@ -72,21 +72,23 @@ module Apidepth
 
       now_ms = Process.clock_gettime(Process::CLOCK_REALTIME, :millisecond)
       rl = Apidepth::RateLimitHeaders.extract(response, now_ms)
+      model_name = Apidepth::ModelNameExtractor.extract(address, response)
+
+      event_attrs = {
+        vendor: vendor,
+        endpoint: normalized_path,
+        method: req.method,
+        status: status,
+        outcome: outcome,
+        duration_ms: duration_ms,
+        cold_start: cold_start,
+        env: resolve_env,
+        ts: now_ms
+      }.merge(rl || {})
+      event_attrs[:model_name] = model_name if model_name
 
       Apidepth::Collector.instance.record(
-        Apidepth::Event.build(
-          {
-            vendor: vendor,
-            endpoint: normalized_path,
-            method: req.method,
-            status: status,
-            outcome: outcome,
-            duration_ms: duration_ms,
-            cold_start: cold_start,
-            env: resolve_env,
-            ts: now_ms
-          }.merge(rl || {})
-        )
+        Apidepth::Event.build(event_attrs)
       )
     rescue StandardError => e
       Apidepth.logger&.debug("[Apidepth] Instrumentation error: #{e.class}: #{e.message}")

data/lib/apidepth/railtie.rb

@@ -27,6 +27,14 @@ module Apidepth
       # every outbound HTTP request.
       Apidepth.configuration.environment ||= Rails.env.to_s
 
+      # Use a per-app cache path so concurrent apps on the same host don't
+      # share a world-readable /tmp file. Falls back to /tmp only if Rails.root
+      # is somehow unavailable.
+      if defined?(Rails.root) && Rails.root
+        Apidepth.configuration.registry_cache_path ||=
+          Rails.root.join("tmp/apidepth_registry.json").to_s
+      end
+
       Net::HTTP.prepend(Apidepth::NetHTTPInstrumentation)
       Apidepth::VendorRegistry.load_extra_vendors(Apidepth.configuration.extra_vendors)
       Apidepth::RegistryLoader.load_and_start
@@ -41,16 +49,9 @@ module Apidepth
     end
 
     # -------------------------------------------------------------------------
-    # 3. Flush queue on graceful shutdown.
-    #    at_exit fires on SIGTERM → graceful Puma/Unicorn shutdown.
-    #    flush! rescues internally so a network error at shutdown is not fatal.
-    # -------------------------------------------------------------------------
-    config.after_initialize do
-      at_exit { Apidepth::Collector.instance.flush! }
-    end
-
-    # -------------------------------------------------------------------------
-    # 4. Fork safety for Puma cluster mode / Spring.
+    # 3. Shutdown flush + fork safety.
+    #
+    #    at_exit: flush the queue on graceful shutdown (SIGTERM → Puma/Unicorn).
     #
     #    after_fork: reset the Collector singleton so each worker gets a fresh
     #    instance with its own flush thread. The master's flush thread is not
@@ -65,6 +66,8 @@ module Apidepth
     #    ActiveSupport::ForkTracker is available in Rails 7.1+.
     # -------------------------------------------------------------------------
     config.after_initialize do
+      at_exit { Apidepth::Collector.instance.flush! }
+
       if defined?(ActiveSupport::ForkTracker)
         ActiveSupport::ForkTracker.after_fork { Apidepth::Collector.reset! }
       elsif defined?(Puma)

data/lib/apidepth/rate_limit_headers.rb

@@ -103,6 +103,8 @@ module Apidepth
       # Pure numeric
       if str.match?(/\A\d+(?:\.\d+)?\z/)
         n = str.to_f
+        # >= 1_000_000_000 is a Unix timestamp (seconds since epoch, e.g. "1716000000");
+        # smaller values are seconds-from-now (Retry-After style, e.g. "30").
         return n >= 1_000_000_000 ? (n * 1_000).to_i : now_ms + (n * 1_000).to_i
       end
 

data/lib/apidepth/version.rb

@@ -1,5 +1,5 @@
 # lib/apidepth/version.rb
 
 module Apidepth
-  VERSION = "0.3.0".freeze
+  VERSION = "0.5.0".freeze
 end

data/lib/apidepth.rb

@@ -1,14 +1,15 @@
 # lib/apidepth.rb
 #
 # Main entry point. Require order matters:
-#   1. version       — no dependencies
-#   2. configuration — no dependencies
-#   3. vendor_registry — no dependencies, boots from BUNDLED_BASELINE immediately
-#   4. rate_limit_headers — no dependencies; used by net_http_instrumentation
-#   5. net_http_instrumentation — depends on vendor_registry + collector (via lazy reference)
-#   5. collector     — depends on configuration
-#   6. registry_loader — depends on collector + vendor_registry
-#   7. railtie       — depends on all of the above; only loaded in a Rails context
+#   1. version             — no dependencies
+#   2. configuration       — no dependencies
+#   3. vendor_registry     — no dependencies, boots from BUNDLED_BASELINE immediately
+#   4. rate_limit_headers  — no dependencies; used by net_http_instrumentation
+#   5. model_name_extractor — no dependencies; used by net_http_instrumentation
+#   6. net_http_instrumentation — depends on vendor_registry + collector (via lazy reference)
+#   7. collector           — depends on configuration
+#   8. registry_loader     — depends on collector + vendor_registry
+#   9. railtie             — depends on all of the above; only loaded in a Rails context
 
 require "logger"
 require "apidepth/version"
@@ -16,6 +17,7 @@ require "apidepth/configuration"
 require "apidepth/event"
 require "apidepth/vendor_registry"
 require "apidepth/rate_limit_headers"
+require "apidepth/model_name_extractor"
 require "apidepth/net_http_instrumentation"
 require "apidepth/collector"
 require "apidepth/registry_loader"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: apidepth
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Apidepth
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-27 00:00:00.000000000 Z
+date: 2026-06-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json
@@ -114,16 +114,22 @@ description: Know if your API slowness is your code or the vendor's. Apidepth in
   you, or everyone.
 email:
 - hello@apidepth.io
-executables: []
+executables:
+- apidepth
 extensions: []
 extra_rdoc_files: []
 files:
 - LICENSE
 - README.md
+- bin/apidepth
 - lib/apidepth.rb
+- lib/apidepth/cli/framework_detector.rb
+- lib/apidepth/cli/setup.rb
+- lib/apidepth/cli/test_cmd.rb
 - lib/apidepth/collector.rb
 - lib/apidepth/configuration.rb
 - lib/apidepth/event.rb
+- lib/apidepth/model_name_extractor.rb
 - lib/apidepth/net_http_instrumentation.rb
 - lib/apidepth/railtie.rb
 - lib/apidepth/rate_limit_headers.rb
@@ -147,7 +153,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.7.0
+      version: 3.1.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="