feat: add support for OTEL based telemetry focusing on langfuse

Gemfile.lock

@@ -2,6 +2,9 @@ PATH
   remote: .
   specs:
     ai-agents (0.7.0)
+      opentelemetry-api (~> 1.5)
+      opentelemetry-exporter-otlp (~> 0.30)
+      opentelemetry-sdk (~> 1.5)
       ruby_llm (~> 1.8.2)
 
 GEM
@@ -30,6 +33,14 @@ GEM
       net-http (>= 0.5.0)
     faraday-retry (2.3.2)
       faraday (~> 2.0)
+    google-protobuf (4.33.0)
+      bigdecimal
+      rake (>= 13)
+    google-protobuf (4.33.0-arm64-darwin)
+      bigdecimal
+      rake (>= 13)
+    googleapis-common-protos-types (1.22.0)
+      google-protobuf (~> 4.26)
     hashdiff (1.2.1)
     io-console (0.8.1)
     irb (1.15.2)
@@ -44,6 +55,25 @@ GEM
     multipart-post (2.4.1)
     net-http (0.6.0)
       uri
+    opentelemetry-api (1.7.0)
+    opentelemetry-common (0.23.0)
+      opentelemetry-api (~> 1.0)
+    opentelemetry-exporter-otlp (0.31.0)
+      google-protobuf (>= 3.18)
+      googleapis-common-protos-types (~> 1.3)
+      opentelemetry-api (~> 1.1)
+      opentelemetry-common (~> 0.20)
+      opentelemetry-sdk (~> 1.2)
+      opentelemetry-semantic_conventions
+    opentelemetry-registry (0.4.0)
+      opentelemetry-api (~> 1.1)
+    opentelemetry-sdk (1.10.0)
+      opentelemetry-api (~> 1.1)
+      opentelemetry-common (~> 0.20)
+      opentelemetry-registry (~> 0.2)
+      opentelemetry-semantic_conventions
+    opentelemetry-semantic_conventions (1.36.0)
+      opentelemetry-api (~> 1.0)
     parallel (1.27.0)
     parser (3.3.9.0)
       ast (~> 2.4.1)

ai-agents.gemspec

@@ -33,6 +33,11 @@ Gem::Specification.new do |spec|
   # Core dependencies
   spec.add_dependency "ruby_llm", "~> 1.8.2"
 
+  # OpenTelemetry dependencies for tracing
+  spec.add_dependency "opentelemetry-api", "~> 1.5"
+  spec.add_dependency "opentelemetry-sdk", "~> 1.5"
+  spec.add_dependency "opentelemetry-exporter-otlp", "~> 0.30"
+
   # For more information and examples about making a new gem, check out our
   # guide at: https://bundler.io/guides/creating_gem.html
 end

examples/isp-support/interactive.rb

@@ -3,6 +3,7 @@
 
 require "json"
 require "readline"
+require "base64"
 require_relative "../../lib/agents"
 require_relative "agents_factory"
 
@@ -12,6 +13,25 @@ def initialize
     # Configure the Agents SDK with API key
     Agents.configure do |config|
       config.openai_api_key = ENV["OPENAI_API_KEY"]
+
+      # Tracing configuration from Langfuse environment variables
+      if ENV["LANGFUSE_PUBLIC_KEY"] && ENV["LANGFUSE_SECRET_KEY"]
+        config.enable_tracing = true
+        langfuse_host = ENV.fetch("LANGFUSE_HOST", "https://cloud.langfuse.com")
+        config.tracing_endpoint = "#{langfuse_host}/api/public/otel/v1/traces"
+
+        # Create Basic auth header from Langfuse credentials
+        auth_string = "#{ENV['LANGFUSE_PUBLIC_KEY']}:#{ENV['LANGFUSE_SECRET_KEY']}"
+        config.tracing_headers = {
+          "Authorization" => "Basic #{Base64.strict_encode64(auth_string)}"
+        }
+      else
+        config.enable_tracing = false
+      end
+
+      config.app_name = ENV.fetch("APP_NAME", "ISP-Support-Demo")
+      config.app_version = ENV.fetch("APP_VERSION", "1.0.0")
+      config.environment = ENV.fetch("ENVIRONMENT", "development")
     end
 
     # Create agents
@@ -30,8 +50,14 @@ def initialize
     @context = {}
     @current_status = ""
 
+    # Hardcoded session ID for tracing (for testing)
+    @session_id = "demo_session_#{Time.now.to_i}"
+
     puts green("🏢 Welcome to ISP Customer Support!")
     puts dim_text("Type '/help' for commands or 'exit' to quit.")
+    if Agents.configuration.enable_tracing
+      puts dim_text("🔍 Tracing enabled - Session: #{@session_id}")
+    end
     puts
   end
 
@@ -50,8 +76,19 @@ def start
       print yellow("🤖 Processing...")
 
       begin
-        # Use the runner - it automatically determines the right agent from context
-        result = @runner.run(user_input, context: @context)
+        # Wrap in trace context
+        result = Agents.with_trace(
+          user_id: "demo_user",
+          session_id: @session_id,
+          tags: ["isp_support", "interactive"],
+          metadata: {
+            channel: "cli",
+            demo: "true"
+          }
+        ) do
+          # Use the runner - it automatically determines the right agent from context
+          @runner.run(user_input, context: @context)
+        end
 
         # Update our context with the returned context from Runner
         @context = result.context if result.respond_to?(:context) && result.context

lib/agents.rb

@@ -31,13 +31,36 @@ class << self
     def configure
       yield(configuration) if block_given?
       configure_ruby_llm!
+      configure_tracing!
       configuration
     end
 
     def configuration
       @configuration ||= Configuration.new
     end
 
+    # Set trace context for all operations within the block.
+    # See Agents::Tracing.with_trace for details.
+    def with_trace(**attrs, &block)
+      Tracing.with_trace(**attrs, &block)
+    end
+
+    # Create a custom span within the current trace.
+    # See Agents::Tracing.in_span for details.
+    def in_span(name, **attrs, &block)
+      Tracing.in_span(name, **attrs, &block)
+    end
+
+    # Get the current OpenTelemetry span
+    def current_span
+      Tracing.current_span
+    end
+
+    # Get the current trace context
+    def current_trace_context
+      Tracing.current_trace_context
+    end
+
     private
 
     def configure_ruby_llm!
@@ -47,6 +70,10 @@ def configure_ruby_llm!
       end
     end
 
+    def configure_tracing!
+      Tracing.setup(configuration)
+    end
+
     def configure_providers(config)
       # OpenAI configuration
       apply_if_present(config, :openai_api_key)
@@ -89,10 +116,20 @@ class Configuration
     # General configuration
     attr_accessor :request_timeout, :default_model, :debug
 
+    # Tracing configuration
+    attr_accessor :enable_tracing, :tracing_endpoint, :tracing_headers
+    attr_accessor :app_name, :app_version, :environment
+
     def initialize
       @default_model = "gpt-4o-mini"
       @request_timeout = 120
       @debug = false
+      @enable_tracing = false
+      @tracing_endpoint = nil
+      @tracing_headers = {}
+      @app_name = "ai-agents"
+      @app_version = nil
+      @environment = "production"
     end
 
     # Check if at least one provider is configured
@@ -114,6 +151,10 @@ def configured?
 require_relative "agents/helpers"
 require_relative "agents/agent"
 
+# Tracing components
+require_relative "agents/trace_context"
+require_relative "agents/tracing"
+
 # Execution components
 require_relative "agents/tool_wrapper"
 require_relative "agents/callback_manager"