riffer 0.35.0 → 0.36.0

data/sig/generated/riffer/guardrails/runner.rbs

@@ -40,10 +40,6 @@ class Riffer::Guardrails::Runner
   # : (Riffer::Guardrail, untyped, messages: Array[Riffer::Messages::Base]?) -> Riffer::Guardrails::Result
   def execute_guardrail: (Riffer::Guardrail, untyped, messages: Array[Riffer::Messages::Base]?) -> Riffer::Guardrails::Result
 
-  # --
-  # : (Riffer::Guardrail) { () -> Riffer::Guardrails::Result } -> Riffer::Guardrails::Result
-  def instrument_guardrail: (Riffer::Guardrail) { () -> Riffer::Guardrails::Result } -> Riffer::Guardrails::Result
-
   # --
   # : (Riffer::Guardrail, untyped, messages: Array[Riffer::Messages::Base]?) -> Riffer::Guardrails::Result
   def run_guardrail_phase: (Riffer::Guardrail, untyped, messages: Array[Riffer::Messages::Base]?) -> Riffer::Guardrails::Result
@@ -52,10 +48,6 @@ class Riffer::Guardrails::Runner
   # : (Riffer::Guardrail) -> Hash[String, untyped]
   def guardrail_span_attributes: (Riffer::Guardrail) -> Hash[String, untyped]
 
-  # --
-  # : (Riffer::Guardrail, String?) -> Hash[String, untyped]
-  def guardrail_metric_attributes: (Riffer::Guardrail, String?) -> Hash[String, untyped]
-
   # A block is a handled outcome, so its span status stays unset — an error
   # span status is reserved for a raised exception.
   # --

data/sig/generated/riffer/providers/base.rbs

@@ -98,30 +98,12 @@ class Riffer::Providers::Base
   # : (String?, Hash[Symbol, untyped]) -> Hash[String, untyped]
   def chat_span_attributes: (String?, Hash[Symbol, untyped]) -> Hash[String, untyped]
 
-  # --
-  # : (String?, ?Hash[String, String]) -> Hash[String, untyped]
-  def chat_metric_base_attributes: (String?, ?Hash[String, String]) -> Hash[String, untyped]
-
-  # --
-  # : (String?, String?, ?Hash[String, String]) -> Hash[String, untyped]
-  def chat_metric_attributes: (String?, String?, ?Hash[String, String]) -> Hash[String, untyped]
-
-  # Maps normalized tags to their namespaced span/metric attribute form. An
-  # empty map yields an empty hash, so merging it is a no-op.
+  # Maps normalized tags to their namespaced span attribute form. An empty map
+  # yields an empty hash, so merging it is a no-op.
   # --
   # : (Hash[String, String]) -> Hash[String, String]
   def tag_attributes: (Hash[String, String]) -> Hash[String, String]
 
-  # Per-call only — the run level would double-count an aggregate.
-  # --
-  # : (String?, Riffer::Providers::TokenUsage?, ?Hash[String, String]) -> void
-  def record_token_usage_metric: (String?, Riffer::Providers::TokenUsage?, ?Hash[String, String]) -> void
-
-  # Per-call only — the run level would double-count an aggregate.
-  # --
-  # : (String?, Riffer::Providers::TokenUsage?, ?Hash[String, String]) -> void
-  def record_cost_metric: (String?, Riffer::Providers::TokenUsage?, ?Hash[String, String]) -> void
-
   # --
   # : ((Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span), Symbol?, String?) -> void
   def record_finish_reason: (Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span, Symbol?, String?) -> void

data/sig/generated/riffer/tools/runtime.rbs

@@ -56,12 +56,8 @@ class Riffer::Tools::Runtime
   # : (Riffer::Messages::Assistant::ToolCall, ?Hash[String, String]) -> Hash[String, untyped]
   def tool_span_attributes: (Riffer::Messages::Assistant::ToolCall, ?Hash[String, String]) -> Hash[String, untyped]
 
