riffer 0.34.0 → 0.36.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bc442fb9eb0296a5a9c6f289c1c9e63e7cdb732ef52b013e1556d1765a874f2d
-  data.tar.gz: aa7512f0b3ac38e4f0c7be500095c73fca0ae1740c37370ceb2aeaf57349dac8
+  metadata.gz: 491260200757bf1d17b920f099012d771328fd333d46bb325f53dca863bcf204
+  data.tar.gz: 072ffcdf47b2aa115a3c7743cb77d4f238d18b926f0a53eb6b45a28148b8b2be
 SHA512:
-  metadata.gz: d9ace157326fa9ebfb356705f14cd4a8bac4af86e3ede2eb142adb4be36870399c81ee122fa02973135c9176b521bdee980745e3cc3f14422e12fbf1392fb009
-  data.tar.gz: cdc2e19b1aab77a93fb6ad7c4a800c5002a5efb63667366113fc04104a05c342863a1fa74219ed2569759f5f7be08dc534ac7c79b10c6d9ab61d6430db805113
+  metadata.gz: 97bf5aeed05fe9b591ae5a2bcf7c59d6990a46de1695fa4ff929823ead08b23372f35c4efb389a7e2f769a2a15dbad4dcb35bb1421e57c1fe5291216390b176c
+  data.tar.gz: 421d381a7d8c0a1be0c017a2c347096fa452d48d512706c474e82b5d90097e245d9f7680ed6745c10aac31502cdfe47efc56ae885dbd9e4b52b3b7e2803b7c10

data/.release-please-manifest.json

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

data/CHANGELOG.md

