riffer 0.33.0 → 0.35.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e72e36f6d29b3a2387246615224e19becb1d157e4a2327f8229ee481f3704e7e
-  data.tar.gz: 89deb58a1ec3a5f0af904d86b38057a2d7bf301490deeadf492bbe11942d0e96
+  metadata.gz: acfc9a0c002c97b79d515172d71aa419359e27fac0a3809934c30057931e66ef
+  data.tar.gz: 322aaebffb66c41824fdd3a3c43d08ae6bb806f8e2e06ca5ee1834648704e1d5
 SHA512:
-  metadata.gz: 11fadbbfd249ce864885709684c51801d3ec2aeba83a3f750ee7afdb390750798d9598df69796bf047afa4c4b4e7136cfc7cff0edf851a0a8d945bb9f8549204
-  data.tar.gz: 60b6c3b2c8e7201cdfb6822709531640b501f4218e63fc2768349c9509b67ba286299fc00372a0c019b07a01390f4a7e77c5a4382e7ffe21ed7cfd250acb67b9
+  metadata.gz: ba3554a4a135ae43f5d5a2d65928275e4acfcc27c03609f2578d5304e8825c3f42f05b7229fe5881fdc7c663372ef6ca3591af02b2719167bc7711fc7754e7e6
+  data.tar.gz: 49c2b41f0cb606ec9e86b72777d55b3b3222220d879b5e05ed211a07094d9561c7e1c054ce2689d3b81b6ff872d981f6e1f24306b916cf12a697f7df23f91a69

data/.release-please-manifest.json

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

data/CHANGELOG.md