-  # --
-  # : (Riffer::Messages::Assistant::ToolCall, String?, ?Hash[String, String]) -> Hash[String, untyped]
-  def tool_metric_attributes: (Riffer::Messages::Assistant::ToolCall, String?, ?Hash[String, String]) -> Hash[String, untyped]
-
-  # Maps normalized tags to their namespaced span/metric attribute form. An
-  # empty map yields an empty hash, so merging it is a no-op.
+  # Maps normalized tags to their namespaced span attribute form. An empty map
+  # yields an empty hash, so merging it is a no-op.
   # --
   # : (Hash[String, String]) -> Hash[String, String]
   def tag_attributes: (Hash[String, String]) -> Hash[String, String]

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: riffer
 version: !ruby/object:Gem::Version
-  version: 0.35.0
+  version: 0.36.0
 platform: ruby
 authors:
 - Jake Bottrall
@@ -35,14 +35,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.49.0
+        version: 1.51.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.49.0
+        version: 1.51.0
 - !ruby/object:Gem::Dependency
   name: aws-sdk-bedrockruntime
   requirement: !ruby/object:Gem::Requirement
@@ -108,7 +108,7 @@ dependencies:
         version: '2.25'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '2.40'
+        version: '2.42'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -118,7 +118,7 @@ dependencies:
         version: '2.25'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '2.40'
+        version: '2.42'
 - !ruby/object:Gem::Dependency
   name: io-event
   requirement: !ruby/object:Gem::Requirement
@@ -278,7 +278,6 @@ files:
 - docs/14_MCP.md
 - docs/15_SERIALIZATION.md
 - docs/16_TRACING.md
-- docs/17_METRICS.md
 - docs/providers/01_PROVIDERS.md
 - docs/providers/02_AMAZON_BEDROCK.md
 - docs/providers/03_ANTHROPIC.md
@@ -334,10 +333,6 @@ files:
 - lib/riffer/messages/system.rb
 - lib/riffer/messages/tool.rb
 - lib/riffer/messages/user.rb
-- lib/riffer/metrics.rb
-- lib/riffer/metrics/instruments.rb
-- lib/riffer/metrics/no_op.rb
-- lib/riffer/metrics/otel.rb
 - lib/riffer/params.rb
 - lib/riffer/params/boolean.rb
 - lib/riffer/params/param.rb
@@ -455,10 +450,6 @@ files:
 - sig/generated/riffer/messages/system.rbs
 - sig/generated/riffer/messages/tool.rbs
 - sig/generated/riffer/messages/user.rbs
-- sig/generated/riffer/metrics.rbs
-- sig/generated/riffer/metrics/instruments.rbs
-- sig/generated/riffer/metrics/no_op.rbs
-- sig/generated/riffer/metrics/otel.rbs
 - sig/generated/riffer/params.rbs
 - sig/generated/riffer/params/boolean.rbs
 - sig/generated/riffer/params/param.rbs
@@ -532,8 +523,6 @@ files:
 - sig/manual/riffer/mcp/authenticated_tool.rbs
 - sig/manual/riffer/mcp/registry.rbs
 - sig/manual/riffer/mcp/tool_factory.rbs
-- sig/manual/riffer/metrics.rbs
-- sig/manual/riffer/metrics/no_op.rbs
 - sig/manual/riffer/providers.rbs
 - sig/manual/riffer/providers/repository.rbs
 - sig/manual/riffer/tracing.rbs

data/docs/17_METRICS.md

