chronos-ruby 0.7.0.pre.1 → 0.8.0.pre.1

data/lib/chronos/agent.rb

@@ -37,13 +37,16 @@ module Chronos
         pipeline_options
       )
       initialize_capture(options)
+      @dependency_reporter = options[:dependency_reporter] || Application::DependencyReporter.new(config)
     end
 
     def notify(exception, context = {})
+      report_dependencies
       @capture.call(exception, context_for_capture(context))
     end
 
     def notify_sync(exception, context = {})
+      report_dependencies
       @capture.call_sync(exception, context_for_capture(context))
     end
 
@@ -64,9 +67,20 @@ module Chronos
     end
 
     def record_event(event_type, payload = {}, context = {})
+      report_dependencies unless event_type.to_s == "dependencies"
       @telemetry.call(event_type, payload, telemetry_context(context))
     end
 
+    def report_dependencies
+      payload = @dependency_reporter.call
+      return false unless payload
+
+      @telemetry.call("dependencies", payload, {})
+    rescue StandardError => error
+      @logger.warn("Chronos dependency reporting failed: #{error.class}")
+      false
+    end
+
     def record_event_once(key, event_type, payload = {}, context = {})
       execution = @context_store.get
       captured = execution[:__chronos_captured_events] || {}
@@ -87,6 +101,14 @@ module Chronos
       }
     end
 
+    def external_http_integration_options
+      {:enabled => @config.external_http_enabled, :trace_headers => @config.external_http_trace_headers}
+    end
+
+    def cache_integration_options
+      {:project_id => @config.project_id, :key_mode => @config.cache_key_mode}
+    end
+
     # Returns the correlation subset safe for an integration-owned process boundary.
     def propagation_context
       current = context_hash(@context_store.get)
@@ -124,6 +146,7 @@ module Chronos
     end
 
     def flush(timeout = DEFAULT_FLUSH_TIMEOUT)
+      report_dependencies
       @telemetry.flush
       @delivery_pipeline.flush(timeout)
     rescue StandardError => error
@@ -132,6 +155,7 @@ module Chronos
     end
 
     def close(timeout = DEFAULT_FLUSH_TIMEOUT)
+      report_dependencies
       @telemetry.flush
       @delivery_pipeline.close(timeout)
     rescue StandardError => error

data/lib/chronos/application/apm_aggregator.rb

@@ -1,6 +1,6 @@
 module Chronos
   module Application
-    # Aggregates bounded request, query, and job observations into metric batches.
+    # Aggregates bounded request, query, job, and external HTTP observations into metric batches.
     #
     # @responsibility Maintain statistics, histograms, breakdown, and local query signals.
     # @motivation Avoid one network event per observation while retaining diagnostic value.
@@ -14,7 +14,9 @@ module Chronos
     # @errors Invalid observations are ignored and never escape to the application.
     # @performance Group, transaction, query, bucket, and batch counts are strictly bounded.
     class ApmAggregator
-      METRIC_TYPES = %w(request query job).freeze
+      include ApmErrorClassifier
+
+      METRIC_TYPES = %w(request query job external_http).freeze
       def initialize(config)
         @config = config
         @mutex = Mutex.new
@@ -77,7 +79,7 @@ module Chronos
           @groups[key] = aggregate
         end
         duration = non_negative(payload["duration_ms"] || payload[:duration_ms])
