activeagent 1.0.3 → 1.2.0

data/lib/active_agent/telemetry/configuration.rb

@@ -2,212 +2,156 @@
 
 module ActiveAgent
   module Telemetry
-    # Configuration for telemetry collection and reporting.
+    # The framework's telemetry configuration, now provided by the
+    # activeagents-telemetry gem. This subclass keeps the framework's
+    # historical behavior on top of the shared core:
     #
-    # Stores settings for endpoint, authentication, sampling, and batching.
-    # Configuration can be set programmatically or loaded from YAML.
+    # * telemetry is opt-in (`enabled` defaults to false)
+    # * `local_storage: true` persists traces through the dashboard's trace
+    #   model instead of HTTP
     #
-    # @example Programmatic configuration
-    #   ActiveAgent::Telemetry.configure do |config|
-    #     config.enabled = true
-    #     config.endpoint = "https://api.activeagents.ai/v1/traces"
-    #     config.api_key = "your-api-key"
-    #     config.sample_rate = 1.0
-    #   end
+    # Every other option — endpoint, api_key, sample_rate, batch_size,
+    # flush_interval, capture_bodies, redact_attributes, service_name,
+    # environment, resource_attributes — lives on the shared class, so
+    # existing config/active_agent.yml files keep working unchanged.
     #
-    # @example YAML configuration (config/activeagent.yml)
-    #   telemetry:
-    #     enabled: true
-    #     endpoint: https://api.activeagents.ai/v1/traces
-    #     api_key: <%= ENV["ACTIVEAGENTS_API_KEY"] %>
-    #     sample_rate: 1.0
-    #     batch_size: 100
-    #     flush_interval: 5
-    #
-    class Configuration
-      # @return [Boolean] Whether telemetry is enabled (default: false)
-      attr_accessor :enabled
-
-      # @return [String] The endpoint URL for sending traces
-      attr_accessor :endpoint
-
-      # @return [String] API key for authentication
-      attr_accessor :api_key
-
-      # @return [Float] Sampling rate from 0.0 to 1.0 (default: 1.0)
-      attr_accessor :sample_rate
-
-      # @return [Integer] Number of traces to batch before sending (default: 100)
-      attr_accessor :batch_size
-
-      # @return [Integer] Seconds between automatic flushes (default: 5)
-      attr_accessor :flush_interval
-
-      # @return [Integer] HTTP timeout in seconds (default: 10)
-      attr_accessor :timeout
-
-      # @return [Boolean] Whether to capture request/response bodies (default: false)
-      attr_accessor :capture_bodies
-
-      # @return [Array<String>] Attributes to redact from traces
-      attr_accessor :redact_attributes
-
-      # @return [String] Service name for trace attribution
-      attr_accessor :service_name
-
-      # @return [String] Environment name (development, staging, production)
-      attr_accessor :environment
-
-      # @return [Hash] Additional resource attributes to include in all traces
-      attr_accessor :resource_attributes
-
-      # @return [Logger] Logger for telemetry operations
-      attr_accessor :logger
-
-      # @return [Boolean] Whether to store traces locally in the app's database
-      attr_accessor :local_storage
+    # @see ActiveAgents::Telemetry::Configuration
+    class Configuration < ActiveAgents::Telemetry::Configuration
+      # Fallback ingest path when the dashboard engine's mount point can't
+      # be resolved from the host's routes (e.g. engine not mounted).
+      LOCAL_ENDPOINT_PATH = "/activeagents/api/traces"
 
-      # Default ActiveAgents.ai endpoint for hosted observability.
-      DEFAULT_ENDPOINT = "https://api.activeagents.ai/v1/traces"
-
-      # Local dashboard endpoint path (relative to app root)
-      LOCAL_ENDPOINT_PATH = "/active_agent/api/traces"
+      # @return [Boolean] Whether to store traces in the app's own database
+      attr_reader :local_storage
 
       def initialize
-        @enabled = false
-        @endpoint = DEFAULT_ENDPOINT
-        @api_key = nil
-        @sample_rate = 1.0
-        @batch_size = 100
-        @flush_interval = 5
-        @timeout = 10
-        @capture_bodies = false
-        @redact_attributes = %w[password secret token key credential api_key]
-        @service_name = nil
-        @environment = Rails.env if defined?(Rails)
-        @resource_attributes = {}
-        @logger = nil
+        super
+        # The framework predates the shared gem and has always been opt-in;
+        # adapters treat the presence of an api_key as the switch instead.
+        self.enabled = false
         @local_storage = false
       end
 
