riffer 0.33.0 → 0.34.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e72e36f6d29b3a2387246615224e19becb1d157e4a2327f8229ee481f3704e7e
-  data.tar.gz: 89deb58a1ec3a5f0af904d86b38057a2d7bf301490deeadf492bbe11942d0e96
+  metadata.gz: bc442fb9eb0296a5a9c6f289c1c9e63e7cdb732ef52b013e1556d1765a874f2d
+  data.tar.gz: aa7512f0b3ac38e4f0c7be500095c73fca0ae1740c37370ceb2aeaf57349dac8
 SHA512:
-  metadata.gz: 11fadbbfd249ce864885709684c51801d3ec2aeba83a3f750ee7afdb390750798d9598df69796bf047afa4c4b4e7136cfc7cff0edf851a0a8d945bb9f8549204
-  data.tar.gz: 60b6c3b2c8e7201cdfb6822709531640b501f4218e63fc2768349c9509b67ba286299fc00372a0c019b07a01390f4a7e77c5a4382e7ffe21ed7cfd250acb67b9
+  metadata.gz: d9ace157326fa9ebfb356705f14cd4a8bac4af86e3ede2eb142adb4be36870399c81ee122fa02973135c9176b521bdee980745e3cc3f14422e12fbf1392fb009
+  data.tar.gz: cdc2e19b1aab77a93fb6ad7c4a800c5002a5efb63667366113fc04104a05c342863a1fa74219ed2569759f5f7be08dc534ac7c79b10c6d9ab61d6430db805113

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.33.0"
+  ".": "0.34.0"
 }

data/CHANGELOG.md

