ask-opentelemetry 0.1.1 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d507a221f80f69247296fbd1d633b2e1e505771cbbc30f2eead059408bf276db
-  data.tar.gz: f666f00ebed72dbeadacda333aa95f17e9af5ffa2370d568d6255947764db6aa
+  metadata.gz: 353c1cc499049b3465c9df2f6d0d97e728dbb393a7feb824e95219ebd4839e19
+  data.tar.gz: ebdd2a7ac236e8cb7a11c020674ff13515d7d517f70338ac329fe6ea2a39d760
 SHA512:
-  metadata.gz: f3088109bac83c159ecfd88cc0c1a8eaa8bf2225aafd61e55db4f0d25ec59333603d4ad547acdd770d94d567d5198c7b7e3e74e0be63bcb36ccb46622176fb9f
-  data.tar.gz: '080c03b38ecd18b6890d72fd0778715d7aa389b5f19dcd8e185273826890389776df4d9ab2203174e55ca7f3c2313eb30fab6f5c3463d873313d5b735e001cce'
+  metadata.gz: 3f5c948e46acbad10230f443ee5807e33b8bc833a1dd40d853e994ea58f943e1a4e2d0db7235e1fb3b87afb360670741e5697584346ff2ffd74ddce86781f190
+  data.tar.gz: 8153b315f9fcab444a8e56f8ae0d74b669a661f9a75d7c35f37860e3a4b03276db86efd187847ba7b70f312274a34945c48c839a3264628c583341e75323ba63

data/CHANGELOG.md

@@ -1,3 +1,19 @@
+## [0.1.3] - 2026-08-06
+
+### Fixed
+- `llm.duration_ms` was microsecond values labeled as milliseconds
+  (`(event.duration * 1000)` — event.duration is already in ms; a 0.2s call
+  showed 203052). Now `event.duration.round(2)` — real milliseconds.
+
+## [0.1.2] - 2026-08-06
+
+### Fixed
+- `llm.input_tokens`/`llm.output_tokens` span attributes read from the nested
+  `usage` payload hash (ask-agent enriches it after the call returns; the
+  instrumenter shallow-copies the top-level payload). Top-level keys still
+  work for other emitters. `llm.duration_ms` now reflects the real LLM call
+  duration thanks to the ask-agent event fix.
+
 ## [0.1.1] - 2026-06-25
 
 ### Changed

data/README.md

@@ -5,10 +5,10 @@
 
 OpenTelemetry tracing for the ask-rb ecosystem. Subscribes to
 `ask-instrumentation` events and creates OpenTelemetry spans for chat
-completions, tool calls, embeddings, and image generation.
-
-Works with any OpenTelemetry-compatible backend: Langfuse, Datadog, Honeycomb,
-Jaeger, Arize Phoenix, and more.
+completions, tool calls, embeddings, and image generation. Backend-agnostic:
+the exporter is configured with the standard OpenTelemetry SDK, so spans go
+to any OpenTelemetry-compatible backend (Langfuse, Datadog, Honeycomb, Jaeger,
+Arize Phoenix, and more).
 
 ## Installation
 
@@ -22,66 +22,37 @@ gem "ask-instrumentation"
 ```ruby
 require "ask/open_telemetry"
 
-# Subscribe to all ask events and create OpenTelemetry spans
 Ask::OpenTelemetry.install
 ```
 
-### In Rails
+That's it. Every `Ask::Instrumentation` event is now wrapped in a span. The
+call is idempotent; subsequent calls are no-ops.
 
-The Railtie auto-installs — no manual setup required:
-
-```ruby
-# Gemfile
-gem "ask-opentelemetry"
-gem "ask-instrumentation"
-```
-
-That's it. Spans are created automatically for every LLM operation.
+In a Rails app, the Railtie calls `Ask::OpenTelemetry.install` automatically:
+no manual setup required.
 
 ## Spans Created
 
