riffer 0.35.0 → 0.37.0

data/sig/_private/opentelemetry.rbs

@@ -1,13 +1,10 @@
-# Minimal signatures for the `opentelemetry-api` and `opentelemetry-metrics-api`
-# gems (undeclared, runtime detected), which ship no RBS.
+# Minimal signatures for the `opentelemetry-api` gem (undeclared, runtime
+# detected), which ships no RBS.
 #
-# Only the surface used by Riffer::Tracing::Otel and Riffer::Metrics::Otel is
-# declared.
+# Only the surface used by Riffer::Tracing::Otel is declared.
 module OpenTelemetry
   def self.tracer_provider: () -> untyped
 
-  def self.meter_provider: () -> untyped
-
   class Context
     def self.current: () -> OpenTelemetry::Context
 

data/sig/generated/riffer/agent/run.rbs

@@ -21,8 +21,8 @@ module Riffer::Agent::Run
 
   # Both +generate+ and +stream+ funnel here, so this is the single place raw
   # +tags+ are normalized. The clean <tt>String => String</tt> map is then
-  # threaded to every span/metric builder in the run as +riffer.tag.*+ and to
-  # each provider call (via +merged_model_options+) for native request-metadata
+  # threaded to every span builder in the run as +riffer.tag.*+ and to each
+  # provider call (via +merged_model_options+) for native request-metadata
   # mapping.
   # --
   # : (Riffer::Agent, ?tags: Hash[(String | Symbol), untyped]?, ?stream_yielder: Enumerator::Yielder?) -> Riffer::Agent::Response
@@ -86,8 +86,8 @@ module Riffer::Agent::Run
 
   # +tags+ rides in the options hash as a curated key the providers extract for
   # native request-metadata mapping (alongside +:structured_output+); it never
-  # reaches an SDK call verbatim. Span/metric tagging is threaded separately to
-  # each builder.
+  # reaches an SDK call verbatim. Span tagging is threaded separately to each
+  # builder.
   # --
   # : (Riffer::Agent, ?Hash[String, String]) -> Hash[Symbol, untyped]
   def merged_model_options: (Riffer::Agent, ?Hash[String, String]) -> Hash[Symbol, untyped]
@@ -114,10 +114,6 @@ module Riffer::Agent::Run
   # : (Riffer::Agent, ?Hash[String, String]) -> Hash[String, untyped]
   def run_span_attributes: (Riffer::Agent, ?Hash[String, String]) -> Hash[String, untyped]
 
-  # --
-  # : (Riffer::Agent, String?, ?Hash[String, String]) -> Hash[String, untyped]
-  def run_metric_attributes: (Riffer::Agent, String?, ?Hash[String, String]) -> Hash[String, untyped]
-
   # --
   # : (Hash[(String | Symbol), untyped]?) -> Hash[String, String]
   def normalize_tags: (Hash[String | Symbol, untyped]?) -> Hash[String, String]

data/sig/generated/riffer/agent.rbs

@@ -215,7 +215,7 @@ class Riffer::Agent
   #
   # +tags:+ is an optional flat hash of attribution tags applied to this single
   # call: they propagate to the provider's native request-metadata field, and
-  # are stamped as +riffer.tag.*+ on every span and metric the call emits. See
+  # are stamped as +riffer.tag.*+ on every span the call emits. See
   # +docs/03_AGENTS.md+ for the per-provider mapping. The reserved key
   # +user_id+ also maps to the provider's native user identifier where one
   # exists.

data/sig/generated/riffer/config.rbs

@@ -137,36 +137,6 @@ class Riffer::Config
     def backend=: (untyped) -> void
   end
 
