activeagent 1.0.3 → 1.1.0

data/lib/active_agent/telemetry/instrumentation.rb

@@ -23,11 +23,6 @@ module ActiveAgent
     module Instrumentation
       extend ActiveSupport::Concern
 
-      included do
-        # Hook into generation lifecycle
-        around_generate :trace_generation if respond_to?(:around_generate)
-      end
-
       class_methods do
         # Installs instrumentation on the agent class.
         #
@@ -46,21 +41,82 @@ module ActiveAgent
         def process_prompt
           return super unless Telemetry.enabled?
 
-          Telemetry.trace("#{self.class.name}.#{action_name}", span_type: :root) do |span|
+          # Reuse (or mint) the generation's trace id so the telemetry trace
+          # shares one id with everything else that reads
+          # prompt_options[:trace_id] — the generation request parameters and
+          # e.g. solid_agent's persisted generation records. Without this the
+          # tracer generates its own id and traces can't be correlated with
+          # the records they describe.
+          trace_id = nil
+          if respond_to?(:prompt_options) && prompt_options.is_a?(Hash)
+            trace_id = (prompt_options[:trace_id] ||= SecureRandom.uuid)
+          end
+
+          Telemetry.trace("#{self.class.name}.#{action_name}", span_type: :root, **{ trace_id: trace_id }.compact) do |span|
             span.set_attribute("agent.class", self.class.name)
             span.set_attribute("agent.action", action_name.to_s)
-            span.set_attribute("agent.provider", provider_name) if respond_to?(:provider_name)
-            span.set_attribute("agent.model", model_name) if respond_to?(:model_name)
+            span.set_attribute("agent.provider", provider_name)
+            span.set_attribute("agent.model", model_name)
 
-            # Add prompt span
+            # Add prompt span, carrying the prompt contents (instructions +
+            # outbound messages) so dashboards can show what was sent.
             prompt_span = span.add_span("agent.prompt", span_type: :prompt)
-            prompt_span.set_attribute("messages.count", messages.size) if respond_to?(:messages)
+            if (message_stack = prompt_options[:messages]).respond_to?(:size)
+              prompt_span.set_attribute("messages.count", message_stack.size)
+            end
+            # Attribute order is display order in dashboards: the system
+            # message first, then the tool roster, then the (often long)
+            # message history.
+            if prompt_options.is_a?(Hash)
+              rendered_instructions = begin
+                prompt_view_instructions(prompt_options[:instructions]) if respond_to?(:prompt_view_instructions)
+              rescue StandardError
+                prompt_options[:instructions].is_a?(String) ? prompt_options[:instructions] : nil
+              end
+              if rendered_instructions.present?
+                prompt_span.set_attribute("prompt.input.instructions", telemetry_truncate(Array(rendered_instructions).join("\n\n")))
+              end
+
+              if (tools = prompt_options[:tools]).present?
+                roster = Array(tools).filter_map { |tool|
+                  next unless tool.is_a?(Hash)
+
+                  name = tool[:name] || tool["name"]
+                  description = tool[:description] || tool["description"]
+                  parameters = tool[:parameters] || tool["parameters"] || tool[:input_schema] || tool["input_schema"]
+                  properties = parameters.is_a?(Hash) ? (parameters[:properties] || parameters["properties"]) : nil
+                  {
+                    name: name,
+                    description: telemetry_truncate(description),
+                    parameters: properties.is_a?(Hash) ? properties.keys : []
+                  }.compact
+                }
+                prompt_span.set_attribute("prompt.input.tools", JSON.generate(roster)) if roster.any?
+              end
+
+              if (outbound = prompt_options[:messages]).present?
+                serialized = Array(outbound).map { |message|
+                  if message.is_a?(Hash)
+                    role = message[:role] || message["role"] || "user"
+                    content = message[:content] || message["content"]
+                    { role: role.to_s, content: telemetry_truncate(content) }
+                  else
+                    { role: "user", content: telemetry_truncate(message) }
+                  end
+                }
+                prompt_span.set_attribute("prompt.input.messages", JSON.generate(serialized))
+              end
+            end
             prompt_span.finish
 
             # Execute generation with LLM span
             llm_span = span.add_span("llm.generate", span_type: :llm)
-            llm_span.set_attribute("llm.provider", provider_name) if respond_to?(:provider_name)
-            llm_span.set_attribute("llm.model", model_name) if respond_to?(:model_name)
+            llm_span.set_attribute("llm.provider", provider_name)
+            llm_span.set_attribute("llm.model", model_name)
+
+            # Providers run tools through tools_function mid-generation; the
+            # wrapped proc (see below) hangs timed tool spans off this span.
+            @_telemetry_llm_span = llm_span
 
             begin
               result = super