-| Event | Span Name | Key Attributes |
-|---|---|---|
-| `chat.ask` | `llm.chat` | provider, model, input_tokens, output_tokens, duration_ms |
-| `chat.stream.ask` | `llm.chat` | provider, model, input_tokens, output_tokens, duration_ms |
-| `tool.ask` | `llm.tool` | provider, tool, tool_args |
-| `embedding.ask` | `llm.embedding` | provider, model, input_tokens |
-| `image.ask` | `llm.image` | provider, model, image.size, duration_ms |
-
-### Standard Attributes
-
-All spans include:
+| Event | Span |
+|---|---|
+| `chat.ask`, `chat.stream.ask` | `llm.chat` |
+| `tool.ask` | `llm.tool` |
+| `embedding.ask` | `llm.embedding` |
+| `image.ask` | `llm.image` |
 
-- `llm.provider` — The LLM provider (e.g., `openai`, `anthropic`)
-- `llm.model` — The model identifier (e.g., `gpt-4`, `claude-3`)
-- `llm.duration_ms` — The duration of the LLM operation in milliseconds
-- `llm.input_tokens` — Input token count (when available)
-- `llm.output_tokens` — Output token count (when available)
+Span attributes use the `llm.*` namespace: `llm.provider`, `llm.model`,
+`llm.input_tokens`, `llm.output_tokens`, `llm.duration_ms`, `llm.tool`,
+`llm.tool_args`, and `llm.image.size` when present. Any context set via
+`Ask::Instrumentation.with_metadata` is forwarded as `llm.metadata.*`
+attributes.
 
-### Metadata Attributes
+## Configuration
 
-Any context set via `Ask::Instrumentation.with_metadata` is forwarded as
-`llm.metadata.*` attributes:
+`Ask::OpenTelemetry.install` is the entire public API; there is no exporter
+configuration on the gem itself. Configure the exporter once with the standard
+OpenTelemetry SDK before calling `install`:
 
 ```ruby
-Ask::Instrumentation.with_metadata(user_id: 42, session_id: "abc") do
-  # The resulting span has:
-  #   llm.metadata.user_id = 42
-  #   llm.metadata.session_id = "abc"
-end
-```
-
-## Backend Examples
-
-### Langfuse
-
-[Langfuse](https://langfuse.com) provides LLM observability (cost tracking,
-evaluations, prompt management) via OpenTelemetry.
-
-**Using Langfuse Cloud:**
-
-```ruby
-require "ask/open_telemetry"
 require "opentelemetry-sdk"
 require "opentelemetry-exporter-otlp"
 
@@ -89,12 +60,7 @@ OpenTelemetry::SDK.configure do |c|
   c.service_name = "my-app"
   c.add_span_processor(
     OpenTelemetry::SDK::Trace::Export::BatchSpanProcessor.new(
-      OpenTelemetry::Exporter::OTLP::Exporter.new(
-        endpoint: "https://cloud.langfuse.com/api/public/otel/v1/traces",
-        headers: {
-          "Authorization" => "Basic #{Base64.strict_encode64("#{LANGFUSE_PUBLIC_KEY}:#{LANGFUSE_SECRET_KEY}")}"
-        }
-      )
+      OpenTelemetry::Exporter::OTLP::Exporter.new(endpoint: "https://otlp.example.com")
     )
   )
 end
@@ -102,87 +68,17 @@ end
 Ask::OpenTelemetry.install
 ```
 
-**Using Langfuse Self-Hosted:**
+## Full documentation
 