@@ -5,6 +5,25 @@ 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.35.0](https://github.com/janeapp/riffer/compare/riffer/v0.34.0...riffer/v0.35.0) (2026-06-25)
+
+
+### Features
+
+* per-call tags: for Agent#generate and #stream ([#339](https://github.com/janeapp/riffer/issues/339)) ([ddfda89](https://github.com/janeapp/riffer/commit/ddfda8929ca3b594415f827957d8c91104387317))
+
+## [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/03_AGENTS.md

@@ -317,6 +317,50 @@ agent.generate('Hello')
 
 When `config:` is supplied, the class-level configuration is ignored for that instance.
 
+## Per-Call Tags
+
+`#generate` and `#stream` accept an optional `tags:` hash — a flat map of attribution labels scoped to that single call (for cost/usage attribution, filtering audit logs, slicing telemetry). It is **per-call only**.
+
+```ruby
+agent.generate("Summarize this ticket.",
+  tags: {team: "growth", feature: "summarizer", user_id: "u_abc123"})
+
+agent.stream("...", tags: {team: "growth", environment: "production"})
+```
+
+Keys and values may be `String` or `Symbol`; both are stringified, and entries with a `nil` value are dropped. Passing a non-`Hash` raises `Riffer::ArgumentError`. An omitted or empty `tags:` is a complete no-op.
+
+Tags propagate to **two** places:
+
+1. The provider's native per-request metadata field (see the mapping below).
+2. Observability — stamped as `riffer.tag.<key>` on **every** span and metric the call emits (`invoke_agent`, `chat`, `execute_tool`, `execute_guardrail` spans, and the duration/token-usage/cost metrics). See [Tracing](16_TRACING.md) and [Metrics](17_METRICS.md).
+
+### Reserved key: `user_id`
+
+`user_id` is a reserved tag. Beyond appearing like any other tag, it maps to the provider's native end-user identifier where one exists (see the table).
+
+### Provider mapping
+
+| Provider              | Native request field          | `user_id` handling                      |
+| --------------------- | ----------------------------- | --------------------------------------- |
+| Amazon Bedrock        | `request_metadata` (all tags) | Ordinary entry; no dedicated user field |
+| OpenAI / Azure OpenAI | `metadata` (all tags)         | Also mapped to `safety_identifier`      |
+| OpenRouter            | `metadata` (all tags)         | Also mapped to `user`                   |
+| Anthropic             | `metadata.user_id` **only**   | The only tag forwarded                  |
+| Gemini                | _(none — observability only)_ | Tag only; no request field              |
+
+**Anthropic silently drops non-`user_id` tags.** The Messages API has no free-form request-metadata field — only `metadata.user_id`. So for Anthropic, `user_id` is forwarded as `metadata: {user_id: …}` and **every other tag is dropped from the request** (it still appears on spans and metrics). This is intentional.
+
+**Gemini is observability-only.** Riffer's Gemini adapter targets the Gemini Developer API (`generativelanguage.googleapis.com`), whose `generateContent` request has **no** `labels` field — sending unknown fields is rejected. So tags are **not** added to the Gemini request; they propagate to spans and metrics only. Native request labels (`labels`, lowercase `[a-z0-9_-]`, ≤63 chars each) are a Vertex AI feature and would arrive with a future Vertex adapter.
+
+### Provider limits (not enforced)
+
+Riffer does not validate tag count, key/value length, or charset — it forwards what you give it and lets the provider reject anything out of bounds. Known limits: Bedrock `requestMetadata` ≤16 entries, key/value ≤256 chars; OpenAI / OpenRouter `metadata` ≤16 pairs (OpenRouter: 64-char keys, 512-char values).
+
+### Metric cardinality
+
+Tags are promoted onto metric dimensions verbatim — there is no allow-list. High-cardinality values (e.g. a unique `user_id` per request) will create a correspondingly large number of metric series in your backend. Keep metric-bound tags low-cardinality.
+
 ## Expand Your Agent
 
 | Goal                          | Feature           | Guide                                                                |

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:
@@ -69,6 +93,10 @@ Every attribute a span can carry is listed below, including the conditional ones
 
 The contract promise is: **when present**, a key carries the documented meaning and type. It is _not_ a promise that every key appears on every span.
 
+### Per-call tags (`riffer.tag.*`)
+
+Any tags passed to `#generate` / `#stream` via `tags:` are stamped on **all four** span types as `riffer.tag.<key>` (string), so the per-span tables below omit them. They appear on every span the tagged call emits and are absent otherwise. Example: `tags: {team: "growth"}` adds `riffer.tag.team` → `"growth"` to the `invoke_agent`, `chat`, `execute_tool`, and `execute_guardrail` spans. See [Per-Call Tags](03_AGENTS.md#per-call-tags) for the full surface and the per-provider request-metadata mapping.
+
 ## `invoke_agent {agent}` — the run span
 
 `INTERNAL`. One per call to `Agent#generate` or `Agent#stream`. The span name suffix is the agent's identifier (e.g. `invoke_agent weather-agent`).

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.
@@ -56,6 +74,8 @@ OpenTelemetry.meter_provider.add_view(
 
 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`.
@@ -99,6 +119,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

@@ -10,37 +10,45 @@ module Riffer::Agent::Run
   # for prompt/files semantics.
   #
   #--
-  #: (agent: Riffer::Agent, ?prompt: String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?) -> Riffer::Agent::Response
-  def generate(agent:, prompt: nil, files: nil)
+  #: (agent: Riffer::Agent, ?prompt: String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?tags: Hash[(String | Symbol), untyped]) -> Riffer::Agent::Response
+  def generate(agent:, prompt: nil, files: nil, tags: {})
     append_user_message(agent, prompt, files: files)
-    run_loop(agent)
+    run_loop(agent, tags: tags)
   end
 
   # Runs the streaming loop for the given agent. See Riffer::Agent#stream
   # for prompt/files semantics.
   #
   #--
-  #: (agent: Riffer::Agent, ?prompt: String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?) -> Enumerator[Riffer::StreamEvents::Base, void]
-  def stream(agent:, prompt: nil, files: nil)
+  #: (agent: Riffer::Agent, ?prompt: String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?tags: Hash[(String | Symbol), untyped]) -> Enumerator[Riffer::StreamEvents::Base, void]
+  def stream(agent:, prompt: nil, files: nil, tags: {})
     append_user_message(agent, prompt, files: files)
     # The enumerator body runs in its own fiber, where the fiber-local OTEL
-    # context is empty — capture here so the run span parents to the caller's trace.
+    # context is empty — capture here so the run span parents to the caller's
+    # trace. tags ride as an ordinary argument captured in the closure, so they
+    # cross the fiber boundary without any re-propagation.
     trace_context = Riffer::Tracing.current_context
     Enumerator.new do |stream_yielder|
-      Riffer::Tracing.with_context(trace_context) { run_loop(agent, stream_yielder: stream_yielder) }
+      Riffer::Tracing.with_context(trace_context) { run_loop(agent, tags: tags, stream_yielder: stream_yielder) }
     end
   end
 
   private
 
+  # 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
+  # mapping.
   #--
-  #: (Riffer::Agent, ?stream_yielder: Enumerator::Yielder?) -> Riffer::Agent::Response
-  def run_loop(agent, stream_yielder: nil)
+  #: (Riffer::Agent, ?tags: Hash[(String | Symbol), untyped]?, ?stream_yielder: Enumerator::Yielder?) -> Riffer::Agent::Response
+  def run_loop(agent, tags: {}, stream_yielder: nil)
+    tags = normalize_tags(tags)
     start = Riffer::Metrics.monotonic_now
     error_type = nil #: String?
     begin
-      Riffer::Tracing.in_span("invoke_agent #{agent.class.identifier}", attributes: run_span_attributes(agent), kind: :internal) do |span|
-        response = execute_run(agent, stream_yielder)
+      Riffer::Tracing.in_span("invoke_agent #{agent.class.identifier}", attributes: run_span_attributes(agent, tags), kind: :internal) do |span|
+        response = execute_run(agent, stream_yielder, tags)
         record_run_outcome(span, response)
         response
       rescue => error
@@ -55,18 +63,18 @@ module Riffer::Agent::Run
       error_type = error.class.name #: String?
       raise
     ensure
-      Riffer::Metrics::Instruments::OPERATION_DURATION.record(Riffer::Metrics.monotonic_now - start, attributes: run_metric_attributes(agent, error_type))
+      Riffer::Metrics::Instruments::OPERATION_DURATION.record(Riffer::Metrics.monotonic_now - start, attributes: run_metric_attributes(agent, error_type, tags))
     end
   end
 
   #--
-  #: (Riffer::Agent, Enumerator::Yielder?) -> Riffer::Agent::Response
-  def execute_run(agent, stream_yielder)
+  #: (Riffer::Agent, Enumerator::Yielder?, ?Hash[String, String]) -> Riffer::Agent::Response
+  def execute_run(agent, stream_yielder, tags = {})
     all_modifications = [] #: Array[Riffer::Guardrails::Modification]
     run_usage = nil #: Riffer::Providers::TokenUsage?
     run_steps = 0
 
-    run_before_guardrails(agent, stream_yielder, all_modifications) do |tripwire|
+    run_before_guardrails(agent, stream_yielder, all_modifications, tags) do |tripwire|
       return tripwire_response(agent, stream_yielder, tripwire, all_modifications, steps: run_steps)
     end
 
@@ -84,16 +92,16 @@ module Riffer::Agent::Run
       step = agent.session.steps
 
       reason = catch(:riffer_interrupt) do
-        execute_pending_tool_calls(agent)
+        execute_pending_tool_calls(agent, tags)
 
         loop do
-          response = stream_yielder ? accumulate_streamed_response(agent, stream_yielder) : call_llm(agent)
+          response = stream_yielder ? accumulate_streamed_response(agent, stream_yielder, tags) : call_llm(agent, tags)
           step += 1
           run_steps += 1
           track_token_usage(agent, response.token_usage)
           run_usage = sum_usage(run_usage, response.token_usage)
 
-          processed_response = run_after_guardrails(agent, response, stream_yielder, all_modifications) do |tripwire|
+          processed_response = run_after_guardrails(agent, response, stream_yielder, all_modifications, tags) do |tripwire|
             return tripwire_response(agent, stream_yielder, tripwire, all_modifications, token_usage: run_usage, steps: run_steps)
           end
 
@@ -104,7 +112,7 @@ module Riffer::Agent::Run
           max_steps = agent.config.max_steps
           throw :riffer_interrupt, Riffer::Agent::INTERRUPT_MAX_STEPS if max_steps && step >= max_steps
 
-          execute_tool_calls(agent, processed_response)
+          execute_tool_calls(agent, processed_response, tags: tags)
         end
 
         return final_response(agent, all_modifications, token_usage: run_usage, steps: run_steps)
@@ -122,14 +130,14 @@ module Riffer::Agent::Run
   end
 
   #--
-  #: (Riffer::Agent, Enumerator::Yielder) -> Riffer::Messages::Assistant
-  def accumulate_streamed_response(agent, stream_yielder)
+  #: (Riffer::Agent, Enumerator::Yielder, ?Hash[String, String]) -> Riffer::Messages::Assistant
+  def accumulate_streamed_response(agent, stream_yielder, tags = {})
     accumulated_content = ""
     accumulated_tool_calls = [] #: Array[Riffer::Messages::Assistant::ToolCall]
     accumulated_token_usage = nil #: Riffer::Providers::TokenUsage?
     accumulated_finish_reason = nil #: Symbol?
 
-    call_llm_stream(agent).each do |event|
+    call_llm_stream(agent, tags).each do |event|
       stream_yielder << event
 
       case event
@@ -180,33 +188,33 @@ module Riffer::Agent::Run
   end
 
   #--
-  #: (Riffer::Agent) -> Riffer::Messages::Assistant
-  def call_llm(agent)
+  #: (Riffer::Agent, ?Hash[String, String]) -> Riffer::Messages::Assistant
+  def call_llm(agent, tags = {})
     agent.provider.generate_text(
       messages: agent.session.messages,
       model: agent.model_name,
       tools: effective_tools(agent),
-      **merged_model_options(agent)
+      **merged_model_options(agent, tags)
     )
   end
 
   #--
-  #: (Riffer::Agent) -> Enumerator[Riffer::StreamEvents::Base, void]
-  def call_llm_stream(agent)
+  #: (Riffer::Agent, ?Hash[String, String]) -> Enumerator[Riffer::StreamEvents::Base, void]
+  def call_llm_stream(agent, tags = {})
     agent.provider.stream_text(
       messages: agent.session.messages,
       model: agent.model_name,
       tools: effective_tools(agent),
-      **merged_model_options(agent)
+      **merged_model_options(agent, tags)
     )
   end
 
   #--
-  #: (Riffer::Agent, Riffer::Messages::Assistant, ?tool_calls: Array[Riffer::Messages::Assistant::ToolCall]) -> void
-  def execute_tool_calls(agent, assistant_message, tool_calls: assistant_message.tool_calls)
+  #: (Riffer::Agent, Riffer::Messages::Assistant, ?tool_calls: Array[Riffer::Messages::Assistant::ToolCall], ?tags: Hash[String, String]) -> void
+  def execute_tool_calls(agent, assistant_message, tool_calls: assistant_message.tool_calls, tags: {})
     return if tool_calls.empty?
 
-    results = agent.tool_runtime.execute(tool_calls, tools: effective_tools(agent), context: agent.context, assistant_message: assistant_message)
+    results = agent.tool_runtime.execute(tool_calls, tools: effective_tools(agent), context: agent.context, assistant_message: assistant_message, tags: tags)
 
     inject_discovered_tools(agent, results)
 
@@ -233,19 +241,19 @@ module Riffer::Agent::Run
   end
 
   #--
-  #: (Riffer::Agent) -> void
-  def execute_pending_tool_calls(agent)
+  #: (Riffer::Agent, ?Hash[String, String]) -> void
+  def execute_pending_tool_calls(agent, tags = {})
     assistant_message, pending = agent.session.pending_tool_calls
-    execute_tool_calls(agent, assistant_message, tool_calls: pending) if assistant_message
+    execute_tool_calls(agent, assistant_message, tool_calls: pending, tags: tags) if assistant_message
   end
 
   #--
-  #: (Riffer::Agent, Enumerator::Yielder?, Array[Riffer::Guardrails::Modification]) { (Riffer::Guardrails::Tripwire) -> void } -> void
-  def run_before_guardrails(agent, stream_yielder, all_modifications)
+  #: (Riffer::Agent, Enumerator::Yielder?, Array[Riffer::Guardrails::Modification], ?Hash[String, String]) { (Riffer::Guardrails::Tripwire) -> void } -> void
+  def run_before_guardrails(agent, stream_yielder, all_modifications, tags = {})
     guardrails = agent.config.guardrails_for(:before)
     return if guardrails.empty?
 
-    runner = Riffer::Guardrails::Runner.new(guardrails, phase: :before, context: agent.context)
+    runner = Riffer::Guardrails::Runner.new(guardrails, phase: :before, context: agent.context, tags: tags)
     processed_messages, tripwire, modifications = runner.run(agent.session.messages)
     agent.session.set(processed_messages) unless tripwire
     record_modifications!(stream_yielder, all_modifications, modifications)
@@ -253,12 +261,12 @@ module Riffer::Agent::Run
   end
 
   #--
-  #: (Riffer::Agent, Riffer::Messages::Assistant, Enumerator::Yielder?, Array[Riffer::Guardrails::Modification]) { (Riffer::Guardrails::Tripwire) -> void } -> untyped
-  def run_after_guardrails(agent, response, stream_yielder, all_modifications)
+  #: (Riffer::Agent, Riffer::Messages::Assistant, Enumerator::Yielder?, Array[Riffer::Guardrails::Modification], ?Hash[String, String]) { (Riffer::Guardrails::Tripwire) -> void } -> untyped
+  def run_after_guardrails(agent, response, stream_yielder, all_modifications, tags = {})
     guardrails = agent.config.guardrails_for(:after)
     return response if guardrails.empty?
 
-    runner = Riffer::Guardrails::Runner.new(guardrails, phase: :after, context: agent.context)
+    runner = Riffer::Guardrails::Runner.new(guardrails, phase: :after, context: agent.context, tags: tags)
     processed_response, tripwire, modifications = runner.run(response, messages: agent.session.messages)
 
     response_index = agent.session.messages.length
@@ -285,11 +293,16 @@ module Riffer::Agent::Run
     discovered.empty? ? agent.tools : agent.tools + discovered
   end
 
+  # +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.
   #--
-  #: (Riffer::Agent) -> Hash[Symbol, untyped]
-  def merged_model_options(agent)
+  #: (Riffer::Agent, ?Hash[String, String]) -> Hash[Symbol, untyped]
+  def merged_model_options(agent, tags = {})
     opts = agent.config.model_options.dup
     opts[:structured_output] = agent.structured_output if agent.structured_output
+    opts[:tags] = tags unless tags.empty?
     opts
   end
 
@@ -329,19 +342,19 @@ module Riffer::Agent::Run
   end
 
   #--
-  #: (Riffer::Agent) -> Hash[String, untyped]
-  def run_span_attributes(agent)
+  #: (Riffer::Agent, ?Hash[String, String]) -> Hash[String, untyped]
+  def run_span_attributes(agent, tags = {})
     {
       "gen_ai.operation.name" => "invoke_agent",
       "gen_ai.agent.name" => agent.class.identifier,
       "gen_ai.provider.name" => agent.provider.class.semconv_provider_name,
       "gen_ai.request.model" => agent.model_name
-    }
+    }.merge(tag_attributes(tags))
   end
 
   #--
-  #: (Riffer::Agent, String?) -> Hash[String, untyped]
-  def run_metric_attributes(agent, error_type)
+  #: (Riffer::Agent, String?, ?Hash[String, String]) -> Hash[String, untyped]
+  def run_metric_attributes(agent, error_type, tags = {})
     attributes = {
       "gen_ai.operation.name" => "invoke_agent",
       "gen_ai.provider.name" => agent.provider.class.semconv_provider_name,
@@ -349,11 +362,31 @@ module Riffer::Agent::Run
       "gen_ai.agent.name" => agent.class.identifier
     } #: Hash[String, untyped]
     attributes["error.type"] = error_type if error_type
-    attributes
+    attributes.merge(tag_attributes(tags))
+  end
+
+  #--
+  #: (Hash[(String | Symbol), untyped]?) -> Hash[String, String]
+  def normalize_tags(tags)
+    return {} if tags.nil?
+    raise Riffer::ArgumentError, "tags: must be a Hash, got #{tags.class}" unless tags.is_a?(Hash)
+
+    result = {} #: Hash[String, String]
+    tags.each do |key, value|
+      next if value.nil?
+      result[key.to_s] = value.to_s
+    end
+    result
+  end
+
+  #--
+  #: (Hash[String, String]) -> Hash[String, String]
+  def tag_attributes(tags)
+    tags.transform_keys { |key| "riffer.tag.#{key}" }
   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)