llm_cost_tracker 0.5.1 → 0.5.3

data/docs/technical/extension-points.md

@@ -0,0 +1,111 @@
+# Extension Points
+
+Extensions should plug into existing provider-agnostic boundaries. If a new feature needs a provider-specific branch outside ingestion code, revisit the design first.
+
+## Custom Parsers
+
+Use parser registration when a provider or gateway has a response shape the built-ins do not cover.
+
+Expected parser contract:
+
+- `match?(url)` detects supported request URLs.
+- `parse(request_url, request_body, response_status, response_body)` returns `ParsedUsage` or `nil`.
+- `parse_stream(request_url, request_body, response_status, events)` returns `ParsedUsage` or `nil`.
+- `streaming_request?(request_url, request_body)` detects streaming requests when the provider does not use a simple `stream: true` field.
+- `provider_names` returns provider names that can be used by `track_stream(provider: ...)`.
+
+Use `Parsers::Base` helpers for URL matching and stream-event extraction. Use `Parsers::OpenaiUsage` only for OpenAI-shaped usage hashes.
+
+## SDK Integrations
+
+Use SDK integrations when a popular Ruby client does not expose a Faraday middleware stack but returns stable usage objects. RubyLLM and the official `openai` and `anthropic` gems qualify. Faraday-based clients that expose a middleware hook, such as `ruby-openai`'s constructor block, are covered by the Faraday middleware instead. Clients with no stable hook must use the explicit `track` / `track_stream` fallback until an integration exists.
+
+Expected integration contract:
+
+- no hard dependency on the provider SDK
+- fail-fast boot when an explicitly enabled SDK is missing or below the minimum supported version
+- install-time checks for the target classes and methods
+- idempotent `Module#prepend` around narrow resource methods
+- no tracking when the integration is not enabled in configuration
+- canonical usage fields passed to `Tracker.record`
+
+SDK integrations belong under `LlmCostTracker::Integrations`. Do not put SDK object-shape handling in parsers, storage, or pricing.
+
+External integrations can register an adapter with
+`LlmCostTracker::Integrations.register(:name, adapter)`. The adapter must
+respond to `install` and `status`, and enabled names are still selected through
+`config.instrument`.
+
+## OpenAI-Compatible Gateways
+
+Use `config.openai_compatible_providers` when a gateway speaks the OpenAI request and response shape.
+
+This is for shape compatibility, not pricing. Gateway-specific model IDs or discounts belong in `prices_file` or `pricing_overrides`.
+
+## Prices
+
+Use `config.prices_file` for the app's source-controlled price snapshot.
+
+Use `config.pricing_overrides` for urgent or environment-specific overrides that are easier to keep in Ruby.
+
+Supported canonical keys:
+
+- `input`
+- `output`
+- `cache_read_input`
+- `cache_write_input`
+- `batch_input`
+- `batch_output`
+- mode-prefixed keys such as `priority_input` or `batch_cache_read_input`
+
+Provider-specific pricing details must be translated before they reach runtime pricing.
+
+## Tags
+
+Tags are the extension point for application attribution:
+
+- tenant
+- user
+- feature
+- trace
+- job
+- workflow
+- agent session
+
+Use `config.default_tags`, middleware `tags:`, explicit metadata, and `LlmCostTracker.with_tags`. Do not add first-class columns for app dimensions unless the ledger needs that field for provider-agnostic billing behavior.
+
+## Storage
+
+Use `storage_backend = :custom` only when the host app needs to own persistence completely.
+
+Custom storage receives a canonical `Event`. Returning `false` tells the tracker not to run budget checks for that event.
+
+ActiveRecord storage is the production path for dashboards and cross-process budgets.
+
+Storage adapters can register with
+`LlmCostTracker::Storage.register(:name, backend)`. A backend must respond to
+`save(event)` and may expose `verify` for capture diagnostics.
+
+## Dashboard
+
+Dashboard additions should be read-only services under `app/services/llm_cost_tracker/dashboard`.
+
+Keep controller actions thin:
+
+- parse params
+- build filtered scope
+- call services
+- render views
+
+Keep view logic in helpers when it is reused across pages. Do not add JavaScript for dashboard behavior.
+
+## Generators
+
+Generators are installation contracts. New generator behavior should be:
+
+- additive when possible
+- idempotent where Rails generator APIs allow it
+- explicit about destructive or table-rewriting operations
+- covered by generator template specs
+
+Fresh install templates and upgrade generators should stay aligned. If a fresh install gains a column or index, the upgrade path needs a generator unless the next release intentionally makes a breaking install path.