-```ruby
-OpenTelemetry::SDK.configure do |c|
-  c.service_name = "my-app"
-  c.add_span_processor(
-    OpenTelemetry::SDK::Trace::Export::BatchSpanProcessor.new(
-      OpenTelemetry::Exporter::OTLP::Exporter.new(
-        endpoint: "https://your-instance.langfuse.com/api/public/otel/v1/traces",
-        headers: {
-          "Authorization" => "Basic #{Base64.strict_encode64("#{LANGFUSE_PUBLIC_KEY}:#{LANGFUSE_SECRET_KEY}")}"
-        }
-      )
-    )
-  )
-end
-```
-
-### Datadog
-
-```ruby
-require "ask/open_telemetry"
-require "opentelemetry-sdk"
-require "opentelemetry-exporter-otlp"
-
-OpenTelemetry::SDK.configure do |c|
-  c.service_name = "my-app"
-  c.add_span_processor(
-    OpenTelemetry::SDK::Trace::Export::BatchSpanProcessor.new(
-      OpenTelemetry::Exporter::OTLP::Exporter.new(
-        endpoint: "https://otlp.datadoghq.com",
-        headers: { "DD-API-KEY" => ENV["DD_API_KEY"] }
-      )
-    )
-  )
-end
-
-Ask::OpenTelemetry.install
-```
-
-### Honeycomb
-
-```ruby
-require "ask/open_telemetry"
-require "opentelemetry-sdk"
-require "opentelemetry-exporter-otlp"
-
-OpenTelemetry::SDK.configure do |c|
-  c.service_name = "my-app"
-  c.add_span_processor(
-    OpenTelemetry::SDK::Trace::Export::BatchSpanProcessor.new(
-      OpenTelemetry::Exporter::OTLP::Exporter.new(
-        endpoint: "https://api.honeycomb.io:443",
-        headers: { "x-honeycomb-team" => ENV["HONEYCOMB_API_KEY"] }
-      )
-    )
-  )
-end
-
-Ask::OpenTelemetry.install
-```
-
-## API
-
-### `.install`
-
-Subscribe to all `.ask` events and start creating spans. Idempotent — calling
-multiple times only subscribes once.
-
-```ruby
-Ask::OpenTelemetry.install
-```
+The full ask-rb documentation lives at https://ask-rb.github.io/ask-docs.
+https://ask-rb.github.io/ask-docs/production/opentelemetry covers
+ask-opentelemetry in depth, including per-backend setup examples. API
+reference: https://ask-rb.github.io/ask-docs/reference/api.
 
 ## Development
 
-```bash
-git clone https://github.com/ask-rb/ask-opentelemetry.git
-cd ask-opentelemetry
 bundle install
 bundle exec rake test
-```
 
 ## License
 

data/lib/ask/open_telemetry/subscriber.rb

@@ -29,7 +29,10 @@ module Ask
         return unless span_name
 
         tracer.in_span(span_name, attributes: attributes_for(event)) do |span|
-          span.set_attribute("llm.duration_ms", (event.duration * 1000).round(2))
+          # event.duration is already MILLISECONDS — multiplying by 1000
+          # produced microsecond values labeled as ms (a 0.2s call showed
+          # llm_duration_ms=203052).
+          span.set_attribute("llm.duration_ms", event.duration.round(2))
         end
       end
 
@@ -44,9 +47,12 @@ module Ask
         attrs["llm.provider"]     = payload[:provider] if payload[:provider]
         attrs["llm.model"]        = payload[:model]    if payload[:model]
 
-        # Token tracking (when available)
-        attrs["llm.input_tokens"]  = payload[:input_tokens]  if payload[:input_tokens]
-        attrs["llm.output_tokens"] = payload[:output_tokens] if payload[:output_tokens]
+        # Token tracking (when available). Chat events emitted by ask-agent
+        # enrich a shared nested +usage+ hash after the call returns (tokens
+        # are only known then); other emitters pass them at the top level.
+        usage = payload[:usage] || payload
+        attrs["llm.input_tokens"]  = usage[:input_tokens]  if usage[:input_tokens]
+        attrs["llm.output_tokens"] = usage[:output_tokens] if usage[:output_tokens]
 
         # Tool-specific
         attrs["llm.tool"]    = payload[:tool_name] if payload[:tool_name]

data/lib/ask/open_telemetry/version.rb

@@ -1,5 +1,5 @@
 module Ask
   module OpenTelemetry
-    VERSION = "0.1.1"
+    VERSION = "0.1.3"
   end
 end

data/lib/ask/open_telemetry.rb

@@ -2,6 +2,11 @@ require "ask/instrumentation"
 require "opentelemetry-api"
 require_relative "open_telemetry/version"
 
+# Rails discovers gem railties only when they are required, so load the
+# railtie from the entry file once Rails itself is on the stack (the
+# documented pattern: "require my_gem/railtie if defined?(Rails::Railtie)").
+require_relative "open_telemetry/railtie" if defined?(Rails::Railtie)
+
 module Ask
   # OpenTelemetry tracing for the ask-rb ecosystem.
   #

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ask-opentelemetry
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.3
 platform: ruby
 authors:
 - Kaka Ruto