activeagent 1.0.2 → 1.1.0

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

data/lib/active_agent/telemetry/tracer.rb

@@ -2,18 +2,17 @@
 
 module ActiveAgent
   module Telemetry
-    # Manages trace creation and lifecycle.
+    # Manages trace creation and lifecycle on the activeagents-telemetry
+    # core: builds an ActiveAgents::Telemetry::Trace per unit of work, tracks
+    # the current span in thread-local storage, and hands finished traces to
+    # the Reporter.
     #
-    # The Tracer creates traces, manages the current trace context,
-    # and coordinates with the Reporter for async transmission.
-    #
-    # @example Basic usage
+    # @example
     #   tracer = Tracer.new(configuration)
     #   tracer.trace("MyAgent.greet") do |span|
     #     span.set_attribute("user_id", 123)
     #     span.add_span("llm.generate", span_type: :llm)
     #   end
-    #
     class Tracer
       # @return [Configuration] Telemetry configuration
       attr_reader :configuration
@@ -27,44 +26,47 @@ module ActiveAgent
       def initialize(configuration)
         @configuration = configuration
         @reporter = Reporter.new(configuration)
-        @mutex = Mutex.new
       end
 
       # Creates and executes a new trace.
       #
+      # Callers may supply the trace id (instrumentation passes the
+      # generation's prompt_options[:trace_id]) so external records — e.g.
+      # solid_agent's persisted generations — can correlate with this trace;
+      # otherwise one is generated.
+      #
       # @param name [String] Trace name (typically "AgentClass.action")
-      # @param attributes [Hash] Root span attributes
+      # @param attributes [Hash] Root span attributes; :trace_id and
+      #   :span_type are extracted rather than recorded
       # @yield [span] Yields the root span for adding child spans
       # @return [Object] Result of the block
-      #
-      # @example
-      #   tracer.trace("WeatherAgent.forecast") do |span|
-      #     span.set_attribute("location", "Seattle")
-      #     result = do_llm_call
-      #     span.set_tokens(input: 100, output: 50)
-      #     result
-      #   end
-      def trace(name, **attributes, &block)
+      def trace(name, **attributes)
         return yield(Telemetry::NullSpan.new) unless should_trace?
 
-        trace_id = generate_trace_id
+        trace_id = attributes.delete(:trace_id) || SecureRandom.hex(16)
+        span_type = attributes.delete(:span_type) || :root
+
+        trace = build_trace(trace_id)
         root_span = Span.new(
           name,
           trace_id: trace_id,
-          span_type: :root,
+          span_type: span_type,
           **default_attributes.merge(attributes)
         )
+        trace.add_span(root_span)
 
         with_span(root_span) do
           result = yield(root_span)
           root_span.finish
-          report_trace(root_span)
+          reporter.report(redact_trace!(trace))
           result
         end
       rescue StandardError => e
-        root_span&.record_error(e)
-        root_span&.finish
-        report_trace(root_span) if root_span
+        if root_span && !root_span.finished?
+          root_span.record_error(e)
+          root_span.finish
+          reporter.report(redact_trace!(trace))
+        end
         raise
       end
 
@@ -76,11 +78,12 @@ module ActiveAgent
       def span(name, **attributes)
         return Telemetry::NullSpan.new unless should_trace?
 
+        span_type = attributes.delete(:span_type) || :root
         current = current_span
         if current
-          current.add_span(name, **attributes)
+          current.add_span(name, span_type: span_type, **attributes)
         else
-          Span.new(name, trace_id: generate_trace_id, **default_attributes.merge(attributes))
+          Span.new(name, trace_id: SecureRandom.hex(16), span_type: span_type, **default_attributes.merge(attributes))
         end
       end
 
@@ -91,7 +94,9 @@ module ActiveAgent
         Thread.current[CURRENT_SPAN_KEY]
       end
 
-      # Flushes buffered traces immediately.
+      # Flushes buffered traces and waits for delivery to complete, so
+      # callers (tests, rails runner, job shutdown) can rely on the traces
+      # having been delivered/stored when this returns.
       #
       # @return [void]
       def flush