-  # Metrics-related global configuration, independent of +config.tracing+ so a
-  # host can run one signal without the other.
-  class Metrics
-    # Whether riffer records OTEL metric instruments; defaults to +true+, a
-    # no-op until a host wires an OTEL metrics SDK.
-    attr_reader enabled: bool
-
-    # The backend riffer routes measurements through; defaults to +nil+, a no-op.
-    # Riffer auto-detects no backend; assigning one is opt-in.
-    attr_reader backend: untyped
-
-    # --
-    # : () -> void
-    def initialize: () -> void
-
-    # Sets the enabled flag, coercing boolean-ish values so an env-var
-    # +"false"+ (truthy in Ruby) doesn't silently keep metrics on. Raises
-    # Riffer::ArgumentError on an unrecognized value.
-    # --
-    # : (untyped) -> void
-    def enabled=: (untyped) -> void
-
-    # Sets the metrics backend riffer routes measurements through. Raises
-    # Riffer::ArgumentError unless the value is +nil+ or responds to
-    # +record_histogram+.
-    # --
-    # : (untyped) -> void
-    def backend=: (untyped) -> void
-  end
-
   # Consumer-configured token pricing, keyed by +provider/model+ id. Riffer
   # ships no price table, so an unconfigured model carries no cost.
   class Pricing
@@ -276,9 +246,6 @@ class Riffer::Config
   # Tracing-related global configuration.
   attr_reader tracing: Riffer::Config::Tracing
 
-  # Metrics-related global configuration.
-  attr_reader metrics: Riffer::Config::Metrics
-
   # Consumer-configured per-model token pricing.
   attr_reader pricing: Riffer::Config::Pricing
 

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/providers/repository.rbs

@@ -1,12 +1,34 @@
 # Generated from lib/riffer/providers/repository.rb with RBS::Inline
 
-# Registry for finding provider classes by identifier.
+# Resolves provider classes by identifier, combining the built-in REPO with
+# consumer registrations added through +register+. Registration is not
+# synchronized — register during boot, before concurrent generation begins.
 module Riffer::Providers::Repository
+  @registrations: Hash[Symbol, ^() -> singleton(Riffer::Providers::Base)]
+
   @key_for: Hash[singleton(Riffer::Providers::Base), Symbol]?
 
   REPO: Hash[Symbol, ^() -> singleton(Riffer::Providers::Base)]
 
-  # Finds a provider class by identifier.
+  # Registers a custom provider under +identifier+, resolved lazily by the block.
+  # Takes precedence over a built-in sharing the identifier.
+  #
+  #   Riffer::Providers::Repository.register(:jane) { MyApp::JaneProvider }
+  #
+  # Raises Riffer::ArgumentError when called without a block.
+  #
+  # --
+  # : ((String | Symbol)) { () -> singleton(Riffer::Providers::Base) } -> void
+  def register: (String | Symbol) { () -> singleton(Riffer::Providers::Base) } -> void
+
+  # Removes a custom registration by identifier, leaving any built-in of the
+  # same name intact.
+  # --
+  # : ((String | Symbol)) -> void
+  def unregister: (String | Symbol) -> void
+
+  # Finds a provider class by identifier, preferring a custom registration over
+  # a built-in of the same name.
   #
   # --
   # : ((String | Symbol)) -> singleton(Riffer::Providers::Base)?
@@ -16,4 +38,10 @@ module Riffer::Providers::Repository
   # --
   # : (singleton(Riffer::Providers::Base)) -> Symbol?
   def key_for: (singleton(Riffer::Providers::Base)) -> Symbol?
+
+  private
+
+  # --
+  # : () -> Hash[singleton(Riffer::Providers::Base), Symbol]
+  def build_key_index: () -> Hash[singleton(Riffer::Providers::Base), Symbol]
 end

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.37.0
 platform: ruby
 authors:
 - Jake Bottrall
@@ -35,14 +35,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.49.0
+        version: 1.55.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.49.0
+        version: 1.55.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.43'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -118,21 +118,21 @@ dependencies:
         version: '2.25'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '2.40'
+        version: '2.43'
 - !ruby/object:Gem::Dependency
   name: io-event
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "<"
       - !ruby/object:Gem::Version
-        version: '1.17'
+        version: '1.20'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "<"
       - !ruby/object:Gem::Version
-        version: '1.17'
+        version: '1.20'
 - !ruby/object:Gem::Dependency
   name: minitest
   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