-      # Returns whether telemetry collection is enabled.
-      #
-      # @return [Boolean]
-      def enabled?
-        @enabled == true
+      def local_storage=(value)
+        @local_storage = value == true
       end
 
-      # Returns whether telemetry is properly configured.
-      #
-      # Checks that endpoint and api_key are present, or local_storage is enabled.
-      #
-      # @return [Boolean]
-      def configured?
-        local_storage? || (endpoint.present? && api_key.present?)
+      def local_storage?
+        @local_storage
       end
 
-      # Returns whether local storage mode is enabled.
-      #
-      # @return [Boolean]
-      def local_storage?
-        @local_storage == true
+      def local_store?
+        local_storage? || super
+      end
+
+      # When local storage is on, traces persist through the dashboard's
+      # trace model rather than leaving the process.
+      def local_store
+        super || (dashboard_store if local_storage?)
       end
 
       # Returns the resolved endpoint for trace reporting.
-      #
-      # Uses local endpoint when local_storage is enabled.
-      #
-      # @return [String]
       def resolved_endpoint
-        if local_storage?
-          LOCAL_ENDPOINT_PATH
-        else
-          endpoint
-        end
+        local_storage? ? local_endpoint_path : endpoint
       end
 
-      # Returns whether a trace should be sampled.
-      #
-      # Uses sample_rate to determine if trace should be collected.
-      #
-      # @return [Boolean]
-      def should_sample?
-        return true if sample_rate >= 1.0
-        return false if sample_rate <= 0.0
-
-        rand < sample_rate
+      # The dashboard engine's ingest path, derived from wherever the host
+      # app actually mounted it — "/activeagents", "/observability", or "/"
+      # on a dedicated subdomain all work. Falls back to
+      # LOCAL_ENDPOINT_PATH when the engine isn't mounted.
+      def local_endpoint_path
+        mount = dashboard_mount_path
+        mount ? "#{mount}/api/traces" : LOCAL_ENDPOINT_PATH
       end
 
-      # Resolves the service name for traces.
-      #
-      # Falls back to Rails application name or "activeagent".
-      #
-      # @return [String]
+      # The framework's historical fallback is "activeagent", not the shared
+      # core's generic "ruby".
       def resolved_service_name
-        @service_name || rails_app_name || "activeagent"
+        value = super
+        value == "ruby" ? "activeagent" : value
       end
 
-      # Returns the logger for telemetry operations.
-      #
-      # Falls back to Rails.logger or a null logger.
-      #
-      # @return [Logger]
-      def resolved_logger
-        @logger || (defined?(Rails) && Rails.logger) || Logger.new(File::NULL)
+      def to_h
+        super.merge(local_storage: local_storage)
       end
 
-      # Loads configuration from a hash (typically from YAML).
-      #
-      # @param hash [Hash] Configuration hash
-      # @return [self]
-      def load_from_hash(hash)
-        hash = hash.with_indifferent_access if hash.respond_to?(:with_indifferent_access)
-
-        @enabled = hash[:enabled] if hash.key?(:enabled)
-        @endpoint = hash[:endpoint] if hash.key?(:endpoint)
-        @api_key = hash[:api_key] if hash.key?(:api_key)
-        @sample_rate = hash[:sample_rate].to_f if hash.key?(:sample_rate)
-        @batch_size = hash[:batch_size].to_i if hash.key?(:batch_size)
-        @flush_interval = hash[:flush_interval].to_i if hash.key?(:flush_interval)
-        @timeout = hash[:timeout].to_i if hash.key?(:timeout)
-        @capture_bodies = hash[:capture_bodies] if hash.key?(:capture_bodies)
-        @redact_attributes = hash[:redact_attributes] if hash.key?(:redact_attributes)
-        @service_name = hash[:service_name] if hash.key?(:service_name)
-        @environment = hash[:environment] if hash.key?(:environment)
-        @resource_attributes = hash[:resource_attributes] if hash.key?(:resource_attributes)
-        @local_storage = hash[:local_storage] if hash.key?(:local_storage)
-
-        self
-      end
+      private
 