data/docs/technical/module-map.md

@@ -0,0 +1,197 @@
+# Module Map
+
+LLM Cost Tracker is organized around a small set of durable responsibilities. File layout does not need to mirror these modules perfectly, but new code should fit one of these boundaries.
+
+## Public API and Configuration
+
+Primary files:
+
+- `lib/llm_cost_tracker.rb`
+- `lib/llm_cost_tracker/configuration.rb`
+- `lib/llm_cost_tracker/tag_context.rb`
+- `lib/llm_cost_tracker/doctor.rb`
+- `lib/llm_cost_tracker/logging.rb`
+- `lib/llm_cost_tracker/errors.rb`
+
+Responsibilities:
+
+- Expose `configure`, `track`, `track_stream`, `with_tags`, and `enforce_budget!`.
+- Keep configuration immutable after `configure` returns.
+- Merge scoped tags and default tags without leaking state across threads.
+- Report installation and pricing health through `llm_cost_tracker:doctor`.
+
+This module should stay small. It can orchestrate other modules, but it should not contain provider parsing, SQL details, dashboard aggregation, or pricing-source logic.
+
+## SDK Integrations
+
+Primary files:
+
+- `lib/llm_cost_tracker/integrations/*`
+
+Responsibilities:
+
+- Add optional instrumentation for Ruby SDKs without adding provider SDK dependencies.
+- Install narrow, idempotent `Module#prepend` wrappers around stable SDK resource methods.
+- Extract SDK response objects into canonical usage fields.
+- Keep SDK-specific object handling out of `Tracker` and storage.
+
+Integrations are for Ruby SDK object shapes. Parsers are for HTTP and stream payload shapes.
+
+## Ingestion
+
+Primary files:
+
+- `lib/llm_cost_tracker/middleware/faraday.rb`
+- `lib/llm_cost_tracker/stream_collector.rb`
+- `lib/llm_cost_tracker/parsed_usage.rb`
+- `lib/llm_cost_tracker/request_url.rb`
+- `lib/llm_cost_tracker/parsers/*`
+
+Responsibilities:
+
+- Detect supported LLM HTTP requests.
+- Parse provider responses and stream events into `ParsedUsage`.
+- Translate provider-specific fields into canonical usage fields.
+- Preserve app streaming behavior while teeing events for tracking.
+
+Provider-specific code belongs here. The output boundary is `ParsedUsage`, not raw provider JSON.
+
+## Canonical Ledger
+
+Primary files:
+
+- `lib/llm_cost_tracker/tracker.rb`
+- `lib/llm_cost_tracker/event.rb`
+- `lib/llm_cost_tracker/event_metadata.rb`
+- `lib/llm_cost_tracker/usage_breakdown.rb`
+- `lib/llm_cost_tracker/cost.rb`
+- `lib/llm_cost_tracker/unknown_pricing.rb`
+
+Responsibilities:
+
+- Normalize provider, model, usage, tags, latency, streaming flags, and response IDs.
+- Price canonical usage through `Pricing`.
+- Emit `ActiveSupport::Notifications`.
+- Persist the event through the configured storage backend.
+- Run budget checks after successful storage.
+
+This module must remain provider-agnostic. It should never branch on a specific provider model family.
+
+## Pricing
+
+Primary files:
+
+- `lib/llm_cost_tracker/pricing.rb`
+- `lib/llm_cost_tracker/price_registry.rb`
+- `lib/llm_cost_tracker/price_freshness.rb`
+- `lib/llm_cost_tracker/prices.json`
+- `lib/llm_cost_tracker/price_sync/*`
+- `lib/tasks/llm_cost_tracker.rake`
+
+Responsibilities:
+
+- Load bundled prices, local price snapshots, and Ruby overrides.
+- Apply pricing precedence: `pricing_overrides`, `prices_file`, bundled prices.
+- Calculate costs from canonical usage fields.
+- Update local snapshots from the maintained LLM Cost Tracker price registry.
+- Validate snapshot schema compatibility, gem-version compatibility, and price entry shape.
+
+Pricing refresh must not perform boot-time or request-time network work. Runtime pricing uses bundled prices, local files, and in-memory caches.
+
+## Storage
+
+Primary files:
+
+- `lib/llm_cost_tracker/llm_api_call.rb`
+- `lib/llm_cost_tracker/period_total.rb`
+- `lib/llm_cost_tracker/llm_api_call_metrics.rb`
+- `lib/llm_cost_tracker/storage/active_record_store.rb`
+- `lib/llm_cost_tracker/storage/active_record_rollups.rb`
+- `lib/llm_cost_tracker/storage/registry.rb`
+- `lib/llm_cost_tracker/tags_column.rb`
+- `lib/llm_cost_tracker/tag_key.rb`
+- `lib/llm_cost_tracker/tag_sql.rb`
+- `lib/llm_cost_tracker/tag_query.rb`
+- `lib/llm_cost_tracker/tag_accessors.rb`
+- `lib/llm_cost_tracker/period_grouping.rb`
+
+Responsibilities:
+
+- Persist canonical events into ActiveRecord.
+- Hide database-specific tag storage differences.
+- Maintain period rollups for hot-path budget reads.
+- Provide safe scopes for filters, periods, tags, unknown pricing, and reports.
+
+Storage can know about database adapters and optional columns. It should not parse provider responses or fetch price data.
+
+## Budgets and Retention
+
+Primary files:
+
+- `lib/llm_cost_tracker/budget.rb`
+- `lib/llm_cost_tracker/retention.rb`
+- `lib/llm_cost_tracker/storage/active_record_rollups.rb`
+
+Responsibilities:
+
+- Enforce monthly, daily, and per-call guardrails.
+- Support preflight blocking where ActiveRecord rollups are available.
+- Prune old ledger rows in batches.
+- Keep budget checks bounded by maintained aggregates, not by full ledger scans.
+
+Budget behavior is part of the hot path. Any change here must be measured against per-request overhead.
+
+## Dashboard and Reporting
+
+Primary files:
+
+- `lib/llm_cost_tracker/report*.rb`
+- `app/controllers/llm_cost_tracker/*`
+- `app/services/llm_cost_tracker/dashboard/*`
+- `app/helpers/llm_cost_tracker/*`
+- `app/views/llm_cost_tracker/*`
+- `app/assets/llm_cost_tracker/application.css`
+
+Responsibilities:
+
+- Render server-side dashboard pages.
+- Aggregate spend, calls, providers, models, tags, latency, and data quality.
+- Export filtered calls as CSV.
+- Keep dashboard queries explicit and indexed.
+
+Dashboard code may run grouped SQL because it is user-initiated reporting. It must stay server-rendered and must not introduce a JavaScript bundle.
+
+## Rails Integration and Generators
+
+Primary files:
+
+- `lib/llm_cost_tracker/railtie.rb`
+- `lib/llm_cost_tracker/engine.rb`
+- `lib/llm_cost_tracker/assets.rb`
+- `lib/llm_cost_tracker/generators/llm_cost_tracker/*`
+- `config/routes.rb`
+
+Responsibilities:
+
+- Register rake tasks and Faraday middleware.
+- Mount the isolated Rails engine.
+- Generate migrations, initializer, dashboard route, and local price snapshots.
+- Serve dashboard CSS as a fingerprinted engine asset.
+
+Generator templates are public installation contracts. Treat them like API.
+
+## Test Suites
+
+Primary files:
+
+- `spec/llm_cost_tracker/*`
+- `spec/llm_cost_tracker/engine/*`
+- `spec/llm_cost_tracker/dashboard/*`
+- `spec/fixtures/pricing/*`
+- `spec/support/*`
+
+Responsibilities:
+
+- Cover canonical behavior, parser boundaries, pricing precedence, storage rollups, dashboard rendering, generators, and concurrency.
+- Keep request specs plain and stable.
+- Run through `bin/check` before release work or commits that touch code.

