Add with_otel_attributes for custom observation attributes (#21)

Allows setting arbitrary OpenTelemetry attributes on chat spans or
traces via `with_otel_attributes`. Values can be static or callables
(Procs/ lambdas) that are evaluated after each completion for access to
response data.

Author: clarissalimab

README.md

@@ -59,6 +59,32 @@ When enabled, the following attributes are added to chat spans:
 > [!WARNING]
 > Captured content may include sensitive or personally identifiable information (PII). Use with caution in production environments.
 
+### Custom attributes
+
+Use `with_otel_attributes` to add arbitrary attributes to the span for each request. This is useful for adding per-request metadata like Langfuse prompt linking or trace-level tags:
+
+```ruby
+chat = RubyLLM.chat
+chat.with_otel_attributes(
+  "langfuse.observation.prompt.name" => "supplement-assistant",
+  "langfuse.observation.prompt.version" => 1,
+  "langfuse.trace.tags" => ["vitamins"],
+  "langfuse.trace.metadata" => { category: "health" }.to_json
+)
+chat.ask("What are the side effects of Vitamin D3?")
+```
+
+Values can also be callables (Procs/lambdas) that are evaluated after each completion, giving access to response data:
+
+```ruby
+chat.with_otel_attributes(
+  "langfuse.observation.prompt.name" => "supplement-assistant",
+  "langfuse.observation.output" => -> { chat.messages.last&.content.to_s }
+)
+```
+
+Attributes persist across calls on the same chat instance and the method returns `self` for chaining.
+
 ## What's traced?
 
 | Feature | Status |
@@ -68,8 +94,8 @@ When enabled, the following attributes are added to chat spans:
 | Error handling | Supported |
 | Opt-in input/output content capture | Supported |
 | Conversation tracking (`gen_ai.conversation.id`) | Planned |
-| System instructions capture | Planned |
-| Custom attributes on traces and spans | Planned |
+| System instructions capture | Supported (via `capture_content`) |
+| Custom attributes on traces and spans | Supported (via `with_otel_attributes`) |
 | Embeddings | Planned |
 | Streaming | Planned |
 

example/trace_demonstration_with_langfuse.rb

@@ -36,6 +36,10 @@
 
 chat = RubyLLM.chat
 chat.with_instructions("You are a helpful assistant that provides concise answers.")
+chat.with_otel_attributes(
+  "langfuse.observation.prompt.name" => "helpful-assistant",
+  "langfuse.observation.prompt.version" => 1
+)
 response = chat.ask("What is the meaning of life?")
 puts "\nResponse: #{response.content}"
 

example/trace_demonstration_with_langfuse_and_tools.rb

@@ -46,6 +46,10 @@ def execute(expression:)
 chat = RubyLLM.chat
 chat.with_instructions("You are a helpful assistant that provides concise answers.")
 chat.with_tool(Calculator)
+chat.with_otel_attributes(
+  "langfuse.observation.prompt.name" => "helpful-assistant",
+  "langfuse.observation.prompt.version" => 1
+)
 response = chat.ask("Use the calculator tool to compute 123 * 456")
 puts "\nResponse: #{response.content}"
 response = chat.ask("Use the tool again to compute 789 + 1011")

example/trace_demonstration_with_langfuse_ingredient_search.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require "bundler/inline"
+
+gemfile(true) do
+  source "https://rubygems.org"
+  gem "ruby_llm"
+  gem "opentelemetry-api"
+  gem "opentelemetry-sdk"
+  gem "opentelemetry-exporter-otlp"
+  gem "opentelemetry-instrumentation-ruby_llm", path: "../"
+  gem "base64"
+  gem "dotenv"
+end
+
+require "base64"
+require "dotenv/load"
+
+credentials = Base64.strict_encode64("#{ENV['LANGFUSE_PUBLIC_KEY']}:#{ENV['LANGFUSE_SECRET_KEY']}")
+
+OpenTelemetry::SDK.configure do |c|
+  c.service_name = "ruby_llm-demo"
+  c.add_span_processor(
+    OpenTelemetry::SDK::Trace::Export::BatchSpanProcessor.new(
+      OpenTelemetry::Exporter::OTLP::Exporter.new(
+        endpoint: "https://us.cloud.langfuse.com/api/public/otel/v1/traces",
+        headers: { "Authorization" => "Basic #{credentials}" }
+      )
+    )
+  )
+  c.use "OpenTelemetry::Instrumentation::RubyLLM", capture_content: true
+end
+
+RubyLLM.configure do |c|
+  c.openai_api_key = ENV["OPENAI_API_KEY"]
+  c.default_model = "gpt-5-nano"
+end
+
+INGREDIENT_DATABASE = {
+  "vitamin d3" => {
+    name: "Vitamin D3 (Cholecalciferol)",
+    common_doses: "1,000-5,000 IU daily",
+    side_effects: ["Nausea", "Vomiting", "Constipation", "Loss of appetite", "Excessive thirst", "Frequent urination", "Kidney stones (at very high doses)"],
+    interactions: ["Corticosteroids", "Orlistat", "Statins", "Thiazide diuretics"],
+    notes: "Fat-soluble vitamin. Toxicity risk at sustained doses above 10,000 IU/day."
+  },
+  "magnesium glycinate" => {
+    name: "Magnesium Glycinate",
+    common_doses: "200-400 mg daily",
+    side_effects: ["Diarrhea", "Nausea", "Abdominal cramping"],
+    interactions: ["Antibiotics (tetracyclines, quinolones)", "Bisphosphonates", "Diuretics"],
+    notes: "Better absorbed and gentler on the stomach than magnesium oxide."
+  },
+  "zinc" => {
+    name: "Zinc",
+    common_doses: "15-30 mg daily",
+    side_effects: ["Nausea", "Metallic taste", "Headache", "Copper deficiency (long-term use)"],
+    interactions: ["Antibiotics", "Penicillamine", "Copper supplements"],
+    notes: "Best taken with food to reduce nausea. Long-term use above 40 mg/day may deplete copper."
+  }
+}
+
+class SearchForIngredientDetails < RubyLLM::Tool
+  description "Searches a database for detailed information about a supplement ingredient, including side effects, interactions, and dosage"
+  param :ingredient_name, type: "string", desc: "The name of the ingredient to search for (e.g., 'vitamin d3', 'magnesium glycinate')"
+
+  def execute(ingredient_name:)
+    key = ingredient_name.downcase.strip
+    match = INGREDIENT_DATABASE.find { |k, _| key.include?(k) || k.include?(key) }
+
+    if match
+      _, details = match
+      details.map { |k, v| "#{k}: #{Array(v).join(', ')}" }.join("\n")
+    else
+      "No information found for '#{ingredient_name}'. Available ingredients: #{INGREDIENT_DATABASE.keys.join(', ')}"
+    end
+  end
+end
+
+chat = RubyLLM.chat
+chat.with_instructions("You are a knowledgeable health supplement assistant. Use the search tool to look up ingredient details before answering questions.")
+chat.with_tool(SearchForIngredientDetails)
+
+questions = [
+  { text: "What are the side effects of Vitamin D3?", ingredient: "vitamin d3" },
+  { text: "What are the common interactions with magnesium glycinate?", ingredient: "magnesium glycinate" },
+  { text: "What is the recommended dosage for zinc?", ingredient: "zinc" },
+  { text: "Are there any interactions I should be aware of with zinc?", ingredient: "zinc" }
+]
+
+questions.each do |q|
+  puts "\n---\n\n"
+  puts "Question: #{q[:text]}\n\n"
+
+  chat.with_otel_attributes(
+    "langfuse.observation.prompt.name" => "supplement-assistant",
+    "langfuse.observation.prompt.version" => 1,
+    "langfuse.observation.input" => q[:text],
+    "langfuse.observation.output" => -> { chat.messages.last&.content.to_s },
+    "langfuse.observation.metadata" => { ingredient: q[:ingredient] }.to_json,
+    "langfuse.trace.metadata" => { ingredient: q[:ingredient] }.to_json,
+    "langfuse.trace.tags" => [q[:ingredient]]
+  )
+
+  response = chat.ask(q[:text])
+  puts "\nResponse: #{response.content}"
+end
+
+# This line is only necessary in short-lived scripts. In a long-running application, spans will be flushed automatically.
+OpenTelemetry.tracer_provider.force_flush

lib/opentelemetry/instrumentation/ruby_llm/patches/chat.rb

@@ -5,6 +5,11 @@ module Instrumentation
     module RubyLLM
       module Patches
         module Chat
+          def with_otel_attributes(attributes)
+            @otel_attributes = attributes
+            self
+          end
+
           def complete(&)
             provider = @model&.provider || "unknown"
             model_id = @model&.id || "unknown"
@@ -45,6 +50,8 @@ def complete(&)
                 end
               end
 
+              @otel_attributes&.each { |key, value| span.set_attribute(key, value.respond_to?(:call) ? value.call : value) }
+
               result
             end
           end

test/instrumentation_test.rb

@@ -292,6 +292,114 @@ def test_records_error_on_embedding_api_failure
     assert_equal OpenTelemetry::Trace::Status::ERROR, span.status.code
   end
 
+  def test_with_otel_attributes_sets_span_attributes
+    stub_request(:post, "https://api.openai.com/v1/chat/completions")
+      .to_return(
+        status: 200,
+        headers: { "Content-Type" => "application/json" },
+        body: {
+          id: "chatcmpl-123",
+          object: "chat.completion",
+          model: "gpt-4o-mini",
+          choices: [{
+            index: 0,
+            message: { role: "assistant", content: "Hello!" },
+            finish_reason: "stop"
+          }],
+          usage: { prompt_tokens: 10, completion_tokens: 5, total_tokens: 15 }
+        }.to_json
+      )
+
+    chat = RubyLLM.chat(model: "gpt-4o-mini")
+    chat.with_otel_attributes(
+      "langfuse.trace.tags" => ["vitamin_d3"],
+      "custom.category" => "supplements"
+    )
+    chat.ask("Hi")
+
+    span = EXPORTER.finished_spans.first
+    assert_equal ["vitamin_d3"], span.attributes["langfuse.trace.tags"]
+    assert_equal "supplements", span.attributes["custom.category"]
+  end
+
+  def test_with_otel_attributes_returns_self_for_chaining
+    stub_request(:post, "https://api.openai.com/v1/chat/completions")
+      .to_return(
+        status: 200,
+        headers: { "Content-Type" => "application/json" },
+        body: {
+          id: "chatcmpl-123",
+          object: "chat.completion",
+          model: "gpt-4o-mini",
+          choices: [{
+            index: 0,
+            message: { role: "assistant", content: "Hello!" },
+            finish_reason: "stop"
+          }],
+          usage: { prompt_tokens: 10, completion_tokens: 5, total_tokens: 15 }
+        }.to_json
+      )
+
+    chat = RubyLLM.chat(model: "gpt-4o-mini")
+    result = chat.with_otel_attributes("custom.category" => "test")
+
+    assert_same chat, result
+  end
+
+  def test_with_otel_attributes_evaluates_callables
+    stub_request(:post, "https://api.openai.com/v1/chat/completions")
+      .to_return(
+        status: 200,
+        headers: { "Content-Type" => "application/json" },
+        body: {
+          id: "chatcmpl-123",
+          object: "chat.completion",
+          model: "gpt-4o-mini",
+          choices: [{
+            index: 0,
+            message: { role: "assistant", content: "Hello!" },
+            finish_reason: "stop"
+          }],
+          usage: { prompt_tokens: 10, completion_tokens: 5, total_tokens: 15 }
+        }.to_json
+      )
+
+    chat = RubyLLM.chat(model: "gpt-4o-mini")
+    chat.with_otel_attributes(
+      "custom.last_role" => -> { chat.messages.last&.role.to_s },
+      "custom.static" => "fixed"
+    )
+    chat.ask("Hi")
+
+    span = EXPORTER.finished_spans.first
+    assert_equal "assistant", span.attributes["custom.last_role"]
+    assert_equal "fixed", span.attributes["custom.static"]
+  end
+
+  def test_works_without_otel_attributes
+    stub_request(:post, "https://api.openai.com/v1/chat/completions")
+      .to_return(
+        status: 200,
+        headers: { "Content-Type" => "application/json" },
+        body: {
+          id: "chatcmpl-123",
+          object: "chat.completion",
+          model: "gpt-4o-mini",
+          choices: [{
+            index: 0,
+            message: { role: "assistant", content: "Hello!" },
+            finish_reason: "stop"
+          }],
+          usage: { prompt_tokens: 10, completion_tokens: 5, total_tokens: 15 }
+        }.to_json
+      )
+
+    chat = RubyLLM.chat(model: "gpt-4o-mini")
+    response = chat.ask("Hi")
+
+    assert_equal "Hello!", response.content
+  end
+
   def test_captures_content_when_enabled_via_env_var
     ENV["OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT"] = "true"