-        status = type == "request" ? payload["status"] || payload[:status] : nil
+        status = ["request", "external_http"].include?(type) ? payload["status"] || payload[:status] : nil
         signals = signals_for(type, payload, context, duration)
         breakdown = breakdown_for(type, payload, context, duration)
         aggregate.observe(
@@ -177,6 +179,7 @@ module Chronos
                 when "request" then %w(route method)
                 when "query" then %w(adapter operation table fingerprint normalized_query name cached role shard source)
                 when "job" then %w(kind class queue status)
+                when "external_http" then %w(host method)
                 else []
                 end
         names.each_with_object({}) do |name, result|
@@ -211,17 +214,11 @@ module Chronos
         return "view" if type == "request" && payload["kind"].to_s == "view"
         return "cache" if type == "cache"
         return "queue" if type == "job"
+        return "external_http" if type == "external_http"
 
         nil
       end
 
-      def error?(type, payload)
-        return (payload["status"] || payload[:status]).to_i >= 500 if type == "request"
-        return (payload["status"] || payload[:status]).to_s == "failed" if type == "job"
-
-        !(payload["error_class"] || payload[:error_class]).to_s.empty?
-      end
-
       def trace_id(context)
         (context["trace_id"] || context[:trace_id]).to_s
       end

data/lib/chronos/application/apm_error_classifier.rb

@@ -0,0 +1,27 @@
+module Chronos
+  module Application
+    # Classifies bounded APM observations without inspecting exception messages.
+    module ApmErrorClassifier
+      private
+
+      def error?(type, payload)
+        return status_error?(payload) if type == "request"
+        return (payload["status"] || payload[:status]).to_s == "failed" if type == "job"
+        return external_http_error?(payload) if type == "external_http"
+
+        !(payload["error_class"] || payload[:error_class]).to_s.empty?
+      end
+
+      def external_http_error?(payload)
+        return true unless (payload["error_class"] || payload[:error_class]).to_s.empty?
+        return true if payload["timeout"] == true || payload[:timeout] == true
+
+        status_error?(payload)
+      end
+
+      def status_error?(payload)
+        (payload["status"] || payload[:status]).to_i >= 500
+      end
+    end
+  end
+end

data/lib/chronos/application/capture_telemetry.rb

@@ -4,7 +4,7 @@ module Chronos
     #
     # @responsibility Aggregate APM observations or serialize and enqueue integration events.
     # @motivation Keep framework policy and local batching outside transport and domain objects.
-    # @limits It handles request, query, job, cache, and metric-batch events only.
+    # @limits It handles only the event types declared by TelemetryEvent.
     # @collaborators ApmAggregator, TelemetryEvent, TelemetrySerializer, and DeliveryPipeline.
     # @thread_safety Calls own event state and may execute concurrently.
     # @compatibility Ruby 2.2.10 through Ruby 2.6; independent of Rails.

data/lib/chronos/application/dependency_reporter.rb

@@ -0,0 +1,129 @@
+module Chronos
+  module Application
+    # Builds one bounded inventory from already loaded runtime components.
+    #
+    # @responsibility Report loaded gems and runtime/framework versions once per agent.
+    # @motivation Dependency context aids diagnosis without attaching the bundle to every error.
+    # @limits It does not read lockfiles, environment variables, gem paths, or open DB connections.
+    # @collaborators RubyGems loaded specs and immutable Chronos configuration.
+    # @thread_safety A mutex guarantees at-most-once collection across concurrent first events.
+    # @compatibility Ruby 2.2.10 through Ruby 2.6; all framework detection is optional.
+    # @example
+    #   payload = DependencyReporter.new(config).call
+    # @errors Detection failures yield omitted fields and never escape.
+    # @performance Runs once and visits at most the configured number of loaded specs.
+    class DependencyReporter
+      def initialize(config, options = {})
+        @config = config
+        @loaded_specs = options[:loaded_specs] || proc { Gem.loaded_specs }
+        @constants = options[:constants] || {}
+        @mutex = Mutex.new
+        @reported = false
+      end
+
+      def call
+        @mutex.synchronize do
+          return nil if @reported || !@config.dependency_reporting
+
+          @reported = true
+          build_payload
+        end
+      rescue StandardError
+        nil
+      end
+
+      private
+
+      def build_payload
+        payload = {
+          "dependencies" => dependencies,
+          "ruby" => {
+            "version" => bounded(RUBY_VERSION, 64), "engine" => bounded(ruby_engine, 64),
+            "platform" => bounded(RUBY_PLATFORM, 128)
+          },
+          "rails" => detected("rails") { rails_version },
+          "web_server" => detected("web_server") { web_server },
+          "database_adapter" => detected("database_adapter") { database_adapter },
+          "sidekiq" => detected("sidekiq") { sidekiq_version },
+          "release" => bounded(@config.app_version.to_s, 128)
+        }
+        payload.delete_if do |key, value|
+          !["dependencies", "ruby"].include?(key) && value.to_s.empty?
+        end
+        payload
+      end
+
+      def dependencies
+        specs = @loaded_specs.call
+        values = specs.respond_to?(:values) ? specs.values : []
+        values.first(@config.dependency_max_items).sort_by { |spec| spec.name.to_s }.map do |spec|
+          {"name" => bounded(spec.name.to_s, 128), "version" => bounded(spec.version.to_s, 64)}
+        end
+      rescue StandardError
+        []
+      end
+
+      def detected(name)
+        explicit = @constants[name]
+        return bounded(explicit.to_s, 128) unless explicit.nil?
+
+        bounded(yield.to_s, 128)
+      rescue StandardError
+        ""
+      end
+
+      def rails_version
+        defined?(::Rails) && ::Rails.respond_to?(:version) ? ::Rails.version.to_s : loaded_version("rails")
+      end
+
+      def sidekiq_version
+        defined?(::Sidekiq::VERSION) ? ::Sidekiq::VERSION.to_s : loaded_version("sidekiq")
+      end
+
+      def web_server
+        return "Puma" if defined?(::Puma)
+        return "Unicorn" if defined?(::Unicorn)
+        return "Passenger" if defined?(::PhusionPassenger)
+        return "WEBrick" if defined?(::WEBrick)
+
+        ""
+      end
+
+      def database_adapter
+        names = loaded_spec_names
+        return "PostgreSQL" if names.include?("pg")
+        return "MySQL" if names.include?("mysql2")
+        return "SQLite" if names.include?("sqlite3")
+
+        ""
+      end
+
+      def loaded_version(name)
+        specs = @loaded_specs.call
+        spec = specs[name] || specs[name.to_sym] if specs.respond_to?(:[])
+        spec ? spec.version.to_s : ""
+      rescue StandardError
+        ""
+      end
+
+      def loaded_spec_names
+        specs = @loaded_specs.call
+        specs.respond_to?(:keys) ? specs.keys.map(&:to_s) : []
+      rescue StandardError
+        []
+      end
+
+      def ruby_engine
+        defined?(RUBY_ENGINE) ? RUBY_ENGINE : "ruby"
+      end
+
+      def bounded(value, limit)
+        text = value.to_s
+        text = text.scrub("?") if text.respond_to?(:scrub)
+        text.bytesize > limit ? text.byteslice(0, limit) : text
+      rescue StandardError
+        ""
+      end
+    end
+  end
+end

data/lib/chronos/application/remote_configuration.rb

@@ -13,7 +13,9 @@ module Chronos
     # @errors Invalid documents are ignored and return false.
     # @performance Validation is bounded by configured document and list limits.
     class RemoteConfiguration
-      SUPPORTED_EVENT_TYPES = ["exception", "request", "query", "job", "cache", "metric_batch"].freeze
+      SUPPORTED_EVENT_TYPES = %w(
+        exception request query job cache external_http dependencies metric_batch
+      ).freeze
       MAX_IGNORED_FINGERPRINTS = 100
       MAX_FINGERPRINT_BYTES = 256
       MIN_PAYLOAD_SIZE = 256

data/lib/chronos/configuration/apm_validation.rb

@@ -2,7 +2,7 @@ module Chronos
   module Internal
     # Validates bounded APM aggregation, histogram, and detector settings.
     #
-    # @responsibility Return configuration errors for version 0.7 APM options.
+    # @responsibility Return configuration errors for bounded APM and observability options.
     # @motivation Keep the general configuration validator focused and maintainable.
     # @limits It validates shape and bounds but does not allocate aggregator state.
     # @collaborators Chronos::Configuration predicates and attributes.
@@ -55,6 +55,22 @@ module Chronos
 
         values.each_cons(2).all? { |left, right| right > left }
       end
+
+      def observability_errors
+        errors = []
+        errors << "external_http_enabled must be true or false" unless boolean?(external_http_enabled)
+        errors << "external_http_trace_headers must be true or false" unless boolean?(external_http_trace_headers)
+        errors << "cache_key_mode must be :none or :sha256" unless [:none, :sha256].include?(cache_key_mode)
+        errors << "dependency_reporting must be true or false" unless boolean?(dependency_reporting)
+        unless dependency_max_items.is_a?(Integer) && dependency_max_items >= 1 && dependency_max_items <= 200
+          errors << "dependency_max_items must be between 1 and 200"
+        end
+        errors
+      end
+
+      def boolean?(value)
+        [true, false].include?(value)
+      end
     end
   end
 end

data/lib/chronos/configuration.rb

@@ -46,7 +46,8 @@ module Chronos
       :apm_enabled, :apm_max_groups, :apm_flush_count, :apm_batch_size,
       :apm_max_queries_per_request, :apm_slow_query_threshold_ms,
       :apm_long_transaction_threshold_ms, :apm_n_plus_one_threshold,
-      :apm_histogram_buckets
+      :apm_histogram_buckets, :external_http_enabled, :external_http_trace_headers,
+      :cache_key_mode, :dependency_reporting, :dependency_max_items
     ].freeze
 
     attr_accessor(*ATTRIBUTES)
