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

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/integrations/rack/middleware.rb

@@ -38,11 +38,14 @@ module Chronos
           response = @app.call(env)
           status = response[0]
           headers = response[1]
-          add_request_breadcrumb("request completed", dynamic_request_context(base, status, headers, started_at))
+          context = dynamic_request_context(base, status, headers, started_at)
+          add_request_breadcrumb("request completed", context)
+          record_request_metric(context)
           response
         rescue Exception => error # rubocop:disable Lint/RescueException
           context = dynamic_request_context(base, 500, nil, started_at)
           notify_safely(error, context)
+          record_request_metric(context)
           raise
         end
 
@@ -141,6 +144,21 @@ module Chronos
           )
         end
 
+        def record_request_metric(context)
+          request = context[:context]["request"]
+          payload = {
+            "kind" => "rack", "route" => request["route"], "method" => request["method"],
+            "status" => request["status"], "duration_ms" => request["duration_ms"]
+          }
+          if @notifier.respond_to?(:record_event_once)
+            @notifier.record_event_once("request", "request", payload)
+          elsif @notifier.respond_to?(:record_event)
+            @notifier.record_event("request", payload)
+          end
+        rescue StandardError
+          false
+        end
+
         def hash_value(value)
           value.is_a?(Hash) ? value : {}
         end

data/lib/chronos/integrations/sidekiq.rb

@@ -176,6 +176,8 @@ module Chronos
           propagated = {} unless propagated.is_a?(Hash)
           {
             :context => propagated.merge("job" => job_context(payload)),
+            :parameters => {"arguments" => payload["arguments"]},
+            :tags => payload["tags"],
             :__chronos_captured_exceptions => {}
           }
         end

data/lib/chronos/net_http.rb

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

data/lib/chronos/observability_facade.rb

@@ -0,0 +1,43 @@
+module Chronos
+  # Public entry points for optional version 0.8 observability integrations.
+  #
+  # @responsibility Delegate dependency, cache, and outbound HTTP integration calls to the agent.
+  # @motivation Keep the main public facade small while preserving one stable Chronos namespace.
+  # @limits It installs only explicitly supplied Net::HTTP connections and never enables features.
+  # @collaborators Chronos::Agent and Chronos::Integrations::NetHttp.
+  # @thread_safety Agent access uses the facade's synchronized current_agent lookup.
+  # @compatibility Ruby 2.2.10 through Ruby 2.6.
+  # @example
+  #   Chronos.instrument_net_http(Net::HTTP.new("api.example.com"))
+  # @errors Integration failures return false or safe disabled options.
+  # @performance Delegation is constant-time; dependency collection remains at-most-once.
+  module ObservabilityFacade
+    def report_dependencies
+      agent = current_agent
+      agent ? agent.report_dependencies : false
+    rescue StandardError
+      false
+    end
+
+    def external_http_integration_options
+      agent = current_agent
+      agent ? agent.external_http_integration_options : {:enabled => false}
+    rescue StandardError
+      {:enabled => false}
+    end
+
+    def cache_integration_options
+      agent = current_agent
+      agent ? agent.cache_integration_options : {:project_id => "", :key_mode => :none}
+    rescue StandardError
+      {:project_id => "", :key_mode => :none}
+    end
+
+    def instrument_net_http(connection, options = {})
+      require "chronos/net_http"
+      Integrations::NetHttp.install(connection, options.merge(:notifier => self))
+    rescue StandardError
+      false
+    end
+  end
+end

data/lib/chronos/rails/notifications_subscriber.rb

@@ -4,7 +4,7 @@ module Chronos
     #
     # @responsibility Subscribe once and normalize controller, view, SQL, mailer, job, and cache events.
     # @motivation Support Rails 4.2 and 5.2 through feature detection and public notification APIs.
-    # @limits It never sends SQL text, bind values, cache keys, mail bodies, or job arguments.
+    # @limits It never sends SQL text, binds, raw cache keys/values, mail bodies, or job arguments.
     # @collaborators ActiveSupport::Notifications and the Chronos facade.
     # @thread_safety Subscription registry is mutex-protected; callbacks own their state.
     # @compatibility ActiveSupport notification argument shapes from Rails 4.2 through 5.2.
@@ -29,6 +29,11 @@ module Chronos
       def initialize(notifier = Chronos, notifications = nil)
         @notifier = notifier
         @notifications = notifications || active_support_notifications