@@ -95,6 +151,23 @@ module ActiveAgent
                 end
               end
 
+              # The span was tagged with the configured model (often unset →
+              # "unknown"); the provider's raw response knows what actually
+              # served the request.
+              if result.respond_to?(:raw_response) && result.raw_response.is_a?(Hash)
+                served_model = result.raw_response["model"] || result.raw_response[:model]
+                llm_span.set_attribute("llm.model", served_model.to_s) if served_model.present?
+              end
+
+              # Carry the generation contents so dashboards can show what
+              # came back, not just how many tokens it cost.
+              if result.respond_to?(:message) && result.message.respond_to?(:content) && result.message.content.present?
+                llm_span.set_attribute("llm.output.message", telemetry_truncate(result.message.content))
+              end
+              if result.respond_to?(:finish_reason) && result.finish_reason.present?
+                llm_span.set_attribute("llm.finish_reason", result.finish_reason.to_s)
+              end
+
               llm_span.set_status(:ok)
               llm_span.finish
               span.set_status(:ok)
@@ -105,6 +178,44 @@ module ActiveAgent
               llm_span.finish
               span.record_error(e)
               raise
+            ensure
+              @_telemetry_llm_span = nil
+            end
+          end
+        end
+
+        # Providers invoke this proc for every tool call during generation.
+        # Wrapping it is what makes tool telemetry real: each call gets a
+        # timed span with its arguments and result — the post-hoc
+        # result.tool_calls path below never fires on 1.x responses, which
+        # don't expose tool calls.
+        def tools_function
+          base = super
+          return base unless Telemetry.enabled?
+
+          agent = self
+          proc do |tool_name, *args, **kwargs|
+            parent = agent.instance_variable_get(:@_telemetry_llm_span)
+            unless parent
+              next base.call(tool_name, *args, **kwargs)
+            end
+
+            tool_span = parent.add_span("tool.#{tool_name}", span_type: :tool)
+            tool_span.set_attribute("tool.name", tool_name.to_s)
+            arguments = kwargs.presence || (args.length == 1 ? args.first : args.presence)
+            if arguments.present?
+              tool_span.set_attribute("tool.input.args", agent.send(:telemetry_truncate, JSON.generate(arguments)))
+            end
+            begin
+              result = base.call(tool_name, *args, **kwargs)
+              tool_span.set_attribute("tool.output.result", agent.send(:telemetry_truncate, result))
+              tool_span.set_status(:ok)
+              result
+            rescue StandardError => e
+              tool_span.record_error(e)
+              raise
+            ensure
+              tool_span.finish
             end
           end
         end
@@ -116,7 +227,7 @@ module ActiveAgent
           Telemetry.trace("#{self.class.name}.embed", span_type: :embedding) do |span|
             span.set_attribute("agent.class", self.class.name)
             span.set_attribute("agent.action", "embed")
-            span.set_attribute("agent.provider", provider_name) if respond_to?(:provider_name)
+            span.set_attribute("agent.provider", provider_name)
 
             begin
               result = super
@@ -138,8 +249,20 @@ module ActiveAgent
 
         private
 
+        # Content attributes are capped so a large prompt (e.g. a 100k-token
+        # tool loop) can't bloat the trace payload.
+        TELEMETRY_ATTRIBUTE_MAX_CHARS = 4_000
+
+        def telemetry_truncate(value)
+          text = value.to_s
+          return text if text.length <= TELEMETRY_ATTRIBUTE_MAX_CHARS
+
+          "#{text[0, TELEMETRY_ATTRIBUTE_MAX_CHARS]}… (truncated, #{text.length} chars total)"
+        end
+
         def provider_name
-          self.class.generation_provider&.to_s || "unknown"
+          klass = prompt_provider_klass
+          klass.respond_to?(:tag_name) ? klass.tag_name : "unknown"
         rescue StandardError
           "unknown"
         end

data/lib/active_agent/telemetry/reporter.rb

@@ -1,175 +1,22 @@
 # frozen_string_literal: true
 
-require "net/http"
-require "json"
-require "uri"
-
 module ActiveAgent
   module Telemetry
-    # Asynchronously reports traces to the telemetry endpoint.
-    #
-    # Buffers traces and sends them in batches to reduce network overhead.
-    # Uses a background thread for non-blocking transmission.
+    # The framework's reporter, now provided by the activeagents-telemetry
+    # gem's BatchingReporter: buffered delivery on batch_size/flush_interval,
+    # a blocking flush, and a shutdown that waits out in-flight sends so
+    # traces reported near process exit are delivered rather than dropped.
     #