@@ -5,6 +5,18 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.34.0](https://github.com/janeapp/riffer/compare/riffer/v0.33.0...riffer/v0.34.0) (2026-06-22)
+
+
+### ⚠ BREAKING CHANGES
+
+* **telemetry:** `config.tracing.tracer_provider` and `config.metrics.meter_provider` are removed. Assign the OTEL backend instead: `config.tracing.backend = Riffer::Tracing::Otel.build` (pass `provider:` to override the global provider).
+
+### Features
+
+* emit a riffer.guardrail.duration metric for guardrail execution ([#338](https://github.com/janeapp/riffer/issues/338)) ([7b0dfb0](https://github.com/janeapp/riffer/commit/7b0dfb014f710d839e53d25ee345df5b404c8c60))
+* **telemetry:** pluggable tracing/metrics backend (OTEL opt-in) ([#329](https://github.com/janeapp/riffer/issues/329)) ([d647f54](https://github.com/janeapp/riffer/commit/d647f54b814bb8e331b89811c2ed661d6534b20c))
+
 ## [0.33.0](https://github.com/janeapp/riffer/compare/riffer/v0.32.1...riffer/v0.33.0) (2026-06-18)
 
 

data/docs/10_CONFIGURATION.md

@@ -103,38 +103,38 @@ Accepts a `Riffer::Skills::Backend` instance or a `Proc` that receives `context`
 
 ### Tracing
 
-Tracing-related global configuration lives under `config.tracing`. Riffer detects the OpenTelemetry API at runtime — without it (or without a host-configured OTEL SDK) every span is a silent no-op, and riffer carries no OTEL gem dependency either way.
+Tracing-related global configuration lives under `config.tracing`. Riffer emits spans only through the backend you assign to `config.tracing.backend` — there is **no auto-detection**. OpenTelemetry is a built-in backend you opt into explicitly with `Riffer::Tracing::Otel.build`; with no backend set every span is a silent no-op, and riffer carries no OTEL gem dependency either way.
 
 ```ruby
 Riffer.configure do |config|
   config.tracing.enabled = ENV.fetch("RIFFER_TRACING_ENABLED", "true")
+  # Opt into OpenTelemetry (uses the global tracer provider):
+  config.tracing.backend = Riffer::Tracing::Otel.build
 end
 ```
 
-| Option             | Description                                                                                                                                                                                                                                                                                                                                                                                                                                       |
-| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `enabled`          | The kill switch, consulted on every span — flipping it at runtime takes effect immediately. Accepts booleans or `'true'`/`'false'`/`'1'`/`'0'`. Defaults to `true`.                                                                                                                                                                                                                                                                               |
-| `capture_messages` | Opt-in capture of full message content on LLM-call spans (`gen_ai.input.messages`, `gen_ai.output.messages`, `gen_ai.system_instructions`) as GenAI-semconv JSON. Defaults to `false` — message content routinely carries sensitive data. File attachments serialize as metadata-only stubs (media type and name, never bytes), and riffer applies no size limit of its own — cap oversized attributes with the OTEL SDK attribute length limits. |
-| `tracer_provider`  | Explicit OTEL tracer provider (e.g. the SDK's in-memory provider in tests). Defaults to `nil`, which resolves the global `OpenTelemetry.tracer_provider` lazily at first span. Raises `Riffer::ArgumentError` if the `opentelemetry-api` gem isn't available at a supported version (>= 1.1, < 2).                                                                                                                                                |
-
-Hosts own SDK and exporter wiring — riffer only emits spans through whatever provider the host configures. See [Tracing](16_TRACING.md) for the emitted span contract — names, attributes, hierarchy, and host wiring.
+| Option             | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `enabled`          | The kill switch, consulted on every span — flipping it at runtime takes effect immediately, short-circuiting to a no-op ahead of the backend. Accepts booleans or `'true'`/`'false'`/`'1'`/`'0'`. Defaults to `true`.                                                                                                                                                                                                                                                                                                                                              |
+| `capture_messages` | Opt-in capture of full message content on LLM-call spans (`gen_ai.input.messages`, `gen_ai.output.messages`, `gen_ai.system_instructions`) as GenAI-semconv JSON. Defaults to `false` — message content routinely carries sensitive data. File attachments serialize as metadata-only stubs (media type and name, never bytes), and riffer applies no size limit of its own — cap oversized attributes with the OTEL SDK attribute length limits.                                                                                                                  |
+| `backend`          | The backend riffer routes spans through. Assign `Riffer::Tracing::Otel.build` (pass `provider:` to override the global tracer provider — e.g. an in-memory provider in tests), or any object satisfying the duck-typed contract (`in_span` / `current_context` / `with_context`) to route into a non-OTEL system (e.g. Datadog APM). Defaults to `nil` — a no-op. Raises `Riffer::ArgumentError` unless the value is `nil` or responds to `in_span`. See [Tracing → Routing to a non-OpenTelemetry backend](16_TRACING.md#routing-to-a-non-opentelemetry-backend). |
 
 ### Metrics
 
-Metrics-related global configuration lives under `config.metrics`, **independent** of `config.tracing` — each has its own kill switch, so you can run one signal without the other. Riffer detects the OpenTelemetry metrics API at runtime — without it (or without a host-configured OTEL metrics SDK) every measurement is a silent no-op, and riffer carries no OTEL gem dependency either way. The metrics API and SDK are separate, still-experimental (pre-1.0) gems from the traces API.
+Metrics-related global configuration lives under `config.metrics`, **independent** of `config.tracing` — each has its own kill switch and its own backend, so you can run one signal without the other. Riffer records measurements only through the backend you assign to `config.metrics.backend` — there is **no auto-detection**. OpenTelemetry is a built-in backend you opt into explicitly with `Riffer::Metrics::Otel.build`; with no backend set every measurement is a silent no-op, and riffer carries no OTEL gem dependency either way. The metrics API and SDK are separate, still-experimental (pre-1.0) gems from the traces API.
 
 ```ruby
 Riffer.configure do |config|
   config.metrics.enabled = ENV.fetch("RIFFER_METRICS_ENABLED", "true")
+  # Opt into OpenTelemetry (uses the global meter provider):
+  config.metrics.backend = Riffer::Metrics::Otel.build
 end
 ```
 
-| Option           | Description                                                                                                                                                                                                                                                                                                  |
-| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `enabled`        | The kill switch, consulted on every measurement — flipping it at runtime takes effect immediately. Accepts booleans or `'true'`/`'false'`/`'1'`/`'0'`. Defaults to `true`.                                                                                                                                   |
-| `meter_provider` | Explicit OTEL meter provider (e.g. the SDK's in-memory provider in tests). Defaults to `nil`, which resolves the global `OpenTelemetry.meter_provider` lazily at first record. Raises `Riffer::ArgumentError` if the `opentelemetry-metrics-api` gem isn't available at a supported version (>= 0.2, < 1.0). |
-
-Hosts own SDK, reader, exporter, and aggregation wiring — riffer only records instruments through whatever provider the host configures, and histogram bucket boundaries are set host-side via Views. See [Metrics](17_METRICS.md) for the instrument contract — names, units, attributes, and host wiring.
+| Option    | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `enabled` | The kill switch, consulted on every measurement — flipping it at runtime takes effect immediately, short-circuiting to a no-op ahead of the backend. Accepts booleans or `'true'`/`'false'`/`'1'`/`'0'`. Defaults to `true`.                                                                                                                                                                                                                                                                                                 |
+| `backend` | The backend riffer routes measurements through. Assign `Riffer::Metrics::Otel.build` (pass `provider:` to override the global meter provider — e.g. an in-memory provider in tests), or any object responding to `record_histogram` to route into a non-OTEL system (e.g. DogStatsD). Defaults to `nil` — a no-op. Raises `Riffer::ArgumentError` unless the value is `nil` or responds to `record_histogram`. See [Metrics → Routing to a non-OpenTelemetry backend](17_METRICS.md#routing-to-a-non-opentelemetry-backend). |
 
 ### Pricing
 

data/docs/16_TRACING.md

@@ -2,11 +2,11 @@
 
 Riffer instruments its agent loop with [OpenTelemetry](https://opentelemetry.io/) spans, following the [GenAI semantic conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/). The emitted span shape — names, attributes, and hierarchy — is a public, versioned contract you can build dashboards, alerts, and cost reporting against. This page is the reference for that contract.
 
-Riffer only _emits_ spans. The host application owns the OpenTelemetry SDK, the exporter, sampling, and service naming — the standard OTEL split. Without a host SDK, every span is a silent no-op and Riffer carries no OpenTelemetry gem dependency.
+Riffer only _emits_ spans, and only through a backend you assign to `config.tracing.backend` — OpenTelemetry is the built-in option you opt into (the host application owns the SDK, exporter, sampling, and service naming — the standard OTEL split), but never a default. With no backend assigned, every span is a silent no-op and Riffer carries no OpenTelemetry gem dependency.
 
 ## Enabling tracing
 
-Add the OpenTelemetry SDK to your host application and configure an exporter. Riffer detects the API at runtime and starts emitting through whatever provider the SDK configures — there is nothing to switch on in Riffer beyond the SDK being present.
+Riffer emits spans only through a backend you assign to `config.tracing.backend` — it does **not** auto-detect OpenTelemetry. To use OTEL, add the SDK, configure an exporter, and assign Riffer's built-in OTEL backend with `Riffer::Tracing::Otel.build`.
 
 ```ruby
 # Gemfile
@@ -19,8 +19,14 @@ require "opentelemetry/sdk"
 OpenTelemetry::SDK.configure do |c|
   c.service_name = "my-agent-host"
 end
+
+Riffer.configure do |config|
+  config.tracing.backend = Riffer::Tracing::Otel.build
+end
 ```
 
+`Riffer::Tracing::Otel.build` wraps the global `OpenTelemetry.tracer_provider` by default; pass `provider:` to wrap a specific one (an in-memory provider in tests, say). It returns `nil` — leaving tracing a no-op rather than raising — when the `opentelemetry-api` gem is absent or outside the supported range (>= 1.1, < 2), so the same configuration is safe on a host that doesn't bundle OTEL.
+
 To see Riffer's spans on stdout while developing locally, wire in the console exporter:
 
 ```ruby
@@ -36,12 +42,30 @@ OpenTelemetry::SDK.configure do |c|
 end
 ```
 
-Any backend that implements the OpenTelemetry Traces API ingests Riffer's spans with no second pipeline — including the `datadog` gem (`require "datadog/opentelemetry"`), which routes them through an existing tracer so they nest inside the host's live trace. For real exporter and collector setup (OTLP, sampling, resource attributes), see the [OpenTelemetry Ruby docs](https://opentelemetry.io/docs/languages/ruby/).
+Any backend that implements the OpenTelemetry Traces API then ingests Riffer's spans with no second pipeline. For real exporter and collector setup (OTLP, sampling, resource attributes), see the [OpenTelemetry Ruby docs](https://opentelemetry.io/docs/languages/ruby/). A host on a non-OTEL stack (e.g. Datadog APM) assigns its own backend instead — see [Routing to a non-OpenTelemetry backend](#routing-to-a-non-opentelemetry-backend).
 
-The three tracing knobs — the `enabled` kill switch, opt-in message-content capture, and an explicit tracer provider for tests — live in [Configuration — Tracing](10_CONFIGURATION.md#tracing).
+The tracing knobs — the `enabled` kill switch, opt-in message-content capture, and the `backend` itself — live in [Configuration — Tracing](10_CONFIGURATION.md#tracing).
 
 Spans are emitted under the instrumentation scope named `riffer`, versioned with the Riffer gem version. That scope version is the runtime signal for which release produced a span; see [Stability](#stability).
 
+## Routing to a non-OpenTelemetry backend
+
+OpenTelemetry is one backend, not the only one. A host already invested in another stack — Datadog APM, say — can route Riffer's spans into it with **no `opentelemetry-*` gem installed** by assigning its own backend to `config.tracing.backend` in place of `Riffer::Tracing::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.tracing.backend = MyDatadogTracingBackend.new
+end
+```
+
+The backend is duck-typed — any object satisfying the contract works, and the setter validates only that it responds to `in_span` (otherwise it raises `Riffer::ArgumentError`). It must respond to:
+
+- `in_span(name, attributes:, kind:) { |span| … }` — open a span around the block, yield a span object, and return the block's value.
+- `current_context` — return the active trace context (for re-attaching across fiber/thread boundaries), or `nil` when there is none.
+- `with_context(context) { … }` — run the block with the given context active; a `nil` context passes straight through, so a span re-attached while tracing was dark stays harmless.
+
+The yielded span must respond to `set_attribute(key, value)`, `add_event(name, attributes:)`, `record_exception(exception)`, `error!(description)`, and `recording?` — the same surface the OTEL span exposes. `Riffer::Tracing::NoOp` is the reference shape for both the backend and the span contract. The `enabled` kill switch is still honoured ahead of the backend: with `config.tracing.enabled = false`, spans short-circuit to the no-op without ever reaching a custom backend.
+
 ## Spans
 
 Riffer emits four span types. A single agent run produces one `invoke_agent` span wrapping one `chat` span per model call, one `execute_tool` span per tool call, and one `execute_guardrail` span per guardrail execution, interleaved in execution order:

data/docs/17_METRICS.md

@@ -2,13 +2,13 @@
 
 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. The host application owns the OpenTelemetry SDK, the metric reader, the exporter, and the aggregation — the standard OTEL split. Without a host SDK, every measurement is a silent no-op and Riffer carries no OpenTelemetry gem dependency.
+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
 
-Add the OpenTelemetry metrics SDK to your host application and register a metric reader with an exporter. Riffer detects the metrics API at runtime and starts recording through whatever meter provider the SDK configures.
+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
@@ -21,14 +21,32 @@ 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. Any backend implementing the OpenTelemetry Metrics API 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 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 two metrics knobs — the `enabled` kill switch and an explicit meter provider for tests — live in [Configuration — Metrics](10_CONFIGURATION.md#metrics). They are **independent** of the tracing knobs: you can run tracing while metrics are off, or the reverse.
+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.
@@ -99,6 +117,18 @@ Pricing is **consumer-configured** — no price table ships with the gem (see [C
 
 > **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):

data/lib/riffer/agent/run.rb

@@ -353,7 +353,7 @@ module Riffer::Agent::Run
   end
 
   #--
-  #: (Riffer::Tracing::Otel::Span | Riffer::Tracing::Null::Span, Riffer::Agent::Response) -> void
+  #: (Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span, Riffer::Agent::Response) -> void
   def record_run_outcome(span, response)
     span.set_attribute("riffer.steps", response.steps)
     Riffer::Tracing.record_usage(span, response.token_usage)

data/lib/riffer/config.rb

@@ -61,16 +61,16 @@ class Riffer::Config
     # content routinely carries sensitive data.
     attr_reader :capture_messages #: bool
 
-    # Explicit OTEL tracer provider; defaults to +nil+, which resolves the
-    # global <tt>OpenTelemetry.tracer_provider</tt> at first span.
-    attr_reader :tracer_provider #: untyped
+    # The backend riffer routes spans through; defaults to +nil+, a no-op.
+    # Riffer auto-detects no backend; assigning one is opt-in.
+    attr_reader :backend #: untyped
 
     #--
     #: () -> void
     def initialize
       @enabled = true
       @capture_messages = false
-      @tracer_provider = nil
+      @backend = nil
     end
 
     # Sets the enabled flag, coercing boolean-ish values so an env-var
@@ -91,17 +91,17 @@ class Riffer::Config
       @capture_messages = Riffer::Helpers::Boolean.coerce(value, attribute: "capture_messages")
     end
 
-    # Sets an explicit tracer provider, forcing the OTEL backend. Raises
-    # Riffer::ArgumentError when the OpenTelemetry API gem isn't available
-    # at a supported version.
+    # Sets the tracing backend riffer routes spans through. Raises
+    # Riffer::ArgumentError unless the value is +nil+ or responds to the full
+    # delegated contract: +in_span+, +current_context+, and +with_context+.
     #--
     #: (untyped) -> void
-    def tracer_provider=(value)
-      if !value.nil? && !Riffer::Tracing::Otel.available?
-        raise Riffer::ArgumentError,
-          "tracer_provider requires the opentelemetry-api gem (#{Riffer::Tracing::Otel::SUPPORTED_API_VERSIONS})"
+    def backend=(value)
+      contract = %i[in_span current_context with_context]
+      unless value.nil? || contract.all? { |method| value.respond_to?(method) }
+        raise Riffer::ArgumentError, "tracing backend must respond to #in_span, #current_context, and #with_context"
       end
-      @tracer_provider = value
+      @backend = value
       Riffer::Tracing.reset!
     end
   end
@@ -113,15 +113,15 @@ class Riffer::Config
     # no-op until a host wires an OTEL metrics SDK.
     attr_reader :enabled #: bool
 
-    # Explicit OTEL meter provider; defaults to +nil+, which resolves the
-    # global <tt>OpenTelemetry.meter_provider</tt> at first record.
-    attr_reader :meter_provider #: untyped
+    # 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
       @enabled = true
-      @meter_provider = nil
+      @backend = nil
     end
 
     # Sets the enabled flag, coercing boolean-ish values so an env-var
@@ -133,17 +133,16 @@ class Riffer::Config
       @enabled = Riffer::Helpers::Boolean.coerce(value, attribute: "enabled")
     end
 
-    # Sets an explicit meter provider, forcing the OTEL backend. Raises
-    # Riffer::ArgumentError when the OpenTelemetry metrics API gem isn't
-    # available at a supported version.
+    # Sets the metrics backend riffer routes measurements through. Raises
+    # Riffer::ArgumentError unless the value is +nil+ or responds to
+    # +record_histogram+.
     #--
     #: (untyped) -> void
-    def meter_provider=(value)
-      if !value.nil? && !Riffer::Metrics::Otel.available?
-        raise Riffer::ArgumentError,
-          "meter_provider requires the opentelemetry-metrics-api gem (#{Riffer::Metrics::Otel::SUPPORTED_API_VERSIONS})"
+    def backend=(value)
+      unless value.nil? || value.respond_to?(:record_histogram)
+        raise Riffer::ArgumentError, "metrics backend must respond to #record_histogram"
       end
-      @meter_provider = value
+      @backend = value
       Riffer::Metrics.reset!
     end
   end

data/lib/riffer/guardrails/runner.rb

@@ -81,15 +81,32 @@ class Riffer::Guardrails::Runner
   #--
   #: (Riffer::Guardrail, untyped, messages: Array[Riffer::Messages::Base]?) -> Riffer::Guardrails::Result
   def execute_guardrail(guardrail, data, messages:)
-    Riffer::Tracing.in_span("execute_guardrail #{guardrail.name}", attributes: guardrail_span_attributes(guardrail), kind: :internal) do |span|
-      result = run_guardrail_phase(guardrail, data, messages: messages)
-      record_guardrail_outcome(span, result)
-      result
+    instrument_guardrail(guardrail) do
+      Riffer::Tracing.in_span("execute_guardrail #{guardrail.name}", attributes: guardrail_span_attributes(guardrail), kind: :internal) do |span|
+        result = run_guardrail_phase(guardrail, data, messages: messages)
+        record_guardrail_outcome(span, result)
+        result
+      rescue => error
+        # The backend records the exception and error status on the re-raise;
+        # error.type is the one semconv attribute it doesn't set.
+        span.set_attribute("error.type", error.class.name)
+        raise
+      end
+    end
+  end
+
+  #--
+  #: (Riffer::Guardrail) { () -> Riffer::Guardrails::Result } -> Riffer::Guardrails::Result
+  def instrument_guardrail(guardrail)
+    start = Riffer::Metrics.monotonic_now
+    error_type = nil #: String?
+    begin
+      yield
     rescue => error
-      # The backend records the exception and error status on the re-raise;
-      # error.type is the one semconv attribute it doesn't set.
-      span.set_attribute("error.type", error.class.name)
+      error_type = error.class.name #: String?
       raise
+    ensure
+      Riffer::Metrics::Instruments::GUARDRAIL_DURATION.record(Riffer::Metrics.monotonic_now - start, attributes: guardrail_metric_attributes(guardrail, error_type))
     end
   end
 
@@ -115,10 +132,18 @@ class Riffer::Guardrails::Runner
     }
   end
 
+  #--
+  #: (Riffer::Guardrail, String?) -> Hash[String, untyped]
+  def guardrail_metric_attributes(guardrail, error_type)
+    attributes = guardrail_span_attributes(guardrail)
+    attributes["error.type"] = error_type if error_type
+    attributes
+  end
+
   # A block is a handled outcome, so its span status stays unset — an error
   # span status is reserved for a raised exception.
   #--
-  #: ((Riffer::Tracing::Otel::Span | Riffer::Tracing::Null::Span), Riffer::Guardrails::Result) -> void
+  #: ((Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span), Riffer::Guardrails::Result) -> void
   def record_guardrail_outcome(span, result)
     span.set_attribute("riffer.guardrail.action", result.type.to_s)
     span.set_attribute("riffer.tripwire.reason", result.data) if result.block?

data/lib/riffer/metrics/instruments.rb

@@ -22,4 +22,10 @@ module Riffer::Metrics::Instruments # :nodoc: all
     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/{null.rb → no_op.rb}

@@ -3,7 +3,7 @@
 
 # No-op metrics backend, used when the OpenTelemetry metrics API is unavailable
 # or metrics are disabled.
-module Riffer::Metrics::Null # :nodoc: all
+module Riffer::Metrics::NoOp # :nodoc: all
   extend self
 
   # Ignores the measurement; there is no meter without the OTEL metrics API.

data/lib/riffer/metrics/otel.rb

@@ -9,10 +9,11 @@ class Riffer::Metrics::Otel # :nodoc: all
 
   class << self
     # Builds a backend when the OpenTelemetry metrics API is loadable at a
-    # supported version; returns +nil+ so resolution falls back to Null.
+    # 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:)
+    #: (?provider: untyped) -> Riffer::Metrics::Otel?
+    def build(provider: nil)
       version = api_version
       return nil unless version
 

data/lib/riffer/metrics.rb

@@ -7,7 +7,7 @@
 module Riffer::Metrics # :nodoc: all
   extend self
 
-  # @rbs @backend: (Riffer::Metrics::Otel | singleton(Riffer::Metrics::Null))?
+  # @rbs @backend: untyped
 
   MUTEX = Mutex.new #: Mutex
 
@@ -54,11 +54,12 @@ module Riffer::Metrics # :nodoc: all
   end
 
   # Mirrors a span's +recording?+ so a caller can skip work that exists only to
-  # feed a metric.
+  # 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.is_a?(Otel)
+    Riffer.config.metrics.enabled && !backend.equal?(NoOp)
   end
 
   # Reads the monotonic clock in seconds — the time source for duration metrics,
@@ -80,14 +81,14 @@ module Riffer::Metrics # :nodoc: all
   private
 
   #--
-  #: () -> (Riffer::Metrics::Otel | singleton(Riffer::Metrics::Null))
+  #: () -> untyped
   def backend
     @backend || MUTEX.synchronize { @backend ||= resolve_backend }
   end
 
   #--
-  #: () -> (Riffer::Metrics::Otel | singleton(Riffer::Metrics::Null))
+  #: () -> untyped
   def resolve_backend
-    Otel.build(provider: Riffer.config.metrics.meter_provider) || Null
+    Riffer.config.metrics.backend || NoOp
   end
 end

data/lib/riffer/providers/base.rb

@@ -220,7 +220,7 @@ class Riffer::Providers::Base
   }.freeze #: Hash[Symbol, String]
 
   #--
-  #: [R] (String?, Array[Riffer::Messages::Base], Hash[Symbol, untyped]) { (Riffer::Tracing::Otel::Span | Riffer::Tracing::Null::Span) -> R } -> R
+  #: [R] (String?, Array[Riffer::Messages::Base], Hash[Symbol, untyped]) { (Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span) -> R } -> R
   def in_chat_span(model, messages, options)
     start = Riffer::Metrics.monotonic_now
     error_type = nil #: String?
@@ -302,7 +302,7 @@ class Riffer::Providers::Base
   end
 
   #--
-  #: ((Riffer::Tracing::Otel::Span | Riffer::Tracing::Null::Span), Symbol?, String?) -> void
+  #: ((Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span), Symbol?, String?) -> void
   def record_finish_reason(span, reason, raw)
     return unless reason
 
@@ -311,7 +311,7 @@ class Riffer::Providers::Base
   end
 
   #--
-  #: ((Riffer::Tracing::Otel::Span | Riffer::Tracing::Null::Span), Riffer::Tracing::StreamRecorder) -> void
+  #: ((Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span), Riffer::Tracing::StreamRecorder) -> void
   def record_stream_outcome(span, recorder)
     Riffer::Tracing.record_usage(span, recorder.token_usage)
     record_finish_reason(span, recorder.finish_reason, recorder.raw_finish_reason)
@@ -319,7 +319,7 @@ class Riffer::Providers::Base
   end
 
   #--
-  #: ((Riffer::Tracing::Otel::Span | Riffer::Tracing::Null::Span), Array[Riffer::Messages::Base]) -> void
+  #: ((Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span), Array[Riffer::Messages::Base]) -> void
   def capture_input(span, messages)
     return unless capture_messages?(span)
 
@@ -329,7 +329,7 @@ class Riffer::Providers::Base
   end
 
   #--
-  #: ((Riffer::Tracing::Otel::Span | Riffer::Tracing::Null::Span), content: String?, tool_calls: Array[Riffer::Messages::Assistant::ToolCall], finish_reason: Symbol?) -> void
+  #: ((Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span), content: String?, tool_calls: Array[Riffer::Messages::Assistant::ToolCall], finish_reason: Symbol?) -> void
   def capture_output(span, content:, tool_calls:, finish_reason:)
     return unless capture_messages?(span)
 
@@ -337,7 +337,7 @@ class Riffer::Providers::Base
   end
 
   #--
-  #: ((Riffer::Tracing::Otel::Span | Riffer::Tracing::Null::Span)) -> bool
+  #: ((Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span)) -> bool
   def capture_messages?(span)
     Riffer.config.tracing.capture_messages && span.recording?
   end

data/lib/riffer/tools/runtime.rb

@@ -113,7 +113,7 @@ class Riffer::Tools::Runtime
 
   # Emitted outside +around_tool_call+ so host enrichment spans nest beneath it.
   #--
-  #: [R] (Riffer::Messages::Assistant::ToolCall) { ((Riffer::Tracing::Otel::Span | Riffer::Tracing::Null::Span)) -> R } -> R
+  #: [R] (Riffer::Messages::Assistant::ToolCall) { ((Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span)) -> R } -> R
   def in_tool_span(tool_call)
     Riffer::Tracing.in_span("execute_tool #{tool_call.name}", attributes: tool_span_attributes(tool_call), kind: :internal) do |span|
       capture_tool_arguments(span, tool_call)
@@ -150,7 +150,7 @@ class Riffer::Tools::Runtime
   # A returned error Response is a handled outcome, so its status stays unset —
   # an error span status is reserved for a raised exception.
   #--
-  #: ((Riffer::Tracing::Otel::Span | Riffer::Tracing::Null::Span), Riffer::Tools::Response) -> void
+  #: ((Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span), Riffer::Tools::Response) -> void
   def record_tool_outcome(span, result)
     error_type = result.error_type
     span.set_attribute("error.type", error_type.to_s) if error_type
@@ -158,7 +158,7 @@ class Riffer::Tools::Runtime
   end
 
   #--
-  #: ((Riffer::Tracing::Otel::Span | Riffer::Tracing::Null::Span), Riffer::Messages::Assistant::ToolCall) -> void
+  #: ((Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span), Riffer::Messages::Assistant::ToolCall) -> void
   def capture_tool_arguments(span, tool_call)
     return unless capture_tool_content?(span)
 
@@ -167,7 +167,7 @@ class Riffer::Tools::Runtime
   end
 
   #--
-  #: ((Riffer::Tracing::Otel::Span | Riffer::Tracing::Null::Span), Riffer::Tools::Response) -> void
+  #: ((Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span), Riffer::Tools::Response) -> void
   def capture_tool_result(span, result)
     return unless capture_tool_content?(span)
 
@@ -175,7 +175,7 @@ class Riffer::Tools::Runtime
   end
 
   #--
-  #: ((Riffer::Tracing::Otel::Span | Riffer::Tracing::Null::Span)) -> bool
+  #: ((Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span)) -> bool
   def capture_tool_content?(span)
     Riffer.config.tracing.capture_messages && span.recording?
   end

data/lib/riffer/tracing/{null.rb → no_op.rb}

@@ -3,7 +3,7 @@
 
 # No-op tracing backend, used when OTEL is unavailable or tracing is
 # disabled.
-module Riffer::Tracing::Null # :nodoc: all
+module Riffer::Tracing::NoOp # :nodoc: all
   extend self
 
   # No-op stand-in for a span; answers <tt>recording?</tt> with +false+ so
@@ -36,11 +36,11 @@ module Riffer::Tracing::Null # :nodoc: all
     end
   end
 
-  SPAN = Span.new.freeze #: Riffer::Tracing::Null::Span
+  SPAN = Span.new.freeze #: Riffer::Tracing::NoOp::Span
 
   # Yields the no-op span, ignoring all span options.
   #--
-  #: [R] (String, **untyped) { (Riffer::Tracing::Null::Span) -> R } -> R
+  #: [R] (String, **untyped) { (Riffer::Tracing::NoOp::Span) -> R } -> R
   def in_span(_name, **)
     yield SPAN
   end

data/lib/riffer/tracing/otel.rb

@@ -52,10 +52,11 @@ class Riffer::Tracing::Otel # :nodoc: all
 
   class << self
     # Builds a backend when the OpenTelemetry API is loadable at a supported
-    # version; returns +nil+ so resolution falls back to Null.
+    # version; returns +nil+ so resolution falls back to NoOp. +provider+
+    # defaults to the global <tt>OpenTelemetry.tracer_provider</tt>.
     #--
-    #: (provider: untyped) -> Riffer::Tracing::Otel?
-    def build(provider:)
+    #: (?provider: untyped) -> Riffer::Tracing::Otel?
+    def build(provider: nil)
       version = api_version
       return nil unless version
 

data/lib/riffer/tracing.rb

@@ -7,7 +7,7 @@
 module Riffer::Tracing # :nodoc: all
   extend self
 
-  # @rbs @backend: (Riffer::Tracing::Otel | singleton(Riffer::Tracing::Null))?
+  # @rbs @backend: untyped
 
   MUTEX = Mutex.new #: Mutex
 
@@ -17,9 +17,9 @@ module Riffer::Tracing # :nodoc: all
 
   # Opens a span around the block, yielding the span.
   #--
-  #: [R] (String, ?attributes: Hash[String, untyped]?, ?kind: Symbol) { (Riffer::Tracing::Otel::Span | Riffer::Tracing::Null::Span) -> R } -> R
+  #: [R] (String, ?attributes: Hash[String, untyped]?, ?kind: Symbol) { (Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span) -> R } -> R
   def in_span(name, attributes: nil, kind: :internal, &block)
-    return Null.in_span(name, &block) unless Riffer.config.tracing.enabled
+    return NoOp.in_span(name, &block) unless Riffer.config.tracing.enabled
     backend.in_span(name, attributes: attributes, kind: kind, &block)
   end
 
@@ -28,7 +28,7 @@ module Riffer::Tracing # :nodoc: all
   #--
   #: () -> untyped
   def current_context
-    return Null.current_context unless Riffer.config.tracing.enabled
+    return NoOp.current_context unless Riffer.config.tracing.enabled
     backend.current_context
   end
 
@@ -37,14 +37,14 @@ module Riffer::Tracing # :nodoc: all
   #--
   #: [R] (untyped) { () -> R } -> R
   def with_context(context, &block)
-    return Null.with_context(context, &block) unless Riffer.config.tracing.enabled
+    return NoOp.with_context(context, &block) unless Riffer.config.tracing.enabled
     backend.with_context(context, &block)
   end
 
   # Stamps token usage onto the span — the <tt>gen_ai.usage.*</tt> counts and,
   # when the model was priced, <tt>riffer.cost</tt>.
   #--
-  #: ((Riffer::Tracing::Otel::Span | Riffer::Tracing::Null::Span), Riffer::Providers::TokenUsage?) -> void
+  #: ((Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span), Riffer::Providers::TokenUsage?) -> void
   def record_usage(span, usage)
     return unless usage
 
@@ -65,14 +65,14 @@ module Riffer::Tracing # :nodoc: all
   private
 
   #--
-  #: () -> (Riffer::Tracing::Otel | singleton(Riffer::Tracing::Null))
+  #: () -> untyped
   def backend
     @backend || MUTEX.synchronize { @backend ||= resolve_backend }
   end
 
   #--
-  #: () -> (Riffer::Tracing::Otel | singleton(Riffer::Tracing::Null))
+  #: () -> untyped
   def resolve_backend
-    Otel.build(provider: Riffer.config.tracing.tracer_provider) || Null
+    Riffer.config.tracing.backend || NoOp
   end
 end

data/lib/riffer/version.rb

@@ -2,5 +2,5 @@
 # rbs_inline: enabled
 
 module Riffer
-  VERSION = "0.33.0" #: String
+  VERSION = "0.34.0" #: String
 end

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

@@ -110,6 +110,6 @@ module Riffer::Agent::Run
   def run_metric_attributes: (Riffer::Agent, String?) -> Hash[String, untyped]
 
   # --
-  # : (Riffer::Tracing::Otel::Span | Riffer::Tracing::Null::Span, Riffer::Agent::Response) -> void
-  def record_run_outcome: (Riffer::Tracing::Otel::Span | Riffer::Tracing::Null::Span, Riffer::Agent::Response) -> void
+  # : (Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span, Riffer::Agent::Response) -> void
+  def record_run_outcome: (Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span, Riffer::Agent::Response) -> void
 end

data/sig/generated/riffer/config.rbs

@@ -107,9 +107,9 @@ class Riffer::Config
     # content routinely carries sensitive data.
     attr_reader capture_messages: bool
 
-    # Explicit OTEL tracer provider; defaults to +nil+, which resolves the
-    # global <tt>OpenTelemetry.tracer_provider</tt> at first span.
-    attr_reader tracer_provider: untyped
+    # The backend riffer routes spans through; defaults to +nil+, a no-op.
+    # Riffer auto-detects no backend; assigning one is opt-in.
+    attr_reader backend: untyped
 
     # --
     # : () -> void
@@ -129,12 +129,12 @@ class Riffer::Config
     # : (untyped) -> void
     def capture_messages=: (untyped) -> void
 
-    # Sets an explicit tracer provider, forcing the OTEL backend. Raises
-    # Riffer::ArgumentError when the OpenTelemetry API gem isn't available
-    # at a supported version.
+    # Sets the tracing backend riffer routes spans through. Raises
+    # Riffer::ArgumentError unless the value is +nil+ or responds to the full
+    # delegated contract: +in_span+, +current_context+, and +with_context+.
     # --
     # : (untyped) -> void
-    def tracer_provider=: (untyped) -> void
+    def backend=: (untyped) -> void
   end
 
   # Metrics-related global configuration, independent of +config.tracing+ so a
@@ -144,9 +144,9 @@ class Riffer::Config
     # no-op until a host wires an OTEL metrics SDK.
     attr_reader enabled: bool
 
-    # Explicit OTEL meter provider; defaults to +nil+, which resolves the
-    # global <tt>OpenTelemetry.meter_provider</tt> at first record.
-    attr_reader meter_provider: untyped
+    # 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
@@ -159,12 +159,12 @@ class Riffer::Config
     # : (untyped) -> void
     def enabled=: (untyped) -> void
 
-    # Sets an explicit meter provider, forcing the OTEL backend. Raises
-    # Riffer::ArgumentError when the OpenTelemetry metrics API gem isn't
-    # available at a supported version.
+    # Sets the metrics backend riffer routes measurements through. Raises
+    # Riffer::ArgumentError unless the value is +nil+ or responds to
+    # +record_histogram+.
     # --
     # : (untyped) -> void
-    def meter_provider=: (untyped) -> void
+    def backend=: (untyped) -> void
   end
 
   # Consumer-configured token pricing, keyed by +provider/model+ id. Riffer

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

@@ -37,6 +37,10 @@ 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
@@ -45,9 +49,13 @@ 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.
   # --
-  # : ((Riffer::Tracing::Otel::Span | Riffer::Tracing::Null::Span), Riffer::Guardrails::Result) -> void
-  def record_guardrail_outcome: (Riffer::Tracing::Otel::Span | Riffer::Tracing::Null::Span, Riffer::Guardrails::Result) -> void
+  # : ((Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span), Riffer::Guardrails::Result) -> void
+  def record_guardrail_outcome: (Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span, Riffer::Guardrails::Result) -> void
 end

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

@@ -10,4 +10,6 @@ module Riffer::Metrics::Instruments
   TOKEN_USAGE: Riffer::Metrics::Histogram
 
   COST: Riffer::Metrics::Histogram
+
+  GUARDRAIL_DURATION: Riffer::Metrics::Histogram
 end

data/sig/generated/riffer/metrics/{null.rbs → no_op.rbs}

@@ -1,8 +1,8 @@
-# Generated from lib/riffer/metrics/null.rb with RBS::Inline
+# 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::Null
+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

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

@@ -8,10 +8,11 @@ class Riffer::Metrics::Otel
   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 Null.
+  # 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?
+  # : (?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.

data/sig/generated/riffer/metrics.rbs

@@ -4,7 +4,7 @@
 # the OpenTelemetry metrics API and no-ops otherwise, so riffer never declares
 # an OTEL dependency.
 module Riffer::Metrics
-  @backend: (Riffer::Metrics::Otel | singleton(Riffer::Metrics::Null))?
+  @backend: untyped
 
   MUTEX: Mutex
 
@@ -42,7 +42,8 @@ module Riffer::Metrics
   def record_histogram: (String, Numeric, ?unit: String?, ?description: String?, ?attributes: Hash[String, untyped]?) -> void
 
   # Mirrors a span's +recording?+ so a caller can skip work that exists only to
-  # feed a metric.
+  # 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?: () -> bool
@@ -62,10 +63,10 @@ module Riffer::Metrics
   private
 
   # --
-  # : () -> (Riffer::Metrics::Otel | singleton(Riffer::Metrics::Null))
-  def backend: () -> (Riffer::Metrics::Otel | singleton(Riffer::Metrics::Null))
+  # : () -> untyped
+  def backend: () -> untyped
 
   # --
-  # : () -> (Riffer::Metrics::Otel | singleton(Riffer::Metrics::Null))
-  def resolve_backend: () -> (Riffer::Metrics::Otel | singleton(Riffer::Metrics::Null))
+  # : () -> untyped
+  def resolve_backend: () -> untyped
 end

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

@@ -91,8 +91,8 @@ class Riffer::Providers::Base
   REQUEST_PARAM_ATTRIBUTES: Hash[Symbol, String]
 
   # --
-  # : [R] (String?, Array[Riffer::Messages::Base], Hash[Symbol, untyped]) { (Riffer::Tracing::Otel::Span | Riffer::Tracing::Null::Span) -> R } -> R
-  def in_chat_span: [R] (String?, Array[Riffer::Messages::Base], Hash[Symbol, untyped]) { (Riffer::Tracing::Otel::Span | Riffer::Tracing::Null::Span) -> R } -> R
+  # : [R] (String?, Array[Riffer::Messages::Base], Hash[Symbol, untyped]) { (Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span) -> R } -> R
+  def in_chat_span: [R] (String?, Array[Riffer::Messages::Base], Hash[Symbol, untyped]) { (Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span) -> R } -> R
 
   # --
   # : (String?, Hash[Symbol, untyped]) -> Hash[String, untyped]
@@ -117,24 +117,24 @@ class Riffer::Providers::Base
   def record_cost_metric: (String?, Riffer::Providers::TokenUsage?) -> void
 
   # --
-  # : ((Riffer::Tracing::Otel::Span | Riffer::Tracing::Null::Span), Symbol?, String?) -> void
-  def record_finish_reason: (Riffer::Tracing::Otel::Span | Riffer::Tracing::Null::Span, Symbol?, 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
 
   # --
-  # : ((Riffer::Tracing::Otel::Span | Riffer::Tracing::Null::Span), Riffer::Tracing::StreamRecorder) -> void
-  def record_stream_outcome: (Riffer::Tracing::Otel::Span | Riffer::Tracing::Null::Span, Riffer::Tracing::StreamRecorder) -> void
+  # : ((Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span), Riffer::Tracing::StreamRecorder) -> void
+  def record_stream_outcome: (Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span, Riffer::Tracing::StreamRecorder) -> void
 
   # --
-  # : ((Riffer::Tracing::Otel::Span | Riffer::Tracing::Null::Span), Array[Riffer::Messages::Base]) -> void
-  def capture_input: (Riffer::Tracing::Otel::Span | Riffer::Tracing::Null::Span, Array[Riffer::Messages::Base]) -> void
+  # : ((Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span), Array[Riffer::Messages::Base]) -> void
+  def capture_input: (Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span, Array[Riffer::Messages::Base]) -> void
 
   # --
-  # : ((Riffer::Tracing::Otel::Span | Riffer::Tracing::Null::Span), content: String?, tool_calls: Array[Riffer::Messages::Assistant::ToolCall], finish_reason: Symbol?) -> void
-  def capture_output: (Riffer::Tracing::Otel::Span | Riffer::Tracing::Null::Span, content: String?, tool_calls: Array[Riffer::Messages::Assistant::ToolCall], finish_reason: Symbol?) -> void
+  # : ((Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span), content: String?, tool_calls: Array[Riffer::Messages::Assistant::ToolCall], finish_reason: Symbol?) -> void
+  def capture_output: (Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span, content: String?, tool_calls: Array[Riffer::Messages::Assistant::ToolCall], finish_reason: Symbol?) -> void
 
   # --
-  # : ((Riffer::Tracing::Otel::Span | Riffer::Tracing::Null::Span)) -> bool
-  def capture_messages?: (Riffer::Tracing::Otel::Span | Riffer::Tracing::Null::Span) -> bool
+  # : ((Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span)) -> bool
+  def capture_messages?: (Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span) -> bool
 
   # --
   # : (Riffer::Providers::_EventSink, Riffer::Providers::FinishReason?) -> void

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

@@ -49,8 +49,8 @@ class Riffer::Tools::Runtime
 
   # Emitted outside +around_tool_call+ so host enrichment spans nest beneath it.
   # --
-  # : [R] (Riffer::Messages::Assistant::ToolCall) { ((Riffer::Tracing::Otel::Span | Riffer::Tracing::Null::Span)) -> R } -> R
-  def in_tool_span: [R] (Riffer::Messages::Assistant::ToolCall) { (Riffer::Tracing::Otel::Span | Riffer::Tracing::Null::Span) -> R } -> R
+  # : [R] (Riffer::Messages::Assistant::ToolCall) { ((Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span)) -> R } -> R
+  def in_tool_span: [R] (Riffer::Messages::Assistant::ToolCall) { (Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span) -> R } -> R
 
   # --
   # : (Riffer::Messages::Assistant::ToolCall) -> Hash[String, untyped]
@@ -63,18 +63,18 @@ class Riffer::Tools::Runtime
   # A returned error Response is a handled outcome, so its status stays unset —
   # an error span status is reserved for a raised exception.
   # --
-  # : ((Riffer::Tracing::Otel::Span | Riffer::Tracing::Null::Span), Riffer::Tools::Response) -> void
-  def record_tool_outcome: (Riffer::Tracing::Otel::Span | Riffer::Tracing::Null::Span, Riffer::Tools::Response) -> void
+  # : ((Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span), Riffer::Tools::Response) -> void
+  def record_tool_outcome: (Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span, Riffer::Tools::Response) -> void
 
   # --
-  # : ((Riffer::Tracing::Otel::Span | Riffer::Tracing::Null::Span), Riffer::Messages::Assistant::ToolCall) -> void
-  def capture_tool_arguments: (Riffer::Tracing::Otel::Span | Riffer::Tracing::Null::Span, Riffer::Messages::Assistant::ToolCall) -> void
+  # : ((Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span), Riffer::Messages::Assistant::ToolCall) -> void
+  def capture_tool_arguments: (Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span, Riffer::Messages::Assistant::ToolCall) -> void
 
   # --
-  # : ((Riffer::Tracing::Otel::Span | Riffer::Tracing::Null::Span), Riffer::Tools::Response) -> void
-  def capture_tool_result: (Riffer::Tracing::Otel::Span | Riffer::Tracing::Null::Span, Riffer::Tools::Response) -> void
+  # : ((Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span), Riffer::Tools::Response) -> void
+  def capture_tool_result: (Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span, Riffer::Tools::Response) -> void
 
   # --
-  # : ((Riffer::Tracing::Otel::Span | Riffer::Tracing::Null::Span)) -> bool
-  def capture_tool_content?: (Riffer::Tracing::Otel::Span | Riffer::Tracing::Null::Span) -> bool
+  # : ((Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span)) -> bool
+  def capture_tool_content?: (Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span) -> bool
 end

data/sig/generated/riffer/tracing/{null.rbs → no_op.rbs}

@@ -1,8 +1,8 @@
-# Generated from lib/riffer/tracing/null.rb with RBS::Inline
+# Generated from lib/riffer/tracing/no_op.rb with RBS::Inline
 
 # No-op tracing backend, used when OTEL is unavailable or tracing is
 # disabled.
-module Riffer::Tracing::Null
+module Riffer::Tracing::NoOp
   # No-op stand-in for a span; answers <tt>recording?</tt> with +false+ so
   # callers can skip expensive attribute serialization.
   class Span
@@ -27,12 +27,12 @@ module Riffer::Tracing::Null
     def recording?: () -> bool
   end
 
-  SPAN: Riffer::Tracing::Null::Span
+  SPAN: Riffer::Tracing::NoOp::Span
 
   # Yields the no-op span, ignoring all span options.
   # --
-  # : [R] (String, **untyped) { (Riffer::Tracing::Null::Span) -> R } -> R
-  def in_span: [R] (String, **untyped) { (Riffer::Tracing::Null::Span) -> R } -> R
+  # : [R] (String, **untyped) { (Riffer::Tracing::NoOp::Span) -> R } -> R
+  def in_span: [R] (String, **untyped) { (Riffer::Tracing::NoOp::Span) -> R } -> R
 
   # Returns +nil+; there is no trace context without OTEL.
   # --

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

@@ -39,10 +39,11 @@ class Riffer::Tracing::Otel
   end
 
   # Builds a backend when the OpenTelemetry API is loadable at a supported
-  # version; returns +nil+ so resolution falls back to Null.
+  # version; returns +nil+ so resolution falls back to NoOp. +provider+
+  # defaults to the global <tt>OpenTelemetry.tracer_provider</tt>.
   # --
-  # : (provider: untyped) -> Riffer::Tracing::Otel?
-  def self.build: (provider: untyped) -> Riffer::Tracing::Otel?
+  # : (?provider: untyped) -> Riffer::Tracing::Otel?
+  def self.build: (?provider: untyped) -> Riffer::Tracing::Otel?
 
   # Whether the OpenTelemetry API gem is loadable at a supported version.
   # --

data/sig/generated/riffer/tracing.rbs

@@ -4,7 +4,7 @@
 # OpenTelemetry API and no-ops otherwise, so riffer never declares an OTEL
 # dependency.
 module Riffer::Tracing
-  @backend: (Riffer::Tracing::Otel | singleton(Riffer::Tracing::Null))?
+  @backend: untyped
 
   MUTEX: Mutex
 
@@ -14,8 +14,8 @@ module Riffer::Tracing
 
   # Opens a span around the block, yielding the span.
   # --
-  # : [R] (String, ?attributes: Hash[String, untyped]?, ?kind: Symbol) { (Riffer::Tracing::Otel::Span | Riffer::Tracing::Null::Span) -> R } -> R
-  def in_span: [R] (String, ?attributes: Hash[String, untyped]?, ?kind: Symbol) { (Riffer::Tracing::Otel::Span | Riffer::Tracing::Null::Span) -> R } -> R
+  # : [R] (String, ?attributes: Hash[String, untyped]?, ?kind: Symbol) { (Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span) -> R } -> R
+  def in_span: [R] (String, ?attributes: Hash[String, untyped]?, ?kind: Symbol) { (Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span) -> R } -> R
 
   # Returns the active trace context, for re-attachment across fiber or
   # thread boundaries.
@@ -32,8 +32,8 @@ module Riffer::Tracing
   # Stamps token usage onto the span — the <tt>gen_ai.usage.*</tt> counts and,
   # when the model was priced, <tt>riffer.cost</tt>.
   # --
-  # : ((Riffer::Tracing::Otel::Span | Riffer::Tracing::Null::Span), Riffer::Providers::TokenUsage?) -> void
-  def record_usage: (Riffer::Tracing::Otel::Span | Riffer::Tracing::Null::Span, Riffer::Providers::TokenUsage?) -> void
+  # : ((Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span), Riffer::Providers::TokenUsage?) -> void
+  def record_usage: (Riffer::Tracing::Otel::Span | Riffer::Tracing::NoOp::Span, Riffer::Providers::TokenUsage?) -> void
 
   # Discards the resolved backend so the next span re-resolves it.
   # --
@@ -43,10 +43,10 @@ module Riffer::Tracing
   private
 
   # --
-  # : () -> (Riffer::Tracing::Otel | singleton(Riffer::Tracing::Null))
-  def backend: () -> (Riffer::Tracing::Otel | singleton(Riffer::Tracing::Null))
+  # : () -> untyped
+  def backend: () -> untyped
 
   # --
-  # : () -> (Riffer::Tracing::Otel | singleton(Riffer::Tracing::Null))
-  def resolve_backend: () -> (Riffer::Tracing::Otel | singleton(Riffer::Tracing::Null))
+  # : () -> untyped
+  def resolve_backend: () -> untyped
 end

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

@@ -0,0 +1,5 @@
+# `Riffer::Metrics::NoOp` uses `extend self`; rbs-inline doesn't emit that, so
+# re-extend here to expose its instance methods as singleton methods.
+module Riffer::Metrics::NoOp
+  extend ::Riffer::Metrics::NoOp
+end

data/sig/manual/riffer/tracing/no_op.rbs

@@ -0,0 +1,5 @@
+# `Riffer::Tracing::NoOp` uses `extend self`; rbs-inline doesn't emit that, so
+# re-extend here to expose its instance methods as singleton methods.
+module Riffer::Tracing::NoOp
+  extend ::Riffer::Tracing::NoOp
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: riffer
 version: !ruby/object:Gem::Version
-  version: 0.33.0
+  version: 0.34.0
 platform: ruby
 authors:
 - Jake Bottrall
@@ -35,14 +35,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.48.1
+        version: 1.49.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.48.1
+        version: 1.49.0
 - !ruby/object:Gem::Dependency
   name: aws-sdk-bedrockruntime
   requirement: !ruby/object:Gem::Requirement
@@ -91,14 +91,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.66.1
+        version: 0.68.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.66.1
+        version: 0.68.0
 - !ruby/object:Gem::Dependency
   name: async
   requirement: !ruby/object:Gem::Requirement
@@ -336,7 +336,7 @@ files:
 - lib/riffer/messages/user.rb
 - lib/riffer/metrics.rb
 - lib/riffer/metrics/instruments.rb
-- lib/riffer/metrics/null.rb
+- lib/riffer/metrics/no_op.rb
 - lib/riffer/metrics/otel.rb
 - lib/riffer/params.rb
 - lib/riffer/params/boolean.rb
@@ -393,7 +393,7 @@ files:
 - lib/riffer/tools/toolable.rb
 - lib/riffer/tracing.rb
 - lib/riffer/tracing/capture.rb
-- lib/riffer/tracing/null.rb
+- lib/riffer/tracing/no_op.rb
 - lib/riffer/tracing/otel.rb
 - lib/riffer/tracing/stream_recorder.rb
 - lib/riffer/version.rb
@@ -457,7 +457,7 @@ files:
 - sig/generated/riffer/messages/user.rbs
 - sig/generated/riffer/metrics.rbs
 - sig/generated/riffer/metrics/instruments.rbs
-- sig/generated/riffer/metrics/null.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
@@ -514,7 +514,7 @@ files:
 - sig/generated/riffer/tools/toolable.rbs
 - sig/generated/riffer/tracing.rbs
 - sig/generated/riffer/tracing/capture.rbs
-- sig/generated/riffer/tracing/null.rbs
+- sig/generated/riffer/tracing/no_op.rbs
 - sig/generated/riffer/tracing/otel.rbs
 - sig/generated/riffer/tracing/stream_recorder.rbs
 - sig/generated/riffer/version.rbs
@@ -533,12 +533,12 @@ files:
 - sig/manual/riffer/mcp/registry.rbs
 - sig/manual/riffer/mcp/tool_factory.rbs
 - sig/manual/riffer/metrics.rbs
-- sig/manual/riffer/metrics/null.rbs
+- sig/manual/riffer/metrics/no_op.rbs
 - sig/manual/riffer/providers.rbs
 - sig/manual/riffer/providers/repository.rbs
 - sig/manual/riffer/tracing.rbs
 - sig/manual/riffer/tracing/capture.rbs
-- sig/manual/riffer/tracing/null.rbs
+- sig/manual/riffer/tracing/no_op.rbs
 homepage: https://riffer.ai
 licenses:
 - MIT

data/sig/manual/riffer/metrics/null.rbs

@@ -1,5 +0,0 @@
-# `Riffer::Metrics::Null` uses `extend self`; rbs-inline doesn't emit that, so
-# re-extend here to expose its instance methods as singleton methods.
-module Riffer::Metrics::Null
-  extend ::Riffer::Metrics::Null
-end

data/sig/manual/riffer/tracing/null.rbs

@@ -1,5 +0,0 @@
-# `Riffer::Tracing::Null` uses `extend self`; rbs-inline doesn't emit that, so
-# re-extend here to expose its instance methods as singleton methods.
-module Riffer::Tracing::Null
-  extend ::Riffer::Tracing::Null
-end