+        @sql_normalizer = Core::SqlNormalizer.new
+        cache_options = notifier.respond_to?(:cache_integration_options) ? notifier.cache_integration_options : {}
+        @cache_normalizer = Core::CacheNormalizer.new(
+          cache_options[:project_id].to_s, cache_options[:key_mode] || :none
+        )
       end
 
       def install
@@ -105,7 +110,7 @@ module Chronos
           "route" => route(payload),
           "duration_ms" => duration, "parameters" => hash(value(payload, :params))
         }
-        @notifier.record_event("request", data)
+        record_once("request", "request", data)
       end
 
       def render_template(payload, duration)
@@ -117,10 +122,15 @@ module Chronos
       end
 
       def sql(payload, duration)
-        data = {
-          "name" => value(payload, :name).to_s, "cached" => value(payload, :cached) == true,
-          "duration_ms" => duration
+        metadata = {
+          :name => value(payload, :name), :cached => value(payload, :cached),
+          :adapter => value(payload, :adapter), :connection => value(payload, :connection),
+          :role => value(payload, :connection_role) || value(payload, :role),
+          :shard => value(payload, :connection_shard) || value(payload, :shard),
+          :exception_object => value(payload, :exception_object), :exception => value(payload, :exception)
         }
+        metadata[:source] = sampled_query_source if duration >= slow_query_threshold
+        data = @sql_normalizer.call(value(payload, :sql), metadata).merge("duration_ms" => duration)
         @notifier.record_event("query", data)
       end
 
@@ -142,10 +152,7 @@ module Chronos
       end
 
       def cache(name, payload, duration)
-        data = {
-          "operation" => name.split(".").first, "store" => value(payload, :store).to_s,
-          "hit" => value(payload, :hit), "duration_ms" => duration
-        }
+        data = @cache_normalizer.call(name, payload).merge("duration_ms" => duration)
         @notifier.record_event("cache", data)
       end
 
@@ -198,6 +205,32 @@ module Chronos
       rescue StandardError
         ""
       end
+
+      def record_once(key, event_type, payload)
+        if @notifier.respond_to?(:record_event_once)
+          @notifier.record_event_once(key, event_type, payload)
+        else
+          @notifier.record_event(event_type, payload)
+        end
+      end
+
+      def slow_query_threshold
+        options = @notifier.respond_to?(:apm_integration_options) ? @notifier.apm_integration_options : {}
+        (options[:slow_query_threshold_ms] || 500.0).to_f
+      rescue StandardError
+        500.0
+      end
+
+      def sampled_query_source
+        options = @notifier.respond_to?(:apm_integration_options) ? @notifier.apm_integration_options : {}
+        root = options[:root_directory].to_s
+        frame = caller.find do |line|
+          (root.empty? || line.start_with?(root)) && line !~ %r{/lib/chronos/}
+        end
+        frame.to_s.sub(/:in .*/, "")[0, 256]
+      rescue StandardError
+        ""
+      end
     end
   end
 end

data/lib/chronos/version.rb

@@ -1,4 +1,4 @@
 module Chronos
   # Current version of the legacy Chronos Ruby agent.
-  VERSION = "0.6.0.pre.1".freeze
+  VERSION = "0.8.0.pre.1".freeze
 end

data/lib/chronos.rb

@@ -16,6 +16,9 @@ require "chronos/core/sanitizer"
 require "chronos/core/safe_serializer"
 require "chronos/core/payload_serializer"
 require "chronos/core/telemetry_event"
+require "chronos/core/sql_normalizer"
+require "chronos/core/metric_aggregate"
+require "chronos/core/cache_normalizer"
 require "chronos/ports/transport"
 require "chronos/ports/context_store"
 require "chronos/internal/safe_logger"
@@ -30,8 +33,12 @@ require "chronos/application/circuit_breaker"
 require "chronos/application/remote_configuration"
 require "chronos/application/delivery_pipeline"
 require "chronos/application/capture_exception"
+require "chronos/application/apm_error_classifier"
+require "chronos/application/apm_aggregator"
+require "chronos/application/dependency_reporter"
 require "chronos/application/capture_telemetry"
 require "chronos/agent"
+require "chronos/observability_facade"
 require "chronos/integrations"
 require "chronos/integrations/rack"
 require "chronos/integrations/rack/middleware"
@@ -52,6 +59,8 @@ require "chronos/integrations/rack/middleware"
 #   end
 #   Chronos.notify(RuntimeError.new("failed"))
 module Chronos
+  extend ObservabilityFacade
+
   @mutex = Mutex.new
   @agent = nil
 
@@ -104,6 +113,20 @@ module Chronos
       false
     end
 
+    def record_event_once(key, event_type, payload = {}, context = {})
+      agent = current_agent
+      agent ? agent.record_event_once(key, event_type, payload, context) : false
+    rescue StandardError
+      false
+    end
+
+    def apm_integration_options
+      agent = current_agent
+      agent ? agent.apm_integration_options : {:enabled => false}
+    rescue StandardError
+      {:enabled => false}
+    end
+
     # Returns only trace/request identifiers for optional process-boundary adapters.
     def propagation_context
       agent = current_agent

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: chronos-ruby
 version: !ruby/object:Gem::Version
-  version: 0.6.0.pre.1
+  version: 0.8.0.pre.1
 platform: ruby
 authors:
 - Antonio Jefferson
@@ -86,6 +86,8 @@ files:
 - LICENSE.txt
 - README.md
 - SECURITY.md
+- contracts/apm-batch-v1.schema.json
+- contracts/dependencies-v1.schema.json
 - contracts/event-v1.schema.json
 - contracts/rack-context-v1.schema.json
 - contracts/sidekiq-job-v1.schema.json
@@ -99,13 +101,19 @@ files:
 - docs/adr/ADR-012-rack-context-isolation.md
 - docs/adr/ADR-013-legacy-rails-notifications.md
 - docs/adr/ADR-014-sidekiq-envelope-context.md
+- docs/adr/ADR-015-bounded-apm-aggregation.md
+- docs/adr/ADR-016-explicit-observability-integrations.md
 - docs/architecture.md
 - docs/compatibility.md
 - docs/configuration.md
 - docs/data-collected.md
 - docs/examples/plain-ruby.md
+- docs/modules/apm-aggregation.md
 - docs/modules/async-queue.md
+- docs/modules/cache-observability.md
 - docs/modules/configuration.md
+- docs/modules/dependencies.md
+- docs/modules/external-http.md
 - docs/modules/notice-pipeline.md
 - docs/modules/rack-context.md
 - docs/modules/rails-legacy.md
@@ -125,19 +133,25 @@ files:
 - lib/chronos/adapters/thread_local_context_store.rb
 - lib/chronos/agent.rb
 - lib/chronos/application.rb
+- lib/chronos/application/apm_aggregator.rb
+- lib/chronos/application/apm_error_classifier.rb
 - lib/chronos/application/capture_exception.rb
 - lib/chronos/application/capture_telemetry.rb
 - lib/chronos/application/circuit_breaker.rb
 - lib/chronos/application/delivery_pipeline.rb
+- lib/chronos/application/dependency_reporter.rb
 - lib/chronos/application/remote_configuration.rb
 - lib/chronos/application/retry_policy.rb
 - lib/chronos/configuration.rb
+- lib/chronos/configuration/apm_validation.rb
 - lib/chronos/configuration/snapshot.rb
 - lib/chronos/configuration/validation.rb
 - lib/chronos/core.rb
 - lib/chronos/core/backtrace_parser.rb
 - lib/chronos/core/breadcrumb.rb
+- lib/chronos/core/cache_normalizer.rb
 - lib/chronos/core/exception_cause_collector.rb
+- lib/chronos/core/metric_aggregate.rb
 - lib/chronos/core/notice.rb
 - lib/chronos/core/notice_builder.rb
 - lib/chronos/core/payload_serializer.rb
@@ -145,10 +159,12 @@ files:
 - lib/chronos/core/safe_serializer.rb
 - lib/chronos/core/sanitizer.rb
 - lib/chronos/core/sensitive_value_filter.rb
+- lib/chronos/core/sql_normalizer.rb
 - lib/chronos/core/telemetry_event.rb
 - lib/chronos/errors.rb
 - lib/chronos/integrations.rb
 - lib/chronos/integrations/job_payload.rb
+- lib/chronos/integrations/net_http.rb
 - lib/chronos/integrations/rack.rb
 - lib/chronos/integrations/rack/middleware.rb
 - lib/chronos/integrations/sidekiq.rb
@@ -157,6 +173,8 @@ files:
 - lib/chronos/internal/memory_backlog.rb
 - lib/chronos/internal/safe_logger.rb
 - lib/chronos/internal/worker_pool.rb
+- lib/chronos/net_http.rb
+- lib/chronos/observability_facade.rb
 - lib/chronos/ports.rb
 - lib/chronos/ports/context_store.rb
 - lib/chronos/ports/transport.rb