@@ -5,6 +5,24 @@ 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.36.0](https://github.com/janeapp/riffer/compare/riffer/v0.35.0...riffer/v0.36.0) (2026-07-03)
+
+
+### ⚠ BREAKING CHANGES
+
+* config.metrics, the Riffer::Metrics module, and Riffer::Metrics::Otel are removed. Hosts wiring a metrics backend must drop that configuration.
+
+### Features
+
+* remove the metrics primitive ([#347](https://github.com/janeapp/riffer/issues/347)) ([70a838e](https://github.com/janeapp/riffer/commit/70a838e9d49da12f89886c6e6f7bca35f427f77c))
+
+## [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)
 
 

data/README.md

@@ -63,7 +63,6 @@ For comprehensive documentation, see the [docs](docs/) directory:
 - [MCP](docs/14_MCP.md) - Integrating third-party MCP servers
 - [Serialization](docs/15_SERIALIZATION.md) - Persisting and transferring agent definitions
 - [Tracing](docs/16_TRACING.md) - OpenTelemetry span contract and host wiring
-- [Metrics](docs/17_METRICS.md) - OpenTelemetry metric contract and host wiring
 - [Providers](docs/providers/01_PROVIDERS.md) - LLM provider adapters
 
 ### API Reference

data/docs/01_OVERVIEW.md

@@ -132,7 +132,6 @@ Response
 - [Tools](06_TOOLS.md) - Creating tools
 - [Configuration](10_CONFIGURATION.md) - Global configuration
 - [Tracing](16_TRACING.md) - OpenTelemetry span contract and host wiring
-- [Metrics](17_METRICS.md) - OpenTelemetry metric contract and host wiring
 - [Evals](11_EVALS.md) - Evaluating agent quality
 - [Guardrails](12_GUARDRAILS.md) - Input/output validation
 - [Skills](13_SKILLS.md) - Packaged agent capabilities

data/docs/03_AGENTS.md

@@ -317,6 +317,46 @@ 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 the call emits (`invoke_agent`, `chat`, `execute_tool`, `execute_guardrail`). See [Tracing](16_TRACING.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). 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 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).
+
 ## Expand Your Agent
 
 | Goal                          | Feature           | Guide                                                                |

data/docs/10_CONFIGURATION.md

@@ -119,23 +119,6 @@ end
 | `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 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, 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
 
 Configure per-model token prices and riffer computes the cost of each LLM call onto its [`TokenUsage`](08_MESSAGES.md#token-usage-semantics). Riffer ships **no** price table — so an unconfigured model simply carries no cost (`token_usage.cost` is `nil`).

data/docs/16_TRACING.md

@@ -93,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/lib/riffer/agent/run.rb

@@ -10,63 +10,60 @@ 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 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)
-    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)
-        record_run_outcome(span, response)
-        response
-      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
+  #: (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)
+    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
-      # The inner rescue tags the span; capture error.type here too, at method
-      # scope, where the ensure can read it onto the metric.
-      error_type = error.class.name #: String?
+      # 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
-    ensure
-      Riffer::Metrics::Instruments::OPERATION_DURATION.record(Riffer::Metrics.monotonic_now - start, attributes: run_metric_attributes(agent, error_type))
     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 +81,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 +101,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 +119,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 +177,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 +230,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 +250,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 +282,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 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,27 +331,34 @@ 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)
-    attributes = {
-      "gen_ai.operation.name" => "invoke_agent",
-      "gen_ai.provider.name" => agent.provider.class.semconv_provider_name,
-      "gen_ai.request.model" => agent.model_name,
-      "gen_ai.agent.name" => agent.class.identifier
-    } #: Hash[String, untyped]
-    attributes["error.type"] = error_type if error_type
-    attributes
+  #: (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
 
   #--

data/lib/riffer/agent.rb

@@ -169,16 +169,16 @@ class Riffer::Agent
 
   # Generates a response using a new agent instance.
   #--
-  #: (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?context: Hash[Symbol, untyped]?) -> Riffer::Agent::Response
-  def self.generate(prompt = nil, files: nil, context: nil)
-    new(context: context).generate(prompt, files: files)
+  #: (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?context: Hash[Symbol, untyped]?, ?tags: Hash[(String | Symbol), untyped]) -> Riffer::Agent::Response
+  def self.generate(prompt = nil, files: nil, context: nil, tags: {})
+    new(context: context).generate(prompt, files: files, tags: tags)
   end
 
   # Streams a response using a new agent instance.
   #--
-  #: (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?context: Hash[Symbol, untyped]?) -> Enumerator[Riffer::StreamEvents::Base, void]
-  def self.stream(prompt = nil, files: nil, context: nil)
-    new(context: context).stream(prompt, files: files)
+  #: (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?context: Hash[Symbol, untyped]?, ?tags: Hash[(String | Symbol), untyped]) -> Enumerator[Riffer::StreamEvents::Base, void]
+  def self.stream(prompt = nil, files: nil, context: nil, tags: {})
+    new(context: context).stream(prompt, files: files, tags: tags)
   end
 
   # Reconstructs a runnable agent from a wire hash produced by +#to_h+.
@@ -288,22 +288,29 @@ class Riffer::Agent
   # against the current session, resuming a persisted conversation or pending
   # tool calls. +files:+ requires +prompt+.
   #
+  # +tags:+ is an optional flat hash of attribution tags applied to this single
+  # call: they propagate to the provider's native request-metadata field, and
+  # are stamped as +riffer.tag.*+ on every span the call emits. See
+  # +docs/03_AGENTS.md+ for the per-provider mapping. The reserved key
+  # +user_id+ also maps to the provider's native user identifier where one
+  # exists.
+  #
   #--
-  #: (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?) -> Riffer::Agent::Response
-  def generate(prompt = nil, files: nil)
-    Riffer::Agent::Run.generate(agent: self, prompt: prompt, files: files)
+  #: (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?tags: Hash[(String | Symbol), untyped]) -> Riffer::Agent::Response
+  def generate(prompt = nil, files: nil, tags: {})
+    Riffer::Agent::Run.generate(agent: self, prompt: prompt, files: files, tags: tags)
   end
 
   # Streams a response from the agent, returning an +Enumerator+ of
-  # +Riffer::StreamEvents+. See +#generate+ for prompt/files semantics.
+  # +Riffer::StreamEvents+. See +#generate+ for prompt/files/tags semantics.
   #
   # Raises Riffer::ArgumentError if structured output is configured.
   #
   #--
-  #: (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?) -> Enumerator[Riffer::StreamEvents::Base, void]
-  def stream(prompt = nil, files: nil)
+  #: (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?tags: Hash[(String | Symbol), untyped]) -> Enumerator[Riffer::StreamEvents::Base, void]
+  def stream(prompt = nil, files: nil, tags: {})
     raise Riffer::ArgumentError, "Structured output is not supported with streaming. Use #generate instead." if @structured_output
-    Riffer::Agent::Run.stream(agent: self, prompt: prompt, files: files)
+    Riffer::Agent::Run.stream(agent: self, prompt: prompt, files: files, tags: tags)
   end
 
   # Interrupts the agent loop from an +on_message+ callback. Equivalent to

data/lib/riffer/config.rb

@@ -106,47 +106,6 @@ class Riffer::Config
     end
   end
 
-  # Metrics-related global configuration, independent of +config.tracing+ so a
-  # host can run one signal without the other.
-  class Metrics
-    # Whether riffer records OTEL metric instruments; defaults to +true+, a
-    # no-op until a host wires an OTEL metrics SDK.
-    attr_reader :enabled #: bool
-
-    # The backend riffer routes measurements through; defaults to +nil+, a no-op.
-    # Riffer auto-detects no backend; assigning one is opt-in.
-    attr_reader :backend #: untyped
-
-    #--
-    #: () -> void
-    def initialize
-      @enabled = true
-      @backend = nil
-    end
-
-    # Sets the enabled flag, coercing boolean-ish values so an env-var
-    # +"false"+ (truthy in Ruby) doesn't silently keep metrics on. Raises
-    # Riffer::ArgumentError on an unrecognized value.
-    #--
-    #: (untyped) -> void
-    def enabled=(value)
-      @enabled = Riffer::Helpers::Boolean.coerce(value, attribute: "enabled")
-    end
-
-    # Sets the metrics backend riffer routes measurements through. Raises
-    # Riffer::ArgumentError unless the value is +nil+ or responds to
-    # +record_histogram+.
-    #--
-    #: (untyped) -> void
-    def backend=(value)
-      unless value.nil? || value.respond_to?(:record_histogram)
-        raise Riffer::ArgumentError, "metrics backend must respond to #record_histogram"
-      end
-      @backend = value
-      Riffer::Metrics.reset!
-    end
-  end
-
   # Consumer-configured token pricing, keyed by +provider/model+ id. Riffer
   # ships no price table, so an unconfigured model carries no cost.
   class Pricing
@@ -306,9 +265,6 @@ class Riffer::Config
   # Tracing-related global configuration.
   attr_reader :tracing #: Riffer::Config::Tracing
 
-  # Metrics-related global configuration.
-  attr_reader :metrics #: Riffer::Config::Metrics
-
   # Consumer-configured per-model token pricing.
   attr_reader :pricing #: Riffer::Config::Pricing
 
@@ -357,7 +313,6 @@ class Riffer::Config
     @tool_runtime = Riffer::Tools::Runtime::Inline.new
     @skills = Skills.new
     @tracing = Tracing.new
-    @metrics = Metrics.new
     @pricing = Pricing.new
     @message_id_strategy = :none
     @experimental_history_healing = false

data/lib/riffer/guardrails/runner.rb

@@ -13,12 +13,16 @@ class Riffer::Guardrails::Runner
   # The context passed to guardrails.
   attr_reader :context #: untyped
 
+  # The normalized per-call tags, stamped as +riffer.tag.*+ on guardrail spans.
+  attr_reader :tags #: Hash[String, String]
+
   #--
-  #: (Array[Hash[Symbol, untyped]], phase: Symbol, ?context: untyped) -> void
-  def initialize(guardrail_configs, phase:, context: nil)
+  #: (Array[Hash[Symbol, untyped]], phase: Symbol, ?context: untyped, ?tags: Hash[String, String]) -> void
+  def initialize(guardrail_configs, phase:, context: nil, tags: {})
     @guardrail_configs = guardrail_configs
     @phase = phase
     @context = context
+    @tags = tags
   end
 
   # Runs the guardrails sequentially. For the +:before+ phase +data+ is the
@@ -81,32 +85,15 @@ class Riffer::Guardrails::Runner
   #--
   #: (Riffer::Guardrail, untyped, messages: Array[Riffer::Messages::Base]?) -> Riffer::Guardrails::Result
   def execute_guardrail(guardrail, data, messages:)
-    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
+    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
-      error_type = error.class.name #: String?
+      # 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
-    ensure
-      Riffer::Metrics::Instruments::GUARDRAIL_DURATION.record(Riffer::Metrics.monotonic_now - start, attributes: guardrail_metric_attributes(guardrail, error_type))
     end
   end
 
@@ -129,15 +116,7 @@ class Riffer::Guardrails::Runner
     {
       "riffer.guardrail.name" => guardrail.name,
       "riffer.guardrail.phase" => phase.to_s
-    }
-  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
+    }.merge(tags.transform_keys { |key| "riffer.tag.#{key}" })
   end
 
   # A block is a handled outcome, so its span status stays unset — an error