data/docs/technical/operational-notes.md

@@ -0,0 +1,77 @@
+# Operational Notes
+
+This file describes runtime constraints that should shape implementation decisions.
+
+## Hot Paths
+
+Hot-path code includes:
+
+- Faraday middleware request and response handling
+- stream collection
+- `Tracker.record`
+- `Pricing.cost_for`
+- ActiveRecord event persistence
+- budget checks
+
+Hot-path code must avoid:
+
+- network calls
+- per-event schema discovery beyond memoized checks
+- full ledger aggregation
+- unbounded stream buffers
+- N+1 queries
+- price-refresh work
+
+## Pricing Freshness
+
+Runtime pricing is local:
+
+1. Ruby overrides
+2. configured local price snapshot
+3. bundled prices
+
+Price update tasks are operational tooling. They can fetch the maintained LLM Cost Tracker price snapshot because the operator runs them intentionally. Request tracking must never depend on live provider pricing pages.
+
+## Budget Reads
+
+Monthly and daily budgets should read `llm_cost_tracker_period_totals` when the table exists. Falling back to summing `llm_api_calls` is an upgrade compatibility path, not the preferred production path.
+
+Per-call budgets are checked from the current event only.
+
+## Retention
+
+Retention may delete old `llm_api_calls`. Period rollups are the durable budget aggregate. Any migration or refactor that changes rollups must preserve the meaning of retained totals or clearly document a breaking change.
+
+## Optional Columns
+
+The gem supports upgrade paths where older apps may not have every column yet. Optional column checks must be memoized and refreshed when ActiveRecord column information is reset.
+
+Do not put table or column checks directly in loops that run for every event without caching.
+
+## Dashboard Queries
+
+Dashboard queries can aggregate because they are user-initiated. They should still use:
+
+- filtered scopes
+- bounded pagination
+- database-side grouping
+- indexes that match common filters
+- single aggregate queries for related counters
+
+Avoid loading ledger rows into Ruby just to count, sum, group, or sort.
+
+## Streaming
+
+Streaming capture must keep the host app's stream behavior intact.
+
+The middleware should collect enough data to parse final usage while bounding memory. When usage never arrives or capture overflows, record an unknown-usage event so Data Quality can surface the gap.
+
+## Release Checks
+
+Run `bin/check` before committing code changes intended for release. It includes full RuboCop, full RSpec, project coverage, and patch coverage for the current diff.
+
+Project coverage defaults to the Codecov target. Patch coverage defaults to 95% so local checks stay stricter than Codecov parser differences. Thresholds can be adjusted locally with `PROJECT_COVERAGE_MIN`, `PATCH_COVERAGE_MIN`, or `COVERAGE_BASE`.
+
+For the closest match to the Codecov upload job, run `BUNDLE_GEMFILE=gemfiles/rails_8_1.gemfile bin/check`.
+
+Docs-only changes do not require the full suite, but any code, generator, migration, parser, pricing, dashboard, or storage change does.

