verica-observability 0.1.4 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 438dcb9a5e21879ac0078d2a16a33424936a998bf89abb80aafb5948581de805
-  data.tar.gz: a3297755e16825869ab659f288d4b6ffe5dfbca5161880aecd103b106af7c68b
+  metadata.gz: 179e07f9889543da9092844457585650ecef766cc9cbc8fdf10225c1606e3e30
+  data.tar.gz: 99c8a02603324aa3c5b8fa14acd401483f8a0b8d67ef5f761d4785f7e37aed2d
 SHA512:
-  metadata.gz: 7aa94440e9614e45bf317092481309c70751bcbc35e73ffa5eb2b75717ed77792186520c61f5cb6bc78bd42906ef297e034ae12e4dfc29d05c08adb6fc4f8d67
-  data.tar.gz: 562391c9009fe1fdfc82cd6319b3a081202824bf6cd66363f1136548f880c5f652a18e090ceb3d49b9e0d1f92cee0b4fded2e6352fdca29d8012360832eb4571
+  metadata.gz: cb9b59ec8c73e36a93409399842b5554b54f0f9583d96583f219d1b0fa2c5fbd716e81fe791473bef6e317186bc083fded6e3f511e1a70cfde73216df154d9b8
+  data.tar.gz: 286212de59d6b2aba37cf9e0ee9a149968c44b9c0a426e367b8e13552d751458d57efb8e0b1ffaed5e530ef0255473bbca342e23fb8c1dac7eedb76f4d0e2c3d

data/README.md