@@ -57,6 +58,7 @@ module Chronos
       initialize_resilience_defaults
       initialize_rails_defaults
       initialize_apm_defaults
+      initialize_observability_defaults
     end
 
     def snapshot
@@ -86,6 +88,7 @@ module Chronos
       errors.concat(privacy_errors)
       errors.concat(context_errors)
       errors.concat(apm_errors)
+      errors.concat(observability_errors)
       errors
     end
 
@@ -136,6 +139,14 @@ module Chronos
       @apm_histogram_buckets = [5.0, 10.0, 25.0, 50.0, 100.0, 250.0, 500.0, 1000.0, 2500.0, 5000.0]
     end
 
+    def initialize_observability_defaults
+      @external_http_enabled = false
+      @external_http_trace_headers = true
+      @cache_key_mode = :none
+      @dependency_reporting = true
+      @dependency_max_items = 100
+    end
+
     def initialize_privacy_defaults
       @blocklist_keys = DEFAULT_BLOCKLIST_KEYS.dup
       @allowlist_keys = []
@@ -155,7 +166,9 @@ module Chronos
       @remote_configuration = true
       @remote_config_max_bytes = 4096
       @sampling_rate = 1.0
-      @enabled_event_types = ["exception", "request", "query", "job", "cache", "metric_batch"]
+      @enabled_event_types = [
+        "exception", "request", "query", "job", "cache", "external_http", "dependencies", "metric_batch"
+      ]
       @max_remote_send_interval = 60.0
     end
 