data/docs/upgrading.md

@@ -0,0 +1,46 @@
+# Upgrading
+
+LLM Cost Tracker is still moving quickly, so upgrades should be explicit:
+inspect the changelog, run doctor, and apply only the generators your schema is
+missing.
+
+The version-by-version upgrade guide is moving here from the README.
+
+## Canonical Sources
+
+Until this page is expanded, use:
+
+- [Changelog](../CHANGELOG.md)
+- [Quickstart](../README.md#quickstart)
+- [Operations](operations.md)
+
+## Schema Generators
+
+Existing installs can add newer optional columns through focused generators:
+
+```bash
+bin/rails generate llm_cost_tracker:add_period_totals
+bin/rails generate llm_cost_tracker:add_streaming
+bin/rails generate llm_cost_tracker:add_provider_response_id
+bin/rails generate llm_cost_tracker:add_usage_breakdown
+bin/rails generate llm_cost_tracker:upgrade_tags_to_jsonb
+bin/rails generate llm_cost_tracker:upgrade_cost_precision
+bin/rails generate llm_cost_tracker:add_latency_ms
+bin/rails db:migrate
+bin/rails llm_cost_tracker:doctor
+```
+
+On PostgreSQL, `upgrade_tags_to_jsonb` rewrites `llm_api_calls`. For large
+tables, run it during a maintenance window or replace it with a two-phase
+backfill.
+
+## Upgrade Habit
+
+Run:
+
+```bash
+bin/rails llm_cost_tracker:doctor
+```
+
+Doctor tells you which optional columns and production-hardening pieces are still
+missing.

data/lib/llm_cost_tracker/capture_verifier.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require_relative "storage/dispatcher"
+
+module LlmCostTracker
+  class CaptureVerifier
+    Check = Data.define(:status, :name, :message)
+
+    class << self
+      def call = new.checks
+
+      def report(checks = call)
+        (["LLM Cost Tracker capture verification"] + checks.map { |check| format_check(check) }).join("\n")
+      end
+
+      def healthy?(checks = call)
+        checks.none? { |check| check.status == :error }
+      end
+
+      private
+
+      def format_check(check)
+        "[#{check.status}] #{check.name}: #{check.message}"
+      end
+    end
+
+    def checks
+      [
+        enabled_check,
+        *integration_checks,
+        *storage_checks
+      ].compact
+    end
+
+    private
+
+    def enabled_check
+      return Check.new(:ok, "tracking", "enabled") if LlmCostTracker.configuration.enabled
+
+      Check.new(:error, "tracking", "disabled; set config.enabled = true before verifying capture")
+    end
+
+    def integration_checks
+      enabled = LlmCostTracker.configuration.instrumented_integrations
+      if enabled.empty?
+        return [
+          Check.new(:ok, "sdk integrations", "none enabled; Faraday middleware and manual capture remain available")
+        ]
+      end
+
+      LlmCostTracker::Integrations.checks.map do |check|
+        Check.new(check.status, "sdk integration #{check.name}", check.message)
+      end
+    end
+
+    def storage_checks
+      backend = LlmCostTracker::Storage::Registry.fetch(LlmCostTracker.configuration.storage_backend)
+      unless backend.respond_to?(:verify)
+        return [
+          Check.new(:warn, "storage", "#{LlmCostTracker.configuration.storage_backend} backend has no verifier")
+        ]
+      end
+
+      backend.verify.map do |check|
+        Check.new(check.status, check.name, check.message)
+      end
+    rescue LlmCostTracker::Error => e
+      [Check.new(:error, "storage", e.message)]
+    end
+  end
+end

data/lib/llm_cost_tracker/configuration/instrumentation.rb

@@ -31,7 +31,7 @@ module LlmCostTracker
     end
 
     def available_instrumentation_names
-      Integrations::Registry::INTEGRATIONS.keys
+      Integrations::Registry.names
     end
   end
 end

data/lib/llm_cost_tracker/configuration/storage_backend.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module LlmCostTracker
+  module ConfigurationStorageBackend
+    def storage_backend=(value)
+      ensure_shared_configuration_mutable!
+      @storage_backend = normalize_storage_backend(value)
+    end
+
+    private
+
+    def normalize_storage_backend(value)
+      value = :log if value.nil?
+      value = value.to_sym
+      return value if self.class::STORAGE_BACKENDS.include?(value)
+      return value if defined?(Storage::Registry) && Storage::Registry.registered?(value)
+
+      names = if defined?(Storage::Registry)
+                Storage::Registry.names
+              else
+                self.class::STORAGE_BACKENDS
+              end
+      raise Error, "Unknown storage_backend: #{value.inspect}. Use one of: #{names.join(', ')}"
+    end
+  end
+end

data/lib/llm_cost_tracker/configuration.rb

@@ -1,38 +1,30 @@
 # frozen_string_literal: true
 
 require_relative "errors"
+require_relative "tag_key"
 require_relative "value_helpers"
 require_relative "configuration/instrumentation"
+require_relative "configuration/storage_backend"
 
 module LlmCostTracker
   class Configuration
     include ConfigurationInstrumentation
+    include ConfigurationStorageBackend
 
-    OPENAI_COMPATIBLE_PROVIDERS = {
-      "openrouter.ai" => "openrouter",
-      "api.deepseek.com" => "deepseek"
-    }.freeze
+    OPENAI_COMPATIBLE_PROVIDERS = { "openrouter.ai" => "openrouter", "api.deepseek.com" => "deepseek" }.freeze
 
     BUDGET_EXCEEDED_BEHAVIORS = %i[notify raise block_requests].freeze
     STORAGE_ERROR_BEHAVIORS = %i[ignore warn raise].freeze
     STORAGE_BACKENDS = %i[log active_record custom].freeze
     UNKNOWN_PRICING_BEHAVIORS = %i[ignore warn raise].freeze
-    SHARED_SCALAR_ATTRIBUTES = %i[
-      enabled
-      custom_storage
-      on_budget_exceeded
-      monthly_budget
-      daily_budget
-      per_call_budget
-      log_level
-      prices_file
-    ].freeze
+    SHARED_SCALAR_ATTRIBUTES = %i[enabled custom_storage on_budget_exceeded monthly_budget daily_budget per_call_budget
+                                  log_level prices_file max_tag_count max_tag_value_bytesize].freeze
     SHARED_ENUM_ATTRIBUTES = {
-      storage_backend: [STORAGE_BACKENDS, :log],
       budget_exceeded_behavior: [BUDGET_EXCEEDED_BEHAVIORS, :notify],
       storage_error_behavior: [STORAGE_ERROR_BEHAVIORS, :warn],
       unknown_pricing_behavior: [UNKNOWN_PRICING_BEHAVIORS, :warn]
     }.freeze
+    DEFAULT_REDACTED_TAG_KEYS = %w[api_key access_token authorization credential password refresh_token secret].freeze
 
     attr_reader(
       *SHARED_SCALAR_ATTRIBUTES,
@@ -41,6 +33,7 @@ module LlmCostTracker
       :pricing_overrides,
       :instrumented_integrations,
       :report_tag_breakdowns,
+      :redacted_tag_keys,
       :storage_backend,
       :storage_error_behavior,
       :unknown_pricing_behavior,
@@ -61,9 +54,12 @@ module LlmCostTracker
       self.unknown_pricing_behavior = :warn
       @log_level          = :info
       @prices_file        = nil
-      @pricing_overrides  = {}
+      @max_tag_count      = 50
+      @max_tag_value_bytesize = 1024
+      @pricing_overrides = {}
       @instrumented_integrations = []
       @report_tag_breakdowns = []
+      @redacted_tag_keys = DEFAULT_REDACTED_TAG_KEYS.dup
       self.openai_compatible_providers = OPENAI_COMPATIBLE_PROVIDERS
       @finalized = false
     end
@@ -85,7 +81,12 @@ module LlmCostTracker
 
     def report_tag_breakdowns=(value)
       ensure_shared_configuration_mutable!
-      @report_tag_breakdowns = value
+      @report_tag_breakdowns = normalize_report_tag_breakdowns(value)
+    end
+
+    def redacted_tag_keys=(value)
+      ensure_shared_configuration_mutable!
+      @redacted_tag_keys = Array(value).map(&:to_s)
     end
 
     SHARED_SCALAR_ATTRIBUTES.each do |name|
@@ -107,6 +108,7 @@ module LlmCostTracker
       @pricing_overrides = ValueHelpers.deep_freeze(@pricing_overrides || {})
       @instrumented_integrations = ValueHelpers.deep_freeze(@instrumented_integrations || [])
       @report_tag_breakdowns = ValueHelpers.deep_freeze(Array(@report_tag_breakdowns))
+      @redacted_tag_keys = ValueHelpers.deep_freeze(Array(@redacted_tag_keys))
       @openai_compatible_providers = ValueHelpers.deep_freeze(@openai_compatible_providers || {})
       @finalized = true
       self
@@ -123,6 +125,7 @@ module LlmCostTracker
         ValueHelpers.deep_dup(@instrumented_integrations || [])
       )
       copy.instance_variable_set(:@report_tag_breakdowns, ValueHelpers.deep_dup(@report_tag_breakdowns || []))
+      copy.instance_variable_set(:@redacted_tag_keys, ValueHelpers.deep_dup(@redacted_tag_keys || []))
       copy.instance_variable_set(
         :@openai_compatible_providers,
         ValueHelpers.deep_dup(@openai_compatible_providers || {})
@@ -149,6 +152,10 @@ module LlmCostTracker
       end
     end
 
+    def normalize_report_tag_breakdowns(value)
+      Array(value).map { |key| TagKey.validate!(key, error_class: Error) }
+    end
+
     def ensure_shared_configuration_mutable!
       return unless finalized?
 

data/lib/llm_cost_tracker/doctor/capture_check.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module LlmCostTracker
+  class Doctor
+    class CaptureCheck
+      def self.call(check_class)
+        new(check_class).call
+      end
+
+      def initialize(check_class)
+        @check_class = check_class
+      end
+
+      def call
+        config = LlmCostTracker.configuration
+        return disabled_check unless config.enabled
+        return integrations_check(config.instrumented_integrations) if config.instrumented_integrations.any?
+
+        check(:ok, "no SDK integrations enabled; Faraday middleware and manual capture remain available")
+      end
+
+      private
+
+      attr_reader :check_class
+
+      def disabled_check
+        check(:warn, "tracking is disabled; set config.enabled = true to record calls")
+      end
+
+      def integrations_check(integrations)
+        check(:ok, "SDK integrations enabled: #{integrations.join(', ')}")
+      end
+
+      def check(status, message)
+        check_class.new(status, "capture", message)
+      end
+    end
+  end
+end