verica-observability 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5a673e65acb78166ecd02e7e1f71e732b9b5a94266b13b5439847323a754d0fd
+  data.tar.gz: 6ad1429c62b84d071393c1c906852ec63d1d1c09e5bf9e003f74ae0efe0f779c
+SHA512:
+  metadata.gz: 314db6f26e34ed191181439756db2e2a05c42be85cb39061d7fe9c18d396c6def8cf1f1cf33e6253e1ac79e7aa4fc17df030dd386ccd8a3bb6907bfc5bfb5586
+  data.tar.gz: 5c093204aee3f513664aa1b8b7ad64d2c1f63308fd209bbed5c7c03e2eaee1f4bf571071ddb4d8f629a52b6993826e2558d87a18d51ded69a7716652859cbf08

data/README.md

@@ -0,0 +1,71 @@
+# verica-observability
+
+Two-line LLM tracing for [Verica](https://verica.app). The official `openai`
+gem has no auto-instrumentation anywhere: this gem ships it.
+
+## Install
+
+```bash
+gem install verica-observability
+```
+
+## Use (official `openai` gem)
+
+```ruby
+require 'verica'
+
+Verica.init(token: ENV['VERICA_TOKEN'], endpoint: 'https://<your-verica-host>')
+client = Verica.wrap_openai(OpenAI::Client.new)
+# use `client` exactly like the original; chat completions are traced.
+```
+
+## Use (community `ruby-openai` gem, alexrudall)
+
+The community [`ruby-openai`](https://github.com/alexrudall/ruby-openai) gem has
+a different API than the official gem: `client.chat(parameters: { ... })`
+returning a plain Hash. It gets its own wrapper.
+
+```ruby
+require 'verica'
+
+Verica.init(token: ENV['VERICA_TOKEN'], endpoint: 'https://<your-verica-host>')
+client = Verica.wrap_ruby_openai(OpenAI::Client.new)
+
+client.chat(parameters: {
+  model: 'gpt-4o-mini',
+  messages: [{ role: 'user', content: 'Hello!' }]
+})
+```
+
+Streaming calls (a `stream:` proc in `parameters`) pass through untouched and
+are traced with request-side attributes only (the streamed response is not a
+stable Hash to read the model or usage from).
+
+Use `wrap_openai` for the official `openai` gem and `wrap_ruby_openai` for
+`ruby-openai`. The two gems' APIs are not interchangeable, so neither are the
+wrappers.
+
+## Use (RubyLLM)
+
+With RubyLLM plus its thoughtbot OpenTelemetry instrumentation, `Verica.init`
+alone is enough: the spans it emits are exported to Verica.
+
+## Serverless
+
+Call `Verica.flush` (or `Verica.shutdown`) before the runtime freezes so the
+span batch is exported.
+
+## Options
+
+| Option / env var                              | Default    | Notes                           |
+| --------------------------------------------- | ---------- | ------------------------------- |
+| `token:` / `VERICA_TOKEN`                     | (required) | ingest-scoped API token         |
+| `endpoint:` / `VERICA_ENDPOINT`               | (required) | your Verica origin              |
+| `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               |
+
+Fail-open by design: if the endpoint is down or the token is invalid, spans are
+dropped and your app is never affected. Export errors are silent unless `debug`
+is on.

data/lib/verica/config.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+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
+    def self.resolve(options, env)
+      token = (options[:token] || env['VERICA_TOKEN'] || '').to_s
+      raw_endpoint = (options[:endpoint] || env['VERICA_ENDPOINT'] || '').to_s
+      missing = []
+      missing << 'token' if token.empty?
+      missing << 'endpoint' if raw_endpoint.empty?
+      return [nil, missing] unless missing.empty?
+
+      capture = options[:capture_content]
+      capture = env.key?('VERICA_CAPTURE_CONTENT') ? %w[1 true].include?(env['VERICA_CAPTURE_CONTENT']) : true if capture.nil?
+
+      [new(
+        token: token,
+        endpoint: raw_endpoint.sub(%r{/+\z}, ''),
+        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]
+      ), []]
+    end
+  end
+end

data/lib/verica/openai_wrapper.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Verica
+  # The official `openai` gem has no auto-instrumentation, so Verica ships its
+  # own thin decorator: everything delegates to the real client; only
+  # chat.completions.create is intercepted to emit ONE gen_ai.* span (pinned
+  # semconv, the exact attributes the Verica normalizer accepts). Fail-open:
+  # instrumentation errors never reach the caller; provider errors always do.
+  class OpenAIWrapper
+    def initialize(client)
+      @client = client
+    end
+
+    def chat
+      ChatProxy.new(@client.chat)
+    end
+
+    def method_missing(name, ...)
+      @client.public_send(name, ...)
+    end
+
+    def respond_to_missing?(name, include_private = false)
+      @client.respond_to?(name, include_private) || super
+    end
+
+    class ChatProxy
+      def initialize(chat) = @chat = chat
+
+      def completions
+        CompletionsProxy.new(@chat.completions)
+      end
+
+      def method_missing(name, ...)
+        @chat.public_send(name, ...)
+      end
+
+      def respond_to_missing?(name, include_private = false)
+        @chat.respond_to?(name, include_private) || super
+      end
+    end
+
+    class CompletionsProxy
+      def initialize(completions) = @completions = completions
+
+      def create(**params)
+        span = safely do
+          tracer = OpenTelemetry.tracer_provider.tracer('verica-observability', Verica::VERSION)
+          tracer.start_span("chat #{params[:model]}", kind: :client)
+        end
+        begin
+          response = @completions.create(**params)
+          safely { annotate(span, params, response) } if span
+          response
+        rescue StandardError => e
+          safely { span&.status = OpenTelemetry::Trace::Status.error(e.message) }
+          raise
+        ensure
+          safely { span&.finish }
+        end
+      end
+
+      def method_missing(name, ...)
+        @completions.public_send(name, ...)
+      end
+
+      def respond_to_missing?(name, include_private = false)
+        @completions.respond_to?(name, include_private) || super
+      end
+
+      private
+
+      def annotate(span, params, response)
+        cfg = Verica.config
+        span.set_attribute('gen_ai.operation.name', 'chat')
+        span.set_attribute('gen_ai.provider.name', 'openai')
+        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
+
+        model = response.respond_to?(:model) ? response.model : nil
+        span.set_attribute('gen_ai.response.model', model) if model
+        usage = response.respond_to?(:usage) ? response.usage : nil
+        if usage
+          input = usage.respond_to?(:prompt_tokens) ? usage.prompt_tokens : nil
+          output = usage.respond_to?(:completion_tokens) ? usage.completion_tokens : nil
+          span.set_attribute('gen_ai.usage.input_tokens', input) if input
+          span.set_attribute('gen_ai.usage.output_tokens', output) if output
+        end
+
+        return unless cfg&.capture_content
+
+        span.set_attribute('gen_ai.input.messages', JSON.generate(params[:messages])) if params[:messages]
+        choices = response.respond_to?(:choices) ? response.choices : nil
+        message = choices&.first.respond_to?(:message) ? choices.first.message : nil
+        return unless message
+
+        span.set_attribute(
+          'gen_ai.output.messages',
+          JSON.generate([{ role: message.role.to_s, content: message.content }])
+        )
+      end
+
+      def safely
+        yield
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/verica/ruby_openai_wrapper.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Verica
+  # The community `ruby-openai` gem (alexrudall) has a different API than the
+  # official `openai` gem: `client.chat(parameters: { model:, messages: })`
+  # returning a plain Hash (string keys) instead of typed objects. Both gems
+  # define OpenAI::Client, so an app uses one or the other; this thin decorator
+  # is the ruby-openai counterpart of OpenAIWrapper. Everything delegates to the
+  # real client; only `chat` is intercepted to emit ONE gen_ai.* span with the
+  # SAME pinned semconv the Verica normalizer accepts. Fail-open: instrumentation
+  # errors never reach the caller; provider errors always do.
+  class RubyOpenAIWrapper
+    def initialize(client)
+      @client = client
+    end
+
+    def chat(parameters: {})
+      model = parameters[:model] || parameters['model']
+      span = safely do
+        tracer = OpenTelemetry.tracer_provider.tracer('verica-observability', Verica::VERSION)
+        tracer.start_span("chat #{model}", kind: :client)
+      end
+      begin
+        response = @client.chat(parameters: parameters)
+        safely { annotate(span, parameters, response) } if span
+        response
+      rescue StandardError => e
+        safely { span&.status = OpenTelemetry::Trace::Status.error(e.message) }
+        raise
+      ensure
+        safely { span&.finish }
+      end
+    end
+
+    def method_missing(name, ...)
+      @client.public_send(name, ...)
+    end
+
+    def respond_to_missing?(name, include_private = false)
+      @client.respond_to?(name, include_private) || super
+    end
+
+    private
+
+    def annotate(span, parameters, response)
+      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', 'openai')
+      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
+      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
+      return unless response.is_a?(Hash)
+
+      response_model = response['model']
+      span.set_attribute('gen_ai.response.model', response_model) if response_model
+      input_tokens = response.dig('usage', 'prompt_tokens')
+      output_tokens = response.dig('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
+
+      return unless cfg&.capture_content
+
+      message = response.dig('choices', 0, 'message')
+      return unless message.is_a?(Hash)
+
+      span.set_attribute(
+        'gen_ai.output.messages',
+        JSON.generate([{ role: message['role'].to_s, content: message['content'] }])
+      )
+    end
+
+    def safely
+      yield
+    rescue StandardError
+      nil
+    end
+  end
+end

data/lib/verica/version.rb

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

data/lib/verica.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require 'verica/version'
+require 'verica/config'
+require 'verica/openai_wrapper'
+require 'verica/ruby_openai_wrapper'
+
+# Fail-open by contract: nothing in this module ever raises into the host app.
+module Verica
+  class << self
+    attr_reader :config
+
+    def init(**options)
+      if @initialized
+        warn '[verica] init called twice; ignoring the second call.'
+        return true
+      end
+
+      cfg, missing = Config.resolve(options, ENV)
+      if cfg.nil?
+        warn "[verica] missing #{missing.join(' and ')}; tracing is disabled."
+        return false
+      end
+
+      begin
+        require 'logger'
+        require 'opentelemetry/sdk'
+        require 'opentelemetry-exporter-otlp'
+
+        # Spec §5: export errors (401, network) must not spam the host app's
+        # logs; OTel Ruby reports them through OpenTelemetry.logger.
+        OpenTelemetry.logger = Logger.new(IO::NULL) unless cfg.debug
+
+        OpenTelemetry::SDK.configure do |c|
+          c.service_name = cfg.service_name
+          c.add_span_processor(
+            OpenTelemetry::SDK::Trace::Export::BatchSpanProcessor.new(
+              OpenTelemetry::Exporter::OTLP::Exporter.new(
+                endpoint: "#{cfg.endpoint}/v1/traces",
+                headers: { 'Authorization' => "Bearer #{cfg.token}" }
+              )
+            )
+          )
+        end
+        @config = cfg
+        @initialized = true
+        true
+      rescue StandardError => e
+        warn "[verica] init failed; tracing is disabled.#{cfg.debug ? " #{e.message}" : ''}"
+        false
+      end
+    end
+
+    # Wraps the official `openai` gem client so chat completions emit traces.
+    def wrap_openai(client)
+      OpenAIWrapper.new(client)
+    end
+
+    # Wraps the community `ruby-openai` gem (alexrudall) client so its
+    # `chat(parameters:)` calls emit traces. Its API and Hash responses differ
+    # from the official gem, so it needs its own wrapper (not interchangeable).
+    def wrap_ruby_openai(client)
+      RubyOpenAIWrapper.new(client)
+    end
+
+    def flush
+      OpenTelemetry.tracer_provider.force_flush if @initialized
+    rescue StandardError
+      nil
+    end
+
+    def shutdown
+      OpenTelemetry.tracer_provider.shutdown if @initialized
+    rescue StandardError
+      nil
+    ensure
+      @initialized = false
+      @config = nil
+    end
+  end
+end

metadata

@@ -0,0 +1,76 @@
+--- !ruby/object:Gem::Specification
+name: verica-observability
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Verica
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-07-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: opentelemetry-exporter-otlp
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.29'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.29'
+- !ruby/object:Gem::Dependency
+  name: opentelemetry-sdk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+description: init(token) and your OpenAI calls land as evaluable traces in Verica.
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/verica.rb
+- lib/verica/config.rb
+- lib/verica/openai_wrapper.rb
+- lib/verica/ruby_openai_wrapper.rb
+- lib/verica/version.rb
+homepage: https://verica.app
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Two-line LLM tracing for Verica.
+test_files: []