chronos-ruby 0.7.0.pre.1 → 0.9.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/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,50 @@
+module Chronos
+  # Public entry points for optional observability and deployment integrations.
+  #
+  # @responsibility Delegate dependency, cache, outbound HTTP, and deploy 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 notify_deploy(attributes = {}, timeout = Agent::DEFAULT_FLUSH_TIMEOUT)
+      agent = current_agent
+      agent ? agent.notify_deploy(attributes, timeout) : 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.
@@ -30,6 +30,10 @@ module Chronos
         @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
@@ -148,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
 

data/lib/chronos/version.rb

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

data/lib/chronos.rb

@@ -14,10 +14,13 @@ require "chronos/core/notice_builder"
 require "chronos/core/sensitive_value_filter"
 require "chronos/core/sanitizer"
 require "chronos/core/safe_serializer"
+require "chronos/core/correlation_context"
+require "chronos/core/deploy_normalizer"
 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"
@@ -32,9 +35,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"
@@ -55,6 +61,8 @@ require "chronos/integrations/rack/middleware"
 #   end
 #   Chronos.notify(RuntimeError.new("failed"))
 module Chronos
+  extend ObservabilityFacade
+
   @mutex = Mutex.new
   @agent = nil
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: chronos-ruby
 version: !ruby/object:Gem::Version
-  version: 0.7.0.pre.1
+  version: 0.9.0.pre.1
 platform: ruby
 authors:
 - Antonio Jefferson
@@ -87,6 +87,8 @@ files:
 - README.md
 - SECURITY.md
 - contracts/apm-batch-v1.schema.json
+- contracts/dependencies-v1.schema.json
+- contracts/deploy-v1.schema.json
 - contracts/event-v1.schema.json
 - contracts/rack-context-v1.schema.json
 - contracts/sidekiq-job-v1.schema.json
@@ -101,6 +103,8 @@ files:
 - 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/adr/ADR-017-deploy-events-and-correlation.md
 - docs/architecture.md
 - docs/compatibility.md
 - docs/configuration.md
@@ -108,7 +112,11 @@ files:
 - 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/deploy-tracking.md
+- docs/modules/external-http.md
 - docs/modules/notice-pipeline.md
 - docs/modules/rack-context.md
 - docs/modules/rails-legacy.md
@@ -129,12 +137,15 @@ files:
 - 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/capistrano.rb
 - lib/chronos/configuration.rb
 - lib/chronos/configuration/apm_validation.rb
 - lib/chronos/configuration/snapshot.rb
@@ -142,6 +153,9 @@ files:
 - lib/chronos/core.rb
 - lib/chronos/core/backtrace_parser.rb
 - lib/chronos/core/breadcrumb.rb
+- lib/chronos/core/cache_normalizer.rb
+- lib/chronos/core/correlation_context.rb
+- lib/chronos/core/deploy_normalizer.rb
 - lib/chronos/core/exception_cause_collector.rb
 - lib/chronos/core/metric_aggregate.rb
 - lib/chronos/core/notice.rb
@@ -155,7 +169,9 @@ files:
 - lib/chronos/core/telemetry_event.rb
 - lib/chronos/errors.rb
 - lib/chronos/integrations.rb
+- lib/chronos/integrations/capistrano.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
@@ -164,6 +180,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