-    # @example
-    #   reporter = Reporter.new(configuration)
-    #   reporter.report(trace_payload)
-    #   reporter.flush  # Send immediately
-    #   reporter.shutdown  # Clean shutdown
+    # Local storage is handled by Configuration#local_store, which routes
+    # traces through the dashboard's trace model instead of HTTP.
     #
-    class Reporter
-      # @return [Configuration] Telemetry configuration
-      attr_reader :configuration
-
+    # @see ActiveAgents::Telemetry::BatchingReporter
+    class Reporter < ActiveAgents::Telemetry::BatchingReporter
       def initialize(configuration)
-        @configuration = configuration
-        @buffer = []
-        @mutex = Mutex.new
-        @running = false
-        @thread = nil
-        @shutdown = false
-
-        start_flush_thread if configuration.enabled?
-      end
-
-      # Adds a trace to the buffer for transmission.
-      #
-      # @param trace [Hash] Trace payload
-      # @return [void]
-      def report(trace)
-        return unless configuration.enabled?
-
-        @mutex.synchronize do
-          @buffer << trace
-
-          # Flush immediately if buffer is full
-          if @buffer.size >= configuration.batch_size
-            flush_buffer
-          end
-        end
-      end
-
-      # Flushes all buffered traces immediately.
-      #
-      # @return [void]
-      def flush
-        @mutex.synchronize do
-          flush_buffer
-        end
-      end
-
-      # Shuts down the reporter, flushing remaining traces.
-      #
-      # @return [void]
-      def shutdown
-        @shutdown = true
-        flush
-        @thread&.join(5) # Wait up to 5 seconds for thread to finish
-      end
-
-      private
-
-      # Starts the background flush thread.
-      def start_flush_thread
-        @running = true
-        @thread = Thread.new do
-          Thread.current.name = "activeagent-telemetry-reporter"
-
-          while @running && !@shutdown
-            sleep(configuration.flush_interval)
-
-            @mutex.synchronize do
-              flush_buffer if @buffer.any?
-            end
-          end
-        end
-      end
-
-      # Flushes the buffer by sending traces to the endpoint.
-      #
-      # Must be called within @mutex synchronization.
-      def flush_buffer
-        return if @buffer.empty?
-
-        traces = @buffer.dup
-        @buffer.clear
-
-        Thread.new { send_traces(traces) }
-      end
-
-      # Sends traces to the configured endpoint.
-      #
-      # @param traces [Array<Hash>] Traces to send
-      def send_traces(traces)
-        # Use direct database storage for local mode
-        if configuration.local_storage?
-          store_traces_locally(traces)
-          return
-        end
-
-        uri = URI.parse(configuration.endpoint)
-
-        http = Net::HTTP.new(uri.host, uri.port)
-        http.use_ssl = uri.scheme == "https"
-        http.open_timeout = configuration.timeout
-        http.read_timeout = configuration.timeout
-
-        request = Net::HTTP::Post.new(uri.request_uri)
-        request["Content-Type"] = "application/json"
-        request["Authorization"] = "Bearer #{configuration.api_key}"
-        request["User-Agent"] = "ActiveAgent/#{ActiveAgent::VERSION} Ruby/#{RUBY_VERSION}"
-        request["X-Service-Name"] = configuration.resolved_service_name
-        request["X-Environment"] = configuration.environment
-
-        payload = {
-          traces: traces,
-          sdk: {
-            name: "activeagent",
-            version: ActiveAgent::VERSION,
-            language: "ruby",
-            runtime_version: RUBY_VERSION
-          }
-        }
-
-        request.body = JSON.generate(payload)
-
-        response = http.request(request)
-
-        unless response.is_a?(Net::HTTPSuccess)
-          log_error("Failed to send traces: #{response.code} #{response.message}")
-        end
-      rescue StandardError => e
-        log_error("Error sending traces: #{e.class} - #{e.message}")
-      end
-
-      # Stores traces directly in the local database.
-      #
-      # @param traces [Array<Hash>] Traces to store
-      def store_traces_locally(traces)
-        sdk_info = {
-          name: "activeagent",
-          version: ActiveAgent::VERSION,
-          language: "ruby",
-          runtime_version: RUBY_VERSION
-        }
-
-        traces.each do |trace|
-          # Skip if trace already exists (idempotency)
-          next if ActiveAgent::TelemetryTrace.exists?(trace_id: trace["trace_id"])
-
-          ActiveAgent::TelemetryTrace.create_from_payload(trace, sdk_info)
-        rescue StandardError => e
-          log_error("Failed to store trace locally: #{e.class} - #{e.message}")
-        end
-      rescue StandardError => e
-        log_error("Error storing traces locally: #{e.class} - #{e.message}")
-      end
-
-      # Logs an error message.
-      #
-      # @param message [String] Error message
-      def log_error(message)
-        configuration.resolved_logger.error("[ActiveAgent::Telemetry] #{message}")
+        # sample: false — the Tracer applies head-based sampling at trace
+        # creation, before any span is built; sampling again here would
+        # compound the rate to rate².
+        super(configuration, sdk_name: "activeagent", sdk_version: ActiveAgent::VERSION, sample: false)
       end
     end
   end

