verica-observability 0.1.7 → 0.1.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 816c57a94a8a82efc43e464165b84611981c76dc6a456eb6bd359804621beddc
-  data.tar.gz: 929106f12d8e32c03de0bd9427b9babe4cf5639c5159e31d6a7f34d3d1a32d89
+  metadata.gz: 9b2286c95c84642a8961ca9521858ce47f8cdff3d764e7269a278acd6a78284c
+  data.tar.gz: bb471935256948e92255edf0b4c92ef97f245544890fe4de09b9862b92d2c092
 SHA512:
-  metadata.gz: e7242e9480405617939a9d4ab4109f5f1eb104046372009d100c458627b7f846987a34f59b0439a766d5b297244d4a11b46400062faf3cf72ea09b0f571e9f71
-  data.tar.gz: 832738007de7cab2d6ea750369609e0d94e08c5578477038018b7086df8cddcf93de574a0f7cabdff00f13d26d736855af5a61678f3bdbc7d9655c75eb16363b
+  metadata.gz: e2765905d27ac2b2d5b94f59d79ebda8fab9b42aeb9e677cd97eeff9e1fb9021567b68b249d58a65ccc423f76997fcf6274320b205b220f18d60c8c9b73acdfb
+  data.tar.gz: d1d66aa9cf309ac254c4bcfde0dadbc4ecfdbad75aa85da8f98b88ccb143f3058fea5d2586946168bdfacc7f33fc61867cb400da690b18a069fad22011851f95

data/README.md

@@ -81,6 +81,32 @@ end
 body with it and keep the return unchanged. Each thread carries its own override,
 so concurrent requests never leak conversation ids into one another.
 
+**Resend history exactly as sent.** Turns are stored as deltas: at ingest,
+Verica matches the history you resend against what previous turns already
+stored, and that match is exact (byte-identical text). If your app mutates
+prior messages between requests (for example, appending "Respond in JSON" to
+the last user message and stripping it from earlier turns when rebuilding the
+history), no prefix ever matches and every turn falls back to storing, and
+showing, the full conversation again. Keep injected instructions in the system
+prompt, or resend them exactly as originally sent.
+
+## Tags
+
+Tags land on each trace (`traces.tags`): filter the workbench by them, and bind
+criteria to them so evaluation preselects the right criteria per tag.
+
+```ruby
+Verica.init(token: ENV.fetch("VERICA_TOKEN"), tags: ["mtn-campus", "prod"])
+
+Verica.with_tags(["mentor-chat"]) do
+  client.chat(parameters: { ... })
+end
+```
+
+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.
+
 ## Streaming (`wrap_openai_compatible`)
 
 Streaming calls (a `stream:` proc in `parameters`) are fully captured: the
@@ -127,14 +153,15 @@ 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              |
-| `stream_usage:` / `VERICA_STREAM_USAGE`       | `false`    | inject `stream_options` for tokens |
-| `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`              |
+| `tags:`                                       | (none)     | global tags; per-request: `Verica.with_tags` |
+| `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

@@ -2,7 +2,7 @@
 
 module Verica
   # Config resolution: options > env vars > defaults. Pure.
-  Config = Struct.new(:token, :endpoint, :capture_content, :conversation_id, :service_name, :debug,
+  Config = Struct.new(:token, :endpoint, :capture_content, :conversation_id, :tags, :service_name, :debug,
                       :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.
@@ -21,6 +21,7 @@ module Verica
         endpoint: raw_endpoint.sub(%r{/+\z}, ''),
         capture_content: capture,
         conversation_id: options[:conversation_id],
+        tags: Array(options[:tags]).map(&:to_s).reject(&:empty?).uniq,
         service_name: options[:service_name] || env['OTEL_SERVICE_NAME'] || 'app',
         debug: options[:debug].nil? ? %w[1 true].include?(env['VERICA_DEBUG']) : options[:debug],
         # Opt-in: append `stream_options: { include_usage: true }` to streaming

data/lib/verica/openai_wrapper.rb

@@ -78,6 +78,8 @@ module Verica
         span.set_attribute('gen_ai.request.model', params[:model].to_s) if params[:model]
         conversation_id = Verica.conversation_id
         span.set_attribute('gen_ai.conversation.id', conversation_id) if conversation_id
+        tags = Verica.current_tags
+        span.set_attribute('verica.tags', JSON.generate(tags)) unless tags.empty?
 
         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

@@ -136,6 +136,8 @@ module Verica
       span.set_attribute('gen_ai.request.model', model.to_s) if model
       conversation_id = Verica.conversation_id
       span.set_attribute('gen_ai.conversation.id', conversation_id) if conversation_id
+      tags = Verica.current_tags
+      span.set_attribute('verica.tags', JSON.generate(tags)) unless tags.empty?
       span.set_attribute('gen_ai.input.messages', JSON.generate(messages)) if cfg&.capture_content && messages
 
       # Streaming: annotate the response side from the drained accumulator.

data/lib/verica/version.rb

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

data/lib/verica.rb

@@ -13,6 +13,10 @@ module Verica
   # String (including '') means an override IS active for this fiber/thread.
   CONVERSATION_KEY = :verica_conversation_override
 
+  # Fiber-local key holding the per-request tag scope (Array<String>); nil means
+  # no scope is active. Scopes UNION with the global config tags.
+  TAGS_KEY = :verica_tags_scope
+
   class << self
     attr_reader :config
 
@@ -43,6 +47,27 @@ module Verica
       value.empty? ? nil : value
     end
 
+    # Adds tags to every span emitted inside the block, UNIONED with the global
+    # `tags:` from `init` (global first, dedup, `to_s` coercion). Thread-safe
+    # (fiber-local), nestable (nested scopes accumulate), restored on the way
+    # out even if the block raises. Returns the block's value.
+    #
+    #   Verica.with_tags(["mentor-chat"]) do
+    #     client.chat(parameters: { ... })
+    #   end
+    def with_tags(tags)
+      previous = Thread.current[TAGS_KEY]
+      Thread.current[TAGS_KEY] = merge_tags(previous || [], tags)
+      yield
+    ensure
+      Thread.current[TAGS_KEY] = previous
+    end
+
+    # Global config tags ∪ the active thread-local scope, deduped in order.
+    def current_tags
+      merge_tags(@config&.tags || [], Thread.current[TAGS_KEY] || [])
+    end
+
     def init(**options)
       if @initialized
         warn '[verica] init called twice; ignoring the second call.'
@@ -113,5 +138,16 @@ module Verica
       @initialized = false
       @config = nil
     end
+
+    private
+
+    def merge_tags(base, extra)
+      out = base.dup
+      Array(extra).each do |t|
+        s = t.to_s
+        out << s unless s.empty? || out.include?(s)
+      end
+      out
+    end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: verica-observability
 version: !ruby/object:Gem::Version
-  version: 0.1.7
+  version: 0.1.8
 platform: ruby
 authors:
 - Verica