verica-observability 0.1.8 → 0.1.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9b2286c95c84642a8961ca9521858ce47f8cdff3d764e7269a278acd6a78284c
-  data.tar.gz: bb471935256948e92255edf0b4c92ef97f245544890fe4de09b9862b92d2c092
+  metadata.gz: 87dae5be3d2d8bb4abc605dce2d2338735d12cc3686ed92e9cb3cb185beb1c19
+  data.tar.gz: 243179f8c98115b7c59cf1f6089abb2a9ea2eec90e666407f006c6c510d18f6b
 SHA512:
-  metadata.gz: e2765905d27ac2b2d5b94f59d79ebda8fab9b42aeb9e677cd97eeff9e1fb9021567b68b249d58a65ccc423f76997fcf6274320b205b220f18d60c8c9b73acdfb
-  data.tar.gz: d1d66aa9cf309ac254c4bcfde0dadbc4ecfdbad75aa85da8f98b88ccb143f3058fea5d2586946168bdfacc7f33fc61867cb400da690b18a069fad22011851f95
+  metadata.gz: 400f082d4df041fa02d68087a29fe15e7716fc2c69cabd04a4ffaf6e00843d571cd99a11e4c4ca63daed5310e2e93bbf2474ec9e7657bd211ee9a12a973b5329
+  data.tar.gz: 99859f6abe8329b733074a913e928b5e3839c01b95b4acc65521c8b730db54521fb034edcb2b5163f954cfea2234580c7aacdcc5580110cd2d53c11ff95644c2

data/README.md

@@ -107,6 +107,32 @@ Per-request tags UNION with the globals (dedup, order preserved); nested blocks
 accumulate; the scope is thread-local and restored even if the block raises.
 Values are coerced with `to_s`; the server caps at 20 tags x 120 chars.
 
+## Agent loops
+
+An agent run is more than one LLM call: it interleaves model turns with tool
+executions. `Verica.with_span(name)` opens `name` as the active span for the
+block, so wrapped-client calls and nested `with_span`/`with_tool` blocks become
+its children. The whole run lands as ONE trace with a span tree instead of a
+handful of disconnected spans. `Verica.with_tool(name)` is the same, plus the
+OTel GenAI semconv tool attributes (`gen_ai.operation.name = execute_tool`,
+`gen_ai.tool.name = name`), so tool spans are matchable by `span_check`.
+
+```ruby
+Verica.with_span('agent.run') do
+  client.chat.completions.create(model: 'gpt-4o-mini', messages: plan_messages)
+  weather = Verica.with_tool('lookup_weather') { lookup_weather('Cordoba') }
+  client.chat.completions.create(model: 'gpt-4o-mini', messages: reply_messages(weather))
+end
+```
+
+The span name is `name` verbatim (that is what `span_check` patterns match).
+Both return the block's value, so you can wrap an existing method body and keep
+its return unchanged. An exception raised inside the block marks the span as
+error and propagates untouched (rescue it outside if the loop should continue).
+Before `Verica.init` both are transparent no-ops that still run the block, so
+instrumentation never changes control flow. See `examples/agent.rb` for a full
+two-call, two-tool run (one tool fails on purpose).
+
 ## Streaming (`wrap_openai_compatible`)
 
 Streaming calls (a `stream:` proc in `parameters`) are fully captured: the

data/lib/verica/version.rb

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

data/lib/verica.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require 'json'
 require 'verica/version'
 require 'verica/config'
 require 'verica/providers'
@@ -68,6 +69,27 @@ module Verica
       merge_tags(@config&.tags || [], Thread.current[TAGS_KEY] || [])
     end
 
+    # Opens `name` as the active span for the block: wrapped-client calls and
+    # nested with_span/with_tool inside become children, so a whole agent run
+    # lands as ONE trace with a span tree. The span name is `name` verbatim
+    # (what span_check patterns match). Exceptions mark the span as error and
+    # propagate untouched. No-op before init (fail-open). Returns the block's
+    # value.
+    #
+    #   Verica.with_span("agent.run") { ...loop... }
+    def with_span(name, &block)
+      manual_span(name.to_s, {}, &block)
+    end
+
+    # with_span + the OTel GenAI semconv tool attributes
+    # (gen_ai.operation.name = execute_tool, gen_ai.tool.name).
+    #
+    #   Verica.with_tool("search_exercises") { execute(...) }
+    def with_tool(name, &block)
+      n = name.to_s
+      manual_span(n, { 'gen_ai.operation.name' => 'execute_tool', 'gen_ai.tool.name' => n }, &block)
+    end
+
     def init(**options)
       if @initialized
         warn '[verica] init called twice; ignoring the second call.'
@@ -149,5 +171,28 @@ module Verica
       end
       out
     end
+
+    # Ruby has no stamping span processor (the wrappers stamp per span), so
+    # manual spans stamp conversation/tags themselves for cross-SDK parity.
+    def manual_span(name, attributes)
+      tracer = @initialized && safely { OpenTelemetry.tracer_provider.tracer('verica-observability', Verica::VERSION) }
+      return yield unless tracer
+
+      attrs = attributes.dup
+      safely do
+        cid = conversation_id
+        attrs['gen_ai.conversation.id'] = cid if cid
+        tags = current_tags
+        attrs['verica.tags'] = JSON.generate(tags) unless tags.empty?
+      end
+      # in_span records the exception, sets error status, re-raises, finishes.
+      tracer.in_span(name, attributes: attrs) { yield }
+    end
+
+    def safely
+      yield
+    rescue StandardError
+      nil
+    end
   end
 end

metadata

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