-      # Returns configuration as a hash for serialization.
+      # Persists a trace through the dashboard's trace model, honoring
+      # ActionAgent.trace_model_class overrides. Idempotent on trace_id, as
+      # HTTP ingest is.
       #
-      # @return [Hash]
-      def to_h
-        {
-          enabled: enabled,
-          endpoint: endpoint,
-          api_key: api_key ? "[REDACTED]" : nil,
-          sample_rate: sample_rate,
-          batch_size: batch_size,
-          flush_interval: flush_interval,
-          timeout: timeout,
-          capture_bodies: capture_bodies,
-          service_name: resolved_service_name,
-          environment: environment,
-          local_storage: local_storage
-        }
+      # The dashboard is the `actionagent` gem, which the framework does not
+      # depend on — every reference to it here is guarded, so local_storage
+      # simply reports that it has nowhere to write when it isn't installed.
+      def dashboard_store
+        @dashboard_store ||= lambda do |trace, sdk|
+          model = local_trace_model
+          unless model
+            resolved_logger.error(
+              "[ActiveAgent::Telemetry] local_storage is enabled but no trace model is available — " \
+              "add the actionagent gem and run `rails generate action_agent:install` first"
+            )
+            next
+          end
+
+          next if model.exists?(trace_id: trace["trace_id"])
+
+          model.create_from_payload(trace, sdk)
+        end
       end
 
-      private
+      def local_trace_model
+        if defined?(::ActionAgent) && ::ActionAgent.respond_to?(:trace_model)
+          ::ActionAgent.trace_model
+        elsif defined?(::ActionAgent::TelemetryTrace)
+          ::ActionAgent::TelemetryTrace
+        end
+      rescue NameError
+        nil
+      end
 
-      def rails_app_name
-        return nil unless defined?(Rails) && Rails.application
+      # The engine's mount point in the host app, found by locating the
+      # mounted engine in the host's route set. Works regardless of the
+      # helper name, so `mount ... => "/", as: :something_else` and
+      # constraint-wrapped mounts resolve correctly. Returns nil when the
+      # engine isn't mounted or no Rails app is booted; "" for a root mount.
+      def dashboard_mount_path
+        return nil unless defined?(::Rails) && ::Rails.respond_to?(:application) && ::Rails.application
 
-        Rails.application.class.module_parent_name.underscore
+        mount_path_in(::Rails.application.routes)
       rescue StandardError
         nil
       end
+
+      # The engine's mount path within a given route set, or nil when it
+      # isn't mounted there. Separate from #dashboard_mount_path so it can be
+      # exercised against a route set directly.
+      public def mount_path_in(route_set)
+        return nil unless defined?(::ActionAgent::Engine)
+
+        route = route_set.routes.find do |candidate|
+          mounted_engine(candidate.app) == ::ActionAgent::Engine
+        end
+        return nil unless route
+
+        # "/activeagents(.:format)" -> "/activeagents"; a root mount -> "".
+        route.path.spec.to_s.sub(/\(\.:format\)\z/, "").chomp("/")
+      end
+
+      # Unwraps the constraint layers Rails wraps a mounted engine in,
+      # returning the engine class (or nil for ordinary routes). Stops at the
+      # engine class itself — engines also respond to #app (their route set),
+      # so unwrapping blindly walks straight past them.
+      def mounted_engine(app)
+        5.times do
+          return app if app.is_a?(Class) && app < ::Rails::Engine
+          break unless app.respond_to?(:app) && !app.app.equal?(app)
+
+          app = app.app
+        end
+        nil
+      end
     end
   end
 end

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
@@ -91,10 +147,28 @@ module ActiveAgent
                   tool_span = span.add_span("tool.#{tool_call[:name]}", span_type: :tool)
                   tool_span.set_attribute("tool.name", tool_call[:name])
                   tool_span.set_attribute("tool.id", tool_call[:id]) if tool_call[:id]
+                  ToolOrigin.annotate(tool_span, tool_call[:name])
                   tool_span.finish
                 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 +179,47 @@ 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)
+            # Records which MCP server (if any) serves this tool, so tool
+            # traffic can be grouped by service downstream.
+            ToolOrigin.annotate(tool_span, tool_name)
+            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 +231,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 +253,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