data/lib/chronos/core/cache_normalizer.rb

@@ -0,0 +1,99 @@
+require "digest"
+
+module Chronos
+  module Core
+    # Produces bounded cache metadata without exposing raw cache keys or values.
+    #
+    # @responsibility Normalize operation, backend, namespace, outcome, and optional key hash.
+    # @motivation Cache telemetry needs diagnostic identity without leaking application keys.
+    # @limits It never reads cache values and hashes keys only after explicit opt-in.
+    # @collaborators Rails notification subscriber and Chronos configuration.
+    # @thread_safety Instances hold only immutable scalar configuration.
+    # @compatibility Ruby 2.2.10 through Ruby 2.6.
+    # @example
+    #   CacheNormalizer.new("project", :none).call(name, payload)
+    # @errors Unreadable fields become empty bounded strings.
+    # @performance Constant work plus SHA-256 only when key hashing is enabled.
+    class CacheNormalizer
+      def initialize(project_id, key_mode)
+        @project_id = project_id.to_s
+        @key_mode = key_mode
+      end
+
+      def call(name, payload = {})
+        hit = hit_value(name, payload)
+        result = {
+          "operation" => bounded(name.to_s.split(".").first, 64),
+          "backend" => backend(payload),
+          "namespace" => bounded(namespace(payload).to_s, 128),
+          "hit" => hit,
+          "outcome" => outcome(hit)
+        }
+        result["key_hash"] = key_hash(value(payload, :key)) if @key_mode == :sha256
+        result.delete_if { |key, child| child.to_s.empty? && key != "hit" }
+      rescue StandardError
+        {"operation" => "cache", "outcome" => "unknown"}
+      end
+
+      private
+
+      def outcome(hit)
+        return "unknown" if hit.nil?
+
+        hit ? "hit" : "miss"
+      end
+
+      def backend(payload)
+        store = value(payload, :store)
+        return "" if store.nil?
+
+        name = store.is_a?(String) || store.is_a?(Symbol) ? store.to_s : store.class.name.to_s
+        bounded(name, 128)
+      rescue StandardError
+        ""
+      end
+
+      def namespace(payload)
+        direct = value(payload, :namespace)
+        return direct unless direct.nil?
+
+        value(value(payload, :options), :namespace)
+      end
+
+      def hit_value(name, payload)
+        return true if name.to_s.start_with?("cache_fetch_hit")
+
+        hit = value(payload, :hit)
+        [true, false].include?(hit) ? hit : nil
+      end
+
+      def key_hash(key)
+        return nil if key.nil?
+
+        Digest::SHA256.hexdigest("#{@project_id}:cache:#{safe_key(key)}")
+      end
+
+      def safe_key(key)
+        text = key.to_s
+        text = text.scrub("?") if text.respond_to?(:scrub)
+        text.bytesize > 2048 ? text.byteslice(0, 2048) : text
+      rescue StandardError
+        "[UNREADABLE]"
+      end
+
+      def value(hash, key)
+        return nil unless hash.is_a?(Hash)
+
+        hash.key?(key) ? hash[key] : hash[key.to_s]
+      end
+
+      def bounded(value, limit)
+        text = value.to_s
+        text = text.scrub("?") if text.respond_to?(:scrub)
+        text.bytesize > limit ? text.byteslice(0, limit) : text
+      rescue StandardError
+        ""
+      end
+    end
+  end
+end