@@ -1,155 +0,0 @@
-# Metrics
-
-Riffer can record [OpenTelemetry](https://opentelemetry.io/) metric instruments alongside its [spans](16_TRACING.md), following the [GenAI semantic conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/). Metric names, instrument types, units, and attributes are a public, versioned contract you can build dashboards and alerts against. This page is the reference for that contract.
-
-As with tracing, Riffer only _records_ instruments, and only through a backend you assign to `config.metrics.backend` — OpenTelemetry is the built-in option you opt into (the host application owns the SDK, metric reader, exporter, and aggregation — the standard OTEL split), but never a default. With no backend assigned, every measurement is a silent no-op and Riffer carries no OpenTelemetry gem dependency.
-
-> **OpenTelemetry metrics for Ruby is still pre-1.0.** The metrics API and SDK ship as separate, experimental gems (`opentelemetry-metrics-api`, `opentelemetry-metrics-sdk`) from the stable 1.x traces API. Riffer guards against an incompatible API and falls back to a no-op outside the supported range, but expect the host-side wiring below to evolve with those gems.
-
-## Enabling metrics
-
-Riffer records measurements only through a backend you assign to `config.metrics.backend` — it does **not** auto-detect OpenTelemetry. To use OTEL, add the metrics SDK, register a metric reader with an exporter, and assign Riffer's built-in OTEL backend with `Riffer::Metrics::Otel.build`.
-
-```ruby
-# Gemfile
-gem "opentelemetry-metrics-sdk"
-```
-
-```ruby
-require "opentelemetry-metrics-sdk"
-
-OpenTelemetry::SDK.configure do |c|
-  c.service_name = "my-agent-host"
-end
-
-Riffer.configure do |config|
-  config.metrics.backend = Riffer::Metrics::Otel.build
-end
-```
-
-The metrics SDK is **separate** from the traces SDK (`opentelemetry-sdk`); add it explicitly even if you already trace. `Riffer::Metrics::Otel.build` wraps the global `OpenTelemetry.meter_provider` by default; pass `provider:` to wrap a specific one. It returns `nil` — leaving metrics a no-op rather than raising — when the `opentelemetry-metrics-api` gem is absent or outside the supported range (>= 0.2, < 1.0). Any backend implementing the OpenTelemetry Metrics API then ingests Riffer's instruments. For real reader and exporter setup (OTLP, periodic export, Views), see the [OpenTelemetry Ruby docs](https://opentelemetry.io/docs/languages/ruby/).
-
-The metrics knobs — the `enabled` kill switch and the `backend` itself — live in [Configuration — Metrics](10_CONFIGURATION.md#metrics). They are **independent** of the tracing knobs (each signal has its own backend): you can run tracing while metrics are off, or the reverse.
-
-Instruments are recorded under the instrumentation scope named `riffer`, versioned with the Riffer gem version — the runtime signal for which release produced a measurement; see [Stability](#stability).
-
-## Routing to a non-OpenTelemetry backend
-
-OpenTelemetry is one backend, not the only one. A host that already runs another metrics stack — DogStatsD, say — can route Riffer's measurements into it with **no `opentelemetry-*` gem installed** by assigning its own backend to `config.metrics.backend` in place of `Riffer::Metrics::Otel.build`. Whatever you assign is the backend; there is no fallback and no auto-detection — an unset backend is a no-op.
-
-```ruby
-Riffer.configure do |config|
-  config.metrics.backend = MyDogStatsdMetricsBackend.new
-end
-```
-
-The backend is duck-typed: any object that responds to `record_histogram(name, value, unit:, description:, attributes:)` works, and the setter validates only that (otherwise it raises `Riffer::ArgumentError`). `Riffer::Metrics::NoOp` is the reference shape. All four instruments are histograms, so the single `record_histogram` method covers the full contract; tell them apart by `name`. Two carry unit `s` — `gen_ai.client.operation.duration` and `riffer.guardrail.duration` — so `name` is the reliable discriminator; `{token}` is `gen_ai.client.token.usage` and `USD` is `riffer.gen_ai.cost`.
-
-A custom backend counts as a **live** sink, so the providers still compute the token counts and cost that feed it — the same data that, under OTEL, populates `gen_ai.client.token.usage` and `riffer.gen_ai.cost`. The `enabled` kill switch is honoured ahead of the backend: with `config.metrics.enabled = false`, measurements short-circuit to the no-op without ever reaching a custom backend.
-
-### Bucket boundaries
-
-Histogram bucket boundaries are a **host-side** concern. The OpenTelemetry metrics API does not let an instrumenting library attach bucket boundaries at instrument creation, so Riffer does not set them — the SDK's default buckets apply unless you override them. To match the GenAI semantic conventions' recommended boundaries (or your own), register a [View](https://opentelemetry.io/docs/specs/otel/metrics/sdk/#view) on the meter provider that targets the instrument by name and sets explicit bucket boundaries.
-
-The convention recommends boundaries scaled to each instrument, so register one View per histogram — the token-count buckets below are for `gen_ai.client.token.usage`; `gen_ai.client.operation.duration` wants its own latency-scaled set, and `riffer.gen_ai.cost` a USD-scaled one.
-
-```ruby
-require "opentelemetry-metrics-sdk"
-
-OpenTelemetry::SDK.configure do |c|
-  c.service_name = "my-agent-host"
-end
-
-# The GenAI semconv's recommended token-count boundaries. Register the View
-# before Riffer records its first measurement.
-OpenTelemetry.meter_provider.add_view(
-  "gen_ai.client.token.usage",
-  aggregation: OpenTelemetry::SDK::Metrics::Aggregation::ExplicitBucketHistogram.new(
-    boundaries: [1, 4, 16, 64, 256, 1024, 4096, 16384, 65536, 262144, 1048576, 4194304, 16777216, 67108864]
-  )
-)
-```
-
-## Instruments
-
-Each instrument is documented here as a row carrying its name, instrument type, unit, and attribute set.
-
-> **Per-call tags become dimensions.** Any tags passed to `#generate` / `#stream` via `tags:` are added as `riffer.tag.<key>` attributes to **every** instrument below — `operation.duration` (each operation), `token.usage` (each point), `cost`, and `guardrail.duration` — so the attribute lists omit them. Tags are promoted verbatim with no allow-list — a high-cardinality value like a unique `user_id` per request multiplies time series accordingly; drop it with a [View](https://opentelemetry.io/docs/specs/otel/metrics/sdk/#view) or keep metric-bound tags low-cardinality. See [Per-Call Tags](03_AGENTS.md#per-call-tags).
-
-### `gen_ai.client.operation.duration`
-
-Histogram, unit `s`. The latency of a single GenAI operation, recorded around the same wrap as the matching [span](16_TRACING.md) on both the success and error paths and timed with a monotonic clock. Recording is independent of tracing — the metric fires even with `config.tracing.enabled = false`. Tell the three operations apart by `gen_ai.operation.name`.
-
-| `gen_ai.operation.name` | Recorded around                                    | Attributes                                                                                                            |
-| ----------------------- | -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
-| `chat`                  | each provider call (`generate_text`/`stream_text`) | `gen_ai.operation.name`, `gen_ai.provider.name`, `gen_ai.request.model` (when set), `error.type` (on error)           |
-| `invoke_agent`          | each agent run (`generate`/`stream`)               | `gen_ai.operation.name`, `gen_ai.provider.name`, `gen_ai.request.model`, `gen_ai.agent.name`, `error.type` (on error) |
-| `execute_tool`          | each tool call                                     | `gen_ai.operation.name`, `gen_ai.tool.name`, `error.type` (on error)                                                  |
-
-`error.type` carries the exception class for a raised error; for `execute_tool` it carries the handled error category (e.g. `validation_error`, `timeout_error`) when a tool returns an error result instead of raising — matching the span. `gen_ai.response.model` is not recorded yet; it will land once it is also captured on the chat span.
-
-> **Streamed operations are consumption-paced.** A streamed `chat` or `invoke_agent` records its duration when the stream drains, so the value includes the time your consumer takes to iterate the events, not just provider latency. The matching span behaves the same way.
-
-> **`gen_ai.tool.name` cardinality.** One time series exists per distinct tool name. With a large or dynamic tool set (for example MCP-discovered tools) that can grow unbounded — drop the attribute with a [View](https://opentelemetry.io/docs/specs/otel/metrics/sdk/#view) if your backend strains.
-
-### `gen_ai.client.token.usage`
-
-Histogram, unit `{token}`. Token volume for a single `chat` call, recorded from the normalized token usage after the provider responds. Each call emits **two data points** — one `input`, one `output` — distinguished by `gen_ai.token.type`. Recording is independent of tracing (it fires with `config.tracing.enabled = false`); for a streamed call it fires when the stream drains. `gen_ai.response.model` is not recorded yet, for the same reason as `operation.duration`.
-
-| `gen_ai.token.type` | Value                                                 | Attributes                                                                                                              |
-| ------------------- | ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
-| `input`             | total prompt tokens for the call, **cache-inclusive** | `gen_ai.operation.name` (always `chat`), `gen_ai.provider.name`, `gen_ai.token.type`, `gen_ai.request.model` (when set) |
-| `output`            | tokens generated, including reasoning/thinking tokens | same                                                                                                                    |
-
-> **Per-call only.** Token usage is never recorded at the run (`invoke_agent`) level. Metrics pre-aggregate, so emitting both the per-call points and a run total would double-count — sum the per-call points in your backend if you want a run total. This is the metric-side counterpart of the span-level [double-count trap](16_TRACING.md#token-usage-and-cost).
-
-> **Cache buckets stay on spans.** The semconv `gen_ai.token.type` defines only `input` and `output`, so the prompt-cache subsets (`cache_read` / `cache_creation`) live on [spans](16_TRACING.md#token-usage-and-cost), not this metric. The `input` value is the cache-inclusive total, matching the span's `gen_ai.usage.input_tokens`.
-
-A call that reports no usage records no data points, and a failed call has nothing to count — so this metric carries no `error.type` (the semconv marks it not applicable here, unlike `operation.duration`).
-
-### `riffer.gen_ai.cost`
-
-Histogram, unit `USD`. The cost of a single `chat` call, recorded from the [cost](16_TRACING.md#token-usage-and-cost) on the normalized token usage after the provider responds — the same source as the cost span attribute, a different sink. This instrument is Riffer-owned (`riffer.*`, not `gen_ai.*`) so it won't collide if the semantic conventions later define a cost instrument; see [Stability](#stability). Recording is independent of tracing (it fires with `config.tracing.enabled = false`); for a streamed call it fires when the stream drains.
-
-| Value            | Attributes                                                                                         |
-| ---------------- | -------------------------------------------------------------------------------------------------- |
-| cost of the call | `gen_ai.operation.name` (always `chat`), `gen_ai.provider.name`, `gen_ai.request.model` (when set) |
-
-Pricing is **consumer-configured** — no price table ships with the gem (see [Configuration — Pricing](10_CONFIGURATION.md#pricing)). A call whose model has no configured price records **no** data point, so this metric covers only priced calls; `operation.duration` and `token.usage` still record. A priced call that computes to `0.0` does record a zero data point — only an absent price means there is nothing to measure.
-
-> **Per-call only.** Cost is never recorded at the run (`invoke_agent`) level, for the same reason as token usage: metrics pre-aggregate, so emitting both per-call points and a run total would double-count. Sum the per-call points in your backend for a run total.
-
-### `riffer.guardrail.duration`
-
-Histogram, unit `s`. The latency of a single guardrail execution, recorded around the same wrap as the [`execute_guardrail` span](16_TRACING.md) on both the success and raise paths and timed with a monotonic clock. Guardrails run on the request hot path — before every model turn and after every response — so this is the guardrail counterpart to `gen_ai.client.operation.duration`. Recording is independent of tracing — the metric fires even with `config.tracing.enabled = false`.
-
-This instrument is Riffer-owned (`riffer.*`, not `gen_ai.*`) by the same reasoning as its span: a guardrail is not a GenAI semantic-convention operation, so the `execute_guardrail` span deliberately carries no `gen_ai.operation.name` and lives in riffer's own `riffer.guardrail.*` namespace (see [Tracing](16_TRACING.md)). Folding the metric into `gen_ai.client.operation.duration` would contradict that, so the duration is its own riffer-owned histogram instead; see [Stability](#stability).
-
-| Value                               | Attributes                                                                 |
-| ----------------------------------- | -------------------------------------------------------------------------- |
-| duration of the guardrail execution | `riffer.guardrail.name`, `riffer.guardrail.phase`, `error.type` (on raise) |
-
-`riffer.guardrail.phase` is `before` or `after`. A pass, transform, or block is a **handled** outcome and records no `error.type` — that attribute carries the exception class only when a guardrail raises, mirroring the span. One time series exists per `riffer.guardrail.name` × `riffer.guardrail.phase`; guardrail names are bounded by the guardrails you configure, so cardinality is safe — unlike the dynamic tool names on `gen_ai.client.operation.duration`.
-
-## Stability
-
-The instrument shape is a public, versioned contract, in two tiers — mirroring the [tracing contract](16_TRACING.md#stability):
-
-- **`gen_ai.*`** tracks the OpenTelemetry GenAI semantic conventions, pinned to schema version `1.37.0`. That convention is still "Development" status upstream and its names may change; Riffer absorbs such renames deliberately in a release, never silently, with a CHANGELOG entry.
-- **`riffer.*`** is Riffer-owned and changes only through a normal version bump and CHANGELOG entry. Riffer-owned metrics live here so they won't collide if semconv later defines an equivalent.
-
-The semantic-convention schema version is a documented pin rather than an instrument attribute — the OpenTelemetry Ruby API can't attach a schema URL to a meter. The runtime version signal is the instrumentation scope: every measurement carries scope name `riffer` at the gem version that recorded it. Pin the Riffer version your dashboards depend on, and watch the CHANGELOG for metrics entries before upgrading.
-
-## Avoid double instrumentation
-
-Riffer records its agent loop's metrics natively. Running a provider-level GenAI instrumentation gem (for example an OpenTelemetry contrib instrumentation for the underlying Anthropic or OpenAI client) _alongside_ Riffer records the same `gen_ai.client.*` metrics twice. Because metrics pre-aggregate, that duplication is **silent** — it inflates counts and distorts distributions in your dashboards without any obvious per-event trace to inspect.
-
-Record one or the other, not both. Since the metrics kill switch is independent of tracing, the usual resolution is to keep Riffer's spans and turn _Riffer's metrics_ off, letting the provider-level instrumentation own the metrics:
-
-```ruby
-Riffer.configure do |config|
-  config.metrics.enabled = false
-end
-```
-
-— or disable the provider-level metric instrumentation and let Riffer own them.

data/lib/riffer/metrics/instruments.rb

@@ -1,31 +0,0 @@
-# frozen_string_literal: true
-# rbs_inline: enabled
-
-# The catalog of metric instruments riffer records. Each handle is a constant
-# that resolves its backend at record time, so it survives a meter-provider swap
-# or a runtime +enabled+ flip.
-module Riffer::Metrics::Instruments # :nodoc: all
-  OPERATION_DURATION = Riffer::Metrics.create_histogram(
-    "gen_ai.client.operation.duration",
-    unit: "s",
-    description: "Duration of GenAI client operations"
-  ) #: Riffer::Metrics::Histogram
-
-  TOKEN_USAGE = Riffer::Metrics.create_histogram(
-    "gen_ai.client.token.usage",
-    unit: "{token}",
-    description: "Number of input and output tokens used in GenAI operations"
-  ) #: Riffer::Metrics::Histogram
-
-  COST = Riffer::Metrics.create_histogram(
-    "riffer.gen_ai.cost",
-    unit: "USD",
-    description: "Cost of GenAI client operations in USD"
-  ) #: Riffer::Metrics::Histogram
-
-  GUARDRAIL_DURATION = Riffer::Metrics.create_histogram(
-    "riffer.guardrail.duration",
-    unit: "s",
-    description: "Duration of guardrail execution"
-  ) #: Riffer::Metrics::Histogram
-end

data/lib/riffer/metrics/no_op.rb

@@ -1,14 +0,0 @@
-# frozen_string_literal: true
-# rbs_inline: enabled
-
-# No-op metrics backend, used when the OpenTelemetry metrics API is unavailable
-# or metrics are disabled.
-module Riffer::Metrics::NoOp # :nodoc: all
-  extend self
-
-  # Ignores the measurement; there is no meter without the OTEL metrics API.
-  #--
-  #: (String, Numeric, unit: String?, description: String?, attributes: Hash[String, untyped]?) -> void
-  def record_histogram(name, value, unit:, description:, attributes:)
-  end
-end

data/lib/riffer/metrics/otel.rb

@@ -1,80 +0,0 @@
-# frozen_string_literal: true
-# rbs_inline: enabled
-
-# OTEL-backed metrics backend. <tt>::OpenTelemetry</tt> constants appear only
-# inside method bodies here, so the gem loads and eager-loads cleanly when the
-# OpenTelemetry metrics API is absent.
-class Riffer::Metrics::Otel # :nodoc: all
-  SUPPORTED_API_VERSIONS = Gem::Requirement.new(">= 0.2", "< 1.0") #: Gem::Requirement
-
-  class << self
-    # Builds a backend when the OpenTelemetry metrics API is loadable at a
-    # supported version; returns +nil+ so resolution falls back to NoOp.
-    # +provider+ defaults to the global <tt>OpenTelemetry.meter_provider</tt>.
-    #--
-    #: (?provider: untyped) -> Riffer::Metrics::Otel?
-    def build(provider: nil)
-      version = api_version
-      return nil unless version
-
-      unless supported?(version)
-        Kernel.warn "riffer: opentelemetry-metrics-api #{version} is outside the supported range (#{SUPPORTED_API_VERSIONS}); metrics are disabled"
-        return nil
-      end
-
-      new(provider: provider || ::OpenTelemetry.meter_provider)
-    end
-
-    # Whether the OpenTelemetry metrics API gem is loadable at a supported
-    # version.
-    #--
-    #: () -> bool
-    def available?
-      version = api_version
-      !version.nil? && supported?(version)
-    end
-
-    # Whether the given opentelemetry-metrics-api version is one riffer codes
-    # against. The gem is undeclared, so this guard is the only protection
-    # against an incompatible, still-pre-1.0 API.
-    #--
-    #: (Gem::Version) -> bool
-    def supported?(version)
-      SUPPORTED_API_VERSIONS.satisfied_by?(version)
-    end
-
-    private
-
-    #--
-    #: () -> Gem::Version?
-    def api_version
-      require "opentelemetry-metrics-api"
-      spec = Gem.loaded_specs["opentelemetry-metrics-api"] #: untyped
-      spec&.version
-    rescue ::LoadError
-      nil
-    end
-  end
-
-  # @rbs @meter: untyped
-  # @rbs @instruments: Hash[String, untyped]
-  # @rbs @mutex: Mutex
-
-  #--
-  #: (provider: untyped) -> void
-  def initialize(provider:)
-    @meter = provider.meter("riffer", version: Riffer::VERSION)
-    @instruments = {}
-    @mutex = Mutex.new
-  end
-
-  # Records a value onto the named histogram.
-  #--
-  #: (String, Numeric, unit: String?, description: String?, attributes: Hash[String, untyped]?) -> void
-  def record_histogram(name, value, unit:, description:, attributes:)
-    histogram = @mutex.synchronize do
-      @instruments[name] ||= @meter.create_histogram(name, unit: unit, description: description)
-    end
-    histogram.record(value, attributes: attributes)
-  end
-end

data/lib/riffer/metrics.rb

@@ -1,94 +0,0 @@
-# frozen_string_literal: true
-# rbs_inline: enabled
-
-# Internal metrics port — records OTEL metric instruments when the host bundles
-# the OpenTelemetry metrics API and no-ops otherwise, so riffer never declares
-# an OTEL dependency.
-module Riffer::Metrics # :nodoc: all
-  extend self
-
-  # @rbs @backend: untyped
-
-  MUTEX = Mutex.new #: Mutex
-
-  # The Ruby API cannot attach a schema URL to a meter, so the semconv pin
-  # lives here as the documented contract version.
-  SCHEMA_URL = "https://opentelemetry.io/schemas/1.37.0" #: String
-
-  # A handle to a named histogram, safe to hold as a constant: it defers backend
-  # resolution to record time, so it survives a meter-provider swap or a runtime
-  # +enabled+ flip.
-  class Histogram
-    # @rbs @name: String
-    # @rbs @unit: String?
-    # @rbs @description: String?
-
-    #--
-    #: (String, ?unit: String?, ?description: String?) -> void
-    def initialize(name, unit: nil, description: nil)
-      @name = name
-      @unit = unit
-      @description = description
-    end
-
-    #--
-    #: (Numeric, ?attributes: Hash[String, untyped]?) -> void
-    def record(value, attributes: nil)
-      Riffer::Metrics.record_histogram(@name, value, unit: @unit, description: @description, attributes: attributes)
-    end
-  end
-
-  # Returns a handle to the named histogram.
-  #--
-  #: (String, ?unit: String?, ?description: String?) -> Riffer::Metrics::Histogram
-  def create_histogram(name, unit: nil, description: nil)
-    Histogram.new(name, unit: unit, description: description)
-  end
-
-  # Records a value onto the named histogram.
-  #--
-  #: (String, Numeric, ?unit: String?, ?description: String?, ?attributes: Hash[String, untyped]?) -> void
-  def record_histogram(name, value, unit: nil, description: nil, attributes: nil)
-    return unless Riffer.config.metrics.enabled
-    backend.record_histogram(name, value, unit: unit, description: description, attributes: attributes)
-  end
-
-  # Mirrors a span's +recording?+ so a caller can skip work that exists only to
-  # feed a metric. True for any live backend — the OTEL backend or a
-  # consumer-supplied one — so a custom metrics sink still gets fed.
-  #--
-  #: () -> bool
-  def recording?
-    Riffer.config.metrics.enabled && !backend.equal?(NoOp)
-  end
-
-  # Reads the monotonic clock in seconds — the time source for duration metrics,
-  # immune to wall-clock adjustments.
-  #--
-  #: () -> Float
-  def monotonic_now
-    Process.clock_gettime(Process::CLOCK_MONOTONIC)
-  end
-
-  # Discards the resolved backend so the next record re-resolves it; cached
-  # instruments live on that backend, so this clears them too.
-  #--
-  #: () -> void
-  def reset!
-    MUTEX.synchronize { @backend = nil }
-  end
-
-  private
-
-  #--
-  #: () -> untyped
-  def backend
-    @backend || MUTEX.synchronize { @backend ||= resolve_backend }
-  end
-
-  #--
-  #: () -> untyped
-  def resolve_backend
-    Riffer.config.metrics.backend || NoOp
-  end
-end

data/sig/generated/riffer/metrics/instruments.rbs

@@ -1,15 +0,0 @@
-# Generated from lib/riffer/metrics/instruments.rb with RBS::Inline
-
-# The catalog of metric instruments riffer records. Each handle is a constant
-# that resolves its backend at record time, so it survives a meter-provider swap
-# or a runtime +enabled+ flip.
-module Riffer::Metrics::Instruments
-  # :nodoc: all
-  OPERATION_DURATION: Riffer::Metrics::Histogram
-
-  TOKEN_USAGE: Riffer::Metrics::Histogram
-
-  COST: Riffer::Metrics::Histogram
-
-  GUARDRAIL_DURATION: Riffer::Metrics::Histogram
-end

data/sig/generated/riffer/metrics/no_op.rbs

@@ -1,10 +0,0 @@
-# Generated from lib/riffer/metrics/no_op.rb with RBS::Inline
-
-# No-op metrics backend, used when the OpenTelemetry metrics API is unavailable
-# or metrics are disabled.
-module Riffer::Metrics::NoOp
-  # Ignores the measurement; there is no meter without the OTEL metrics API.
-  # --
-  # : (String, Numeric, unit: String?, description: String?, attributes: Hash[String, untyped]?) -> void
-  def record_histogram: (String, Numeric, unit: String?, description: String?, attributes: Hash[String, untyped]?) -> void
-end

data/sig/generated/riffer/metrics/otel.rbs

@@ -1,48 +0,0 @@
-# Generated from lib/riffer/metrics/otel.rb with RBS::Inline
-
-# OTEL-backed metrics backend. <tt>::OpenTelemetry</tt> constants appear only
-# inside method bodies here, so the gem loads and eager-loads cleanly when the
-# OpenTelemetry metrics API is absent.
-class Riffer::Metrics::Otel
-  # :nodoc: all
-  SUPPORTED_API_VERSIONS: Gem::Requirement
-
-  # Builds a backend when the OpenTelemetry metrics API is loadable at a
-  # supported version; returns +nil+ so resolution falls back to NoOp.
-  # +provider+ defaults to the global <tt>OpenTelemetry.meter_provider</tt>.
-  # --
-  # : (?provider: untyped) -> Riffer::Metrics::Otel?
-  def self.build: (?provider: untyped) -> Riffer::Metrics::Otel?
-
-  # Whether the OpenTelemetry metrics API gem is loadable at a supported
-  # version.
-  # --
-  # : () -> bool
-  def self.available?: () -> bool
-
-  # Whether the given opentelemetry-metrics-api version is one riffer codes
-  # against. The gem is undeclared, so this guard is the only protection
-  # against an incompatible, still-pre-1.0 API.
-  # --
-  # : (Gem::Version) -> bool
-  def self.supported?: (Gem::Version) -> bool
-
-  # --
-  # : () -> Gem::Version?
-  private def self.api_version: () -> Gem::Version?
-
-  @meter: untyped
-
-  @instruments: Hash[String, untyped]
-
-  @mutex: Mutex
-
-  # --
-  # : (provider: untyped) -> void
-  def initialize: (provider: untyped) -> void
-
-  # Records a value onto the named histogram.
-  # --
-  # : (String, Numeric, unit: String?, description: String?, attributes: Hash[String, untyped]?) -> void
-  def record_histogram: (String, Numeric, unit: String?, description: String?, attributes: Hash[String, untyped]?) -> void
-end