data/lib/active_agent/telemetry/span.rb

@@ -2,103 +2,28 @@
 
 module ActiveAgent
   module Telemetry
-    # Represents a single span in a trace.
+    # The framework's span, now provided by the activeagents-telemetry gem.
+    # This subclass translates the framework's historical constructor
+    # (span_type: keyword, attributes as a keyword splat) onto the shared
+    # class; everything else — set_attribute, set_tokens, set_status,
+    # record_error, add_span, measure, finish — is inherited.
     #
-    # Spans capture discrete operations within a trace, such as LLM calls,
-    # tool invocations, or prompt rendering. Each span has timing, attributes,
-    # and can have child spans.
+    # One deliberate change rides along from the shared core: record_error
+    # truncates the message and no longer puts a backtrace on the wire.
     #
-    # @example Creating a span
-    #   span = Span.new("llm.generate", trace_id: trace.trace_id)
-    #   span.set_attribute("provider", "anthropic")
-    #   span.set_attribute("model", "claude-3-5-sonnet")
-    #   span.set_tokens(input: 100, output: 50)
-    #   span.finish
-    #
-    class Span
-      # Span types for categorization
-      TYPES = {
-        root: "root",           # Root span for entire generation
-        prompt: "prompt",       # Prompt preparation/rendering
-        llm: "llm",             # LLM API call
-        tool: "tool",           # Tool invocation
-        thinking: "thinking",   # Extended thinking (Anthropic)
-        embedding: "embedding", # Embedding generation
-        error: "error"          # Error handling
-      }.freeze
-
-      # Span status codes
-      STATUS = {
-        unset: "UNSET",
-        ok: "OK",
-        error: "ERROR"
-      }.freeze
-
-      # @return [String] Unique identifier for this span
-      attr_reader :span_id
-
-      # @return [String] Trace ID this span belongs to
-      attr_reader :trace_id
-
-      # @return [String, nil] Parent span ID
-      attr_reader :parent_span_id
-
-      # @return [String] Span name (e.g., "llm.generate", "tool.get_weather")
-      attr_reader :name
-
-      # @return [String] Span type from TYPES
-      attr_reader :span_type
-
-      # @return [Time] When the span started
-      attr_reader :start_time
-
-      # @return [Time, nil] When the span ended
-      attr_reader :end_time
-
-      # @return [Hash] Span attributes
-      attr_reader :attributes
-
-      # @return [Array<Span>] Child spans
-      attr_reader :children
-
-      # @return [String] Status code from STATUS
-      attr_reader :status
-
-      # @return [String, nil] Status message
-      attr_reader :status_message
-
-      # @return [Array<Hash>] Events recorded during the span
-      attr_reader :events
-
-      # Creates a new span.
-      #
-      # @param name [String] Span name
-      # @param trace_id [String] Parent trace ID
-      # @param parent_span_id [String, nil] Parent span ID
-      # @param span_type [Symbol] Type of span
-      # @param attributes [Hash] Initial attributes
+    # @see ActiveAgents::Telemetry::Span
+    class Span < ActiveAgents::Telemetry::Span
       def initialize(name, trace_id:, parent_span_id: nil, span_type: :root, **attributes)
-        @span_id = SecureRandom.hex(8)
-        @trace_id = trace_id
-        @parent_span_id = parent_span_id
-        @name = name
-        @span_type = TYPES[span_type] || span_type.to_s
-        @start_time = Time.current
-        @end_time = nil
-        @attributes = attributes.transform_keys(&:to_s)
-        @children = []
-        @status = STATUS[:unset]
-        @status_message = nil
-        @events = []
-        @tokens = { input: 0, output: 0, thinking: 0, total: 0 }
+        super(
+          name,
+          type: span_type,
+          trace_id: trace_id,
+          parent_span_id: parent_span_id,
+          attributes: attributes
+        )
       end
 