data/lib/chronos/core/telemetry_event.rb

@@ -16,7 +16,7 @@ module Chronos
     # @errors Unsupported types raise ArgumentError during construction.
     # @performance Construction is linear in supplied context and payload size.
     class TelemetryEvent
-      TYPES = %w(request query job cache metric_batch).freeze
+      TYPES = %w(request query job cache external_http dependencies metric_batch).freeze
 
       attr_reader :event_id, :event_type, :timestamp, :context, :payload
 

data/lib/chronos/integrations/net_http.rb

@@ -0,0 +1,165 @@
+module Chronos
+  module Integrations
+    # Optional per-instance Net::HTTP instrumentation without a global monkey patch.
+    #
+    # @responsibility Install one idempotent request wrapper on an explicit HTTP connection.
+    # @motivation Legacy Net::HTTP has no middleware callback but must remain safe and optional.
+    # @limits Class convenience methods and uninstrumented instances are deliberately untouched.
+    # @collaborators Net::HTTP-compatible connection, request objects, and Chronos notifier.
+    # @thread_safety Installation is synchronized per object; request state is call-local.
+    # @compatibility Net::HTTP on Ruby 2.2.10 through Ruby 2.6.
+    # @example
+    #   Chronos::Integrations::NetHttp.install(Net::HTTP.new("api.example.com"))
+    # @errors Instrumentation errors are contained; original HTTP errors are re-raised unchanged.
+    # @performance Adds bounded hashes and clock reads; never reads request/response bodies.
+    module NetHttp
+      INSTALLED_KEY = :@__chronos_net_http_installed
+      OPTIONS_KEY = :@__chronos_net_http_options
+
+      class << self
+        def install(connection, options = {})
+          notifier = options[:notifier] || Chronos
+          return false unless enabled?(notifier)
+          return false unless connection.respond_to?(:request) && connection.respond_to?(:address)
+
+          mutex_for(connection).synchronize do
+            return false if connection.instance_variable_get(INSTALLED_KEY)
+
+            connection.instance_variable_set(OPTIONS_KEY, instrumentation_options(notifier, options))
+            connection.singleton_class.send(:prepend, InstrumentedRequest)
+            connection.instance_variable_set(INSTALLED_KEY, true)
+          end
+          true
+        rescue StandardError
+          false
+        end
+
+        private
+
+        def enabled?(notifier)
+          return true unless notifier.respond_to?(:external_http_integration_options)
+
+          notifier.external_http_integration_options[:enabled] == true
+        rescue StandardError
+          false
+        end
+
+        def instrumentation_options(notifier, options)
+          configured = if notifier.respond_to?(:external_http_integration_options)
+                         notifier.external_http_integration_options
+                       else
+                         {}
+                       end
+          {
+            :notifier => notifier,
+            :clock => options[:clock] || proc { monotonic_time },
+            :trace_headers => configured.fetch(:trace_headers, true)
+          }
+        end
+
+        def mutex_for(connection)
+          key = :@__chronos_net_http_mutex
+          connection.instance_variable_get(key) || connection.instance_variable_set(key, Mutex.new)
+        end
+
+        def monotonic_time
+          Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        rescue StandardError
+          Time.now.to_f
+        end
+      end
+
+      # Request wrapper prepended only to an explicitly selected HTTP object.
+      #
+      # @responsibility Inject bounded trace headers and record outcome/timing around `request`.
+      # @motivation Preserve the native API, streaming block, and exception semantics.
+      # @limits It never reads URL path/query, Authorization, request body, headers, or response body.
+      # @collaborators NetHttp installation options and Chronos record_event.
+      # @thread_safety All request observations use local variables.
+      # @compatibility Net::HTTP#request signature on Ruby 2.2.10 through Ruby 2.6.
+      # @example
+      #   connection.request(Net::HTTP::Get.new("/health"))
+      # @errors Original StandardError values are recorded by class and re-raised unchanged.
+      # @performance Two clock reads and one asynchronous telemetry observation per call.
+      module InstrumentedRequest
+        def request(request, body = nil, &block)
+          options = instance_variable_get(NetHttp::OPTIONS_KEY)
+          started_at = options[:clock].call
+          inject_trace_headers(request, options) if options[:trace_headers]
+          response = super(request, body, &block)
+          record_external_http(options, request, started_at, response, nil)
+          response
+        rescue StandardError => error
+          record_external_http(options, request, started_at, nil, error) if options && started_at
+          raise
+        end
+
+        private
+
+        def inject_trace_headers(request, options)
+          return unless request.respond_to?(:[]) && request.respond_to?(:[]=)
+
+          context = if options[:notifier].respond_to?(:propagation_context)
+                      options[:notifier].propagation_context
+                    else
+                      {}
+                    end
+          set_header(request, "X-Chronos-Trace-ID", context["trace_id"] || context[:trace_id])
+          set_header(request, "X-Chronos-Request-ID", context["request_id"] || context[:request_id])
+        rescue StandardError
+          nil
+        end
+
+        def set_header(request, name, value)
+          request[name] = value.to_s if request[name].to_s.empty? && !value.to_s.empty?
+        end
+
+        def record_external_http(options, request, started_at, response, error)
+          payload = {
+            "host" => sanitized_external_host,
+            "method" => request.respond_to?(:method) ? request.method.to_s.upcase : "",
+            "status" => response_status(response),
+            "duration_ms" => ((options[:clock].call - started_at) * 1000.0).round(3),
+            "timeout" => timeout_error?(error),
+            "connection_error" => connection_error?(error),
+            "error_class" => error ? error.class.name.to_s : ""
+          }
+          payload.delete_if { |_key, value| value.nil? || value == "" }
+          options[:notifier].record_event("external_http", payload)
+        rescue StandardError
+          false
+        end
+
+        def response_status(response)
+          response.code.to_i if response && response.respond_to?(:code)
+        end
+
+        def sanitized_external_host
+          host = respond_to?(:address) ? address.to_s.downcase.sub(/\.\z/, "") : ""
+          host = host.scrub("?") if host.respond_to?(:scrub)
+          host.bytesize > 253 ? host.byteslice(0, 253) : host
+        rescue StandardError
+          ""
+        end
+
+        def timeout_error?(error)
+          return false unless error
+
+          error.is_a?(Timeout::Error) || !error.class.name.to_s.match(/Timeout/).nil?
+        rescue StandardError
+          false
+        end
+
+        def connection_error?(error)
+          return false unless error
+          return false if timeout_error?(error)
+
+          error.is_a?(SystemCallError) || error.is_a?(IOError) ||
+            !error.class.name.to_s.match(/SocketError|OpenSSL::SSL::SSLError/).nil?
+        rescue StandardError
+          false
+        end
+      end
+    end
+  end
+end

data/lib/chronos/net_http.rb

@@ -0,0 +1,4 @@
+require "net/http"
+require "timeout"
+require "chronos"
+require "chronos/integrations/net_http"