@@ -107,11 +112,16 @@ module ActiveAgent
 
       private
 
+      def build_trace(trace_id)
+        ActiveAgents::Telemetry::Trace.new(
+          trace_id: trace_id,
+          service_name: configuration.resolved_service_name,
+          environment: configuration.resolved_environment,
+          resource_attributes: configuration.resource_attributes
+        )
+      end
+
       # Executes block with span as current context.
-      #
-      # @param span [Span] Span to set as current
-      # @yield Block to execute
-      # @return [Object] Result of block
       def with_span(span)
         previous = Thread.current[CURRENT_SPAN_KEY]
         Thread.current[CURRENT_SPAN_KEY] = span
@@ -120,61 +130,48 @@ module ActiveAgent
         Thread.current[CURRENT_SPAN_KEY] = previous
       end
 
-      # Reports a completed trace to the reporter.
-      #
-      # @param span [Span] Root span of the trace
-      def report_trace(span)
-        reporter.report(build_trace_payload(span))
+      # Redacts span (and span-event) attributes whose keys match any
+      # configured redact_attributes entry, before the trace is handed to
+      # the reporter. Matching is case-insensitive substring — deliberately
+      # over-broad: better to redact a harmless "max_tokens" than to ship
+      # an "api_key". (Ported from the pre-shared-core payload builder,
+      # which no longer exists — the gem's reporter ships the trace as-is.)
+      REDACTED = "[REDACTED]"
+
+      def redact_trace!(trace)
+        patterns = Array(configuration.redact_attributes).map(&:to_s).reject(&:empty?)
+        return trace if patterns.empty?
+
+        matcher = Regexp.union(patterns.map { |pattern| Regexp.new(Regexp.escape(pattern), Regexp::IGNORECASE) })
+        Array(trace.spans).each { |span| redact_span!(span, matcher) }
+        trace
       end
 
-      # Builds the trace payload for transmission.
-      #
-      # @param root_span [Span] Root span
-      # @return [Hash] Trace payload
-      def build_trace_payload(root_span)
-        {
-          trace_id: root_span.trace_id,
-          service_name: configuration.resolved_service_name,
-          environment: configuration.environment,
-          timestamp: Time.current.iso8601(6),
-          resource_attributes: configuration.resource_attributes,
-          spans: flatten_spans(root_span)
-        }
+      def redact_span!(span, matcher)
+        redact_hash!(span.attributes, matcher) if span.attributes.is_a?(Hash)
+        Array(span.events).each do |event|
+          attributes = event.is_a?(Hash) ? (event["attributes"] || event[:attributes]) : nil
+          redact_hash!(attributes, matcher) if attributes.is_a?(Hash)
+        end
+        Array(span.children).each { |child| redact_span!(child, matcher) }
       end
 
-      # Flattens span hierarchy into array.
-      #
-      # @param span [Span] Root span
-      # @return [Array<Hash>] Flattened span data
-      def flatten_spans(span)
-        result = [ span.to_h.except(:children) ]
-        span.children.each do |child|
-          result.concat(flatten_spans(child))
+      def redact_hash!(attributes, matcher)
+        attributes.each_key do |key|
+          attributes[key] = REDACTED if key.to_s.match?(matcher)
         end
-        result
       end
 
-      # Returns whether this trace should be sampled.
-      #
-      # @return [Boolean]
+      # Returns whether this trace should be collected at all.
       def should_trace?
         configuration.enabled? && configuration.configured? && configuration.should_sample?
       end
 
-      # Generates a unique trace ID.
-      #
-      # @return [String] 32-character hex trace ID
-      def generate_trace_id
-        SecureRandom.hex(16)
-      end
-
       # Returns default attributes for all spans.
-      #
-      # @return [Hash] Default attributes
       def default_attributes
         {
           "service.name" => configuration.resolved_service_name,
-          "service.environment" => configuration.environment,
+          "service.environment" => configuration.resolved_environment,
           "telemetry.sdk.name" => "activeagent",
           "telemetry.sdk.version" => ActiveAgent::VERSION
         }