-      # Creates a child span.
-      #
-      # @param name [String] Child span name
-      # @param span_type [Symbol] Type of span
-      # @param attributes [Hash] Span attributes
-      # @return [Span] The child span
+      # Creates a child span, keeping the framework's keyword shape.
       def add_span(name, span_type: :root, **attributes)
         child = Span.new(
           name,
@@ -107,161 +32,9 @@ module ActiveAgent
           span_type: span_type,
           **attributes
         )
-        @children << child
+        children << child
         child
       end
-
-      # Sets a single attribute.
-      #
-      # @param key [String, Symbol] Attribute key
-      # @param value [Object] Attribute value
-      # @return [self]
-      def set_attribute(key, value)
-        @attributes[key.to_s] = value
-        self
-      end
-
-      # Sets multiple attributes at once.
-      #
-      # @param attrs [Hash] Attributes to set
-      # @return [self]
-      def set_attributes(attrs)
-        attrs.each { |k, v| set_attribute(k, v) }
-        self
-      end
-
-      # Sets token usage for LLM spans.
-      #
-      # @param input [Integer] Input token count
-      # @param output [Integer] Output token count
-      # @param thinking [Integer] Thinking token count (Anthropic extended thinking)
-      # @return [self]
-      def set_tokens(input: 0, output: 0, thinking: 0)
-        @tokens = {
-          input: input,
-          output: output,
-          thinking: thinking,
-          total: input + output + thinking
-        }
-        set_attribute("tokens.input", input)
-        set_attribute("tokens.output", output)
-        set_attribute("tokens.thinking", thinking) if thinking > 0
-        set_attribute("tokens.total", @tokens[:total])
-        self
-      end
-
-      # Returns token usage.
-      #
-      # @return [Hash] Token counts
-      def tokens
-        @tokens.dup
-      end
-
-      # Sets the span status.
-      #
-      # @param code [Symbol] Status code (:ok, :error, :unset)
-      # @param message [String, nil] Optional status message
-      # @return [self]
-      def set_status(code, message = nil)
-        @status = STATUS[code] || STATUS[:unset]
-        @status_message = message
-        self
-      end
-
-      # Records an error on the span.
-      #
-      # @param error [Exception] The error to record
-      # @return [self]
-      def record_error(error)
-        set_status(:error, error.message)
-        set_attribute("error.type", error.class.name)
-        set_attribute("error.message", error.message)
-        set_attribute("error.backtrace", error.backtrace&.first(10)&.join("\n"))
-
-        add_event("exception", {
-          "exception.type" => error.class.name,
-          "exception.message" => error.message,
-          "exception.stacktrace" => error.backtrace&.join("\n")
-        })
-
-        self
-      end
-
-      # Adds an event to the span.
-      #
-      # @param name [String] Event name
-      # @param attributes [Hash] Event attributes
-      # @return [self]
-      def add_event(name, attributes = {})
-        @events << {
-          name: name,
-          timestamp: Time.current.iso8601(6),
-          attributes: attributes.transform_keys(&:to_s)
-        }
-        self
-      end
-
-      # Marks the span as finished.
-      #
-      # @return [self]
-      def finish
-        @end_time = Time.current
-        set_status(:ok) if @status == STATUS[:unset]
-        self
-      end
-
-      # Returns whether the span is finished.
-      #
-      # @return [Boolean]
-      def finished?
-        !@end_time.nil?
-      end
-
-      # Returns the duration in milliseconds.
-      #
-      # @return [Float, nil] Duration or nil if not finished
-      def duration_ms
-        return nil unless finished?
-
-        ((@end_time - @start_time) * 1000).round(2)
-      end
-
-      # Serializes the span for transmission.
-      #
-      # @return [Hash] Serialized span data
-      def to_h
-        {
-          span_id: span_id,
-          trace_id: trace_id,
-          parent_span_id: parent_span_id,
-          name: name,
-          type: span_type,
-          start_time: start_time.iso8601(6),
-          end_time: end_time&.iso8601(6),
-          duration_ms: duration_ms,
-          status: status,
-          status_message: status_message,
-          attributes: attributes,
-          tokens: tokens,
-          events: events,
-          children: children.map(&:to_h)
-        }
-      end
-
-      # Executes a block and records timing/errors.
-      #
-      # @yield Block to execute within the span
-      # @return [Object] Result of the block
-      def measure
-        result = yield
-        set_status(:ok)
-        result
-      rescue StandardError => e
-        record_error(e)
-        raise
-      ensure
-        finish
-      end
     end
   end
 end