@@ -50,10 +50,67 @@ anthropic = Verica.wrap_openai_compatible(OpenAI::Client.new(
 anthropic.chat(parameters: { model: 'claude-sonnet-4', messages: [...] })
 ```
 
-`wrap_ruby_openai` is a back-compat alias of `wrap_openai_compatible`. Streaming
-calls (a `stream:` proc) pass through with request-side attributes only. Ruby has
+`wrap_ruby_openai` is a back-compat alias of `wrap_openai_compatible`. Ruby has
 no native Gemini/Anthropic gem support; use the OpenAI-compatible endpoints above.
 
+## Per-request conversation id
+
+Group the turns of one chat under a single `gen_ai.conversation.id` without a
+global setting. `Verica.with_conversation(id)` sets a thread-local override that
+both wrappers stamp on every span emitted inside the block; it takes precedence
+over the global `conversation_id:` from `init`, restores the previous value on
+exit (including when the block raises), and is safe to nest. `id` is coerced with
+`to_s`; a nil or empty id emits no conversation attribute. In a Rails chatbot
+controller:
+
+```ruby
+class MessagesController < ApplicationController
+  def create
+    Verica.with_conversation("chat-#{conversation.id}") do
+      reply = openai.chat(parameters: {
+        model: 'gpt-4o-mini',
+        messages: conversation.to_openai_messages
+      })
+      # ...persist and render reply...
+    end
+  end
+end
+```
+
+`with_conversation` returns the block's value, so you can wrap an existing method
+body with it and keep the return unchanged. Each thread carries its own override,
+so concurrent requests never leak conversation ids into one another.
+
+## Streaming (`wrap_openai_compatible`)
+
+Streaming calls (a `stream:` proc in `parameters`) are fully captured: the
+wrapper accumulates the chunks as they flow to your proc, then annotates the span
+with the joined assistant output and the response model. Your proc still receives
+every chunk, in order, unchanged; instrumentation never interferes with the
+stream.
+
+Tokens (and therefore cost) are only available when the provider sends a final
+usage chunk, which OpenAI does when you pass `stream_options: { include_usage:
+true }`:
+
+```ruby
+client.chat(parameters: {
+  model: 'gpt-4o-mini',
+  messages: [{ role: 'user', content: 'Hello!' }],
+  stream_options: { include_usage: true },
+  stream: proc { |chunk| print chunk.dig('choices', 0, 'delta', 'content') }
+})
+```
+
+If you'd rather not touch every call site, set `Verica.init(..., stream_usage:
+true)` and the wrapper injects `stream_options: { include_usage: true }` for you
+(merged into a private copy, never mutating your parameters hash). It is off by
+default because the extra usage chunk arrives with an empty `choices` array that
+some caller procs may not expect.
+
+Limitation: streamed tool-call deltas (`delta.tool_calls`) are not captured in
+this pass; text output, model, and usage are.
+
 ## Use (RubyLLM)
 
 With RubyLLM plus its thoughtbot OpenTelemetry instrumentation, `Verica.init`
@@ -66,13 +123,14 @@ span batch is exported.
 
 ## Options
 
-| Option / env var                              | Default    | Notes                           |
-| --------------------------------------------- | ---------- | ------------------------------- |
-| `token:` / `VERICA_TOKEN`                     | (required) | ingest-scoped API token         |
-| `capture_content:` / `VERICA_CAPTURE_CONTENT` | `true`     | send prompt/response content    |
-| `conversation_id:`                            | (none)     | stamps `gen_ai.conversation.id` |
-| `service_name:` / `OTEL_SERVICE_NAME`         | `app`      | resource service.name           |
-| `debug:` / `VERICA_DEBUG`                     | `false`    | log export errors               |
+| Option / env var                              | Default    | Notes                              |
+| --------------------------------------------- | ---------- | ---------------------------------- |
+| `token:` / `VERICA_TOKEN`                     | (required) | ingest-scoped API token            |
+| `capture_content:` / `VERICA_CAPTURE_CONTENT` | `true`     | send prompt/response content       |
+| `conversation_id:`                            | (none)     | stamps `gen_ai.conversation.id`    |
+| `service_name:` / `OTEL_SERVICE_NAME`         | `app`      | resource service.name              |
+| `stream_usage:` / `VERICA_STREAM_USAGE`       | `false`    | inject `stream_options` for tokens |
+| `debug:` / `VERICA_DEBUG`                     | `false`    | log export errors                  |
 
 Fail-open by design: if Verica is unreachable or the token is invalid, spans are
 dropped and your app is never affected. Export errors are silent unless `debug`

data/lib/verica/config.rb

@@ -3,7 +3,7 @@
 module Verica
   # Config resolution: options > env vars > defaults. Pure.
   Config = Struct.new(:token, :endpoint, :capture_content, :conversation_id, :service_name, :debug,
-                      keyword_init: true) do
+                      :stream_usage, keyword_init: true) do
     # Verica's hosted ingest endpoint. Override via the `endpoint:` option or the
     # VERICA_ENDPOINT env var for self-host or local dev. Only `token` is required.
     DEFAULT_ENDPOINT = 'https://ingest.verica.app'
@@ -22,7 +22,12 @@ module Verica
         capture_content: capture,
         conversation_id: options[:conversation_id],
         service_name: options[:service_name] || env['OTEL_SERVICE_NAME'] || 'app',
-        debug: options[:debug].nil? ? %w[1 true].include?(env['VERICA_DEBUG']) : options[:debug]
+        debug: options[:debug].nil? ? %w[1 true].include?(env['VERICA_DEBUG']) : options[:debug],
+        # Opt-in: append `stream_options: { include_usage: true }` to streaming
+        # calls so the provider emits a final usage chunk (tokens + cost). Off by
+        # default because it adds a trailing empty-choices chunk some caller procs
+        # may not expect.
+        stream_usage: options[:stream_usage].nil? ? %w[1 true].include?(env['VERICA_STREAM_USAGE']) : options[:stream_usage]
       ), []]
     end
   end

data/lib/verica/openai_wrapper.rb

@@ -76,7 +76,8 @@ module Verica
         span.set_attribute('gen_ai.operation.name', 'chat')
         span.set_attribute('gen_ai.provider.name', Verica::Providers.for_model(params[:model]))
         span.set_attribute('gen_ai.request.model', params[:model].to_s) if params[:model]
-        span.set_attribute('gen_ai.conversation.id', cfg.conversation_id) if cfg&.conversation_id
+        conversation_id = Verica.conversation_id
+        span.set_attribute('gen_ai.conversation.id', conversation_id) if conversation_id
 
         model = response.respond_to?(:model) ? response.model : nil
         span.set_attribute('gen_ai.response.model', model) if model

data/lib/verica/ruby_openai_wrapper.rb

@@ -22,9 +22,27 @@ module Verica
         tracer = OpenTelemetry.tracer_provider.tracer('verica-observability', Verica::VERSION)
         tracer.start_span("chat #{model}", kind: :client)
       end
+
+      # Streaming: ruby-openai delivers each chunk to the caller's proc and the
+      # returned value is not a stable Hash. We wrap that proc so our accumulator
+      # sees every chunk first, then hand it to the caller unchanged. The HTTP
+      # call is synchronous, so by the time `@client.chat` returns the stream has
+      # fully drained and the accumulator is complete.
+      accumulator = nil
+      call_parameters = parameters
+      stream_key = stream_key_for(parameters)
+      if stream_key && parameters[stream_key].respond_to?(:call)
+        acc = StreamAccumulator.new
+        built = safely { build_streaming_parameters(parameters, stream_key, acc) }
+        if built
+          accumulator = acc
+          call_parameters = built
+        end
+      end
+
       begin
-        response = @client.chat(parameters: parameters)
-        safely { annotate(span, parameters, response) } if span
+        response = @client.chat(parameters: call_parameters)
+        safely { annotate(span, parameters, response, accumulator) } if span
         response
       rescue StandardError => e
         safely { span&.status = OpenTelemetry::Trace::Status.error(e.message) }
@@ -44,21 +62,60 @@ module Verica
 
     private
 
-    def annotate(span, parameters, response)
+    def stream_key_for(parameters)
+      if parameters.key?(:stream)
+        :stream
+      elsif parameters.key?('stream')
+        'stream'
+      end
+    end
+
+    # Returns a shallow copy of the caller's parameters with the stream proc
+    # replaced by our wrapper (which accumulates then delegates). Never mutates
+    # the caller's hash. When `stream_usage` is on, also injects
+    # `stream_options: { include_usage: true }` so the provider sends a final
+    # usage chunk, without mutating any nested hash the caller passed.
+    def build_streaming_parameters(parameters, stream_key, accumulator)
+      user_proc = parameters[stream_key]
+      wrapped = proc do |*args|
+        safely { accumulator.add(args.first) }
+        user_proc.call(*args)
+      end
+
+      copy = parameters.dup
+      copy[stream_key] = wrapped
+
+      if Verica.config&.stream_usage
+        symbols = stream_key.is_a?(Symbol)
+        opts_key = symbols ? :stream_options : 'stream_options'
+        usage_key = symbols ? :include_usage : 'include_usage'
+        existing = copy[opts_key]
+        merged = (existing.is_a?(Hash) ? existing.dup : {})
+        merged[usage_key] = true
+        copy[opts_key] = merged
+      end
+
+      copy
+    end
+
+    def annotate(span, parameters, response, accumulator = nil)
       cfg = Verica.config
       model = parameters[:model] || parameters['model']
       messages = parameters[:messages] || parameters['messages']
-      streaming = parameters[:stream] || parameters['stream']
 
       span.set_attribute('gen_ai.operation.name', 'chat')
       span.set_attribute('gen_ai.provider.name', Verica::Providers.for_model(model))
       span.set_attribute('gen_ai.request.model', model.to_s) if model
-      span.set_attribute('gen_ai.conversation.id', cfg.conversation_id) if cfg&.conversation_id
+      conversation_id = Verica.conversation_id
+      span.set_attribute('gen_ai.conversation.id', conversation_id) if conversation_id
       span.set_attribute('gen_ai.input.messages', JSON.generate(messages)) if cfg&.capture_content && messages
 
-      # Streaming: chunks go to the caller's proc; the returned value is not a
-      # stable Hash, so skip ALL response-side annotation.
-      return if streaming
+      # Streaming: annotate the response side from the drained accumulator.
+      return annotate_from_stream(span, accumulator, cfg) if accumulator
+
+      # A stream proc we could not wrap (e.g. accumulator build failed): the
+      # returned value is not a stable Hash, so skip response-side annotation.
+      return if stream_key_for(parameters)
       return unless response.is_a?(Hash)
 
       response_model = response['model']
@@ -79,10 +136,60 @@ module Verica
       )
     end
 
+    def annotate_from_stream(span, accumulator, cfg)
+      span.set_attribute('gen_ai.response.model', accumulator.model) if accumulator.model
+      if accumulator.usage.is_a?(Hash)
+        input_tokens = accumulator.usage['prompt_tokens']
+        output_tokens = accumulator.usage['completion_tokens']
+        span.set_attribute('gen_ai.usage.input_tokens', input_tokens) if input_tokens
+        span.set_attribute('gen_ai.usage.output_tokens', output_tokens) if output_tokens
+      end
+
+      return unless cfg&.capture_content
+
+      text = accumulator.content
+      return if text.nil? || text.empty?
+
+      span.set_attribute(
+        'gen_ai.output.messages',
+        JSON.generate([{ role: (accumulator.role || 'assistant').to_s, content: text }])
+      )
+    end
+
     def safely
       yield
     rescue StandardError
       nil
     end
+
+    # Drains a ruby-openai stream (parsed Hashes, string keys) into the pieces
+    # the span needs: the joined assistant text, the first non-nil model, the
+    # assistant role from the first delta that carries one, and the usage Hash
+    # from the final chunk (present only when the caller asks for it). Tool-call
+    # deltas are intentionally ignored in this pass.
+    class StreamAccumulator
+      attr_reader :content, :model, :role, :usage
+
+      def initialize
+        @content = +''
+        @model = nil
+        @role = nil
+        @usage = nil
+      end
+
+      def add(chunk)
+        return unless chunk.is_a?(Hash)
+
+        @model ||= chunk['model']
+        delta = chunk.dig('choices', 0, 'delta')
+        if delta.is_a?(Hash)
+          @role ||= delta['role']
+          fragment = delta['content']
+          @content << fragment if fragment.is_a?(String)
+        end
+        usage = chunk['usage']
+        @usage = usage if usage.is_a?(Hash)
+      end
+    end
   end
 end

data/lib/verica/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Verica
-  VERSION = '0.1.4'
+  VERSION = '0.1.5'
 end

data/lib/verica.rb

@@ -8,9 +8,41 @@ require 'verica/ruby_openai_wrapper'
 
 # Fail-open by contract: nothing in this module ever raises into the host app.
 module Verica
+  # Fiber-local key holding the per-request conversation override. A value of
+  # `nil` means "no override active" (fall back to the global config); any
+  # String (including '') means an override IS active for this fiber/thread.
+  CONVERSATION_KEY = :verica_conversation_override
+
   class << self
     attr_reader :config
 
+    # Scopes `gen_ai.conversation.id` to a single request/thread, overriding the
+    # global `conversation_id:` from `init`. Thread-safe (fiber-local storage),
+    # nestable, and restored on the way out even if the block raises. `id` is
+    # coerced with `to_s`; nil/empty means "no conversation attribute" for spans
+    # emitted inside the block. Returns the block's value.
+    #
+    #   Verica.with_conversation("chat-#{conversation.id}") do
+    #     client.chat(parameters: { ... })
+    #   end
+    def with_conversation(id)
+      previous = Thread.current[CONVERSATION_KEY]
+      Thread.current[CONVERSATION_KEY] = id.to_s
+      yield
+    ensure
+      Thread.current[CONVERSATION_KEY] = previous
+    end
+
+    # Resolves the conversation id both wrappers stamp on spans: the thread-local
+    # override (when a `with_conversation` block is active) wins over the global
+    # config; nil/empty resolves to nil so the attribute is omitted.
+    def conversation_id
+      override = Thread.current[CONVERSATION_KEY]
+      raw = override.nil? ? @config&.conversation_id : override
+      value = raw.to_s
+      value.empty? ? nil : value
+    end
+
     def init(**options)
       if @initialized
         warn '[verica] init called twice; ignoring the second call.'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: verica-observability
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.1.5
 platform: ruby
 authors:
 - Verica
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-03 00:00:00.000000000 Z
+date: 2026-07-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: opentelemetry-exporter-otlp