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

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,33 @@ 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
+        correlation_attributes.each do |name, value|
+          errors << "#{name} must be a String with at most 128 bytes" unless bounded_optional_string?(value, 128)
+        end
+        errors
+      end
+
+      def correlation_attributes
+        {:revision => revision, :deploy_id => deploy_id, :region => region, :instance_id => instance_id}
+      end
+
+      def bounded_optional_string?(value, limit)
+        value.nil? || (value.is_a?(String) && value.bytesize <= limit)
+      end
+
+      def boolean?(value)
+        [true, false].include?(value)
+      end
     end
   end
 end

data/lib/chronos/configuration.rb

@@ -32,7 +32,8 @@ module Chronos
 
     ATTRIBUTES = [
       :project_id, :project_key, :host, :environment, :app_version,
-      :service_name, :root_directory, :logger, :timeout, :open_timeout,
+      :service_name, :revision, :deploy_id, :region, :instance_id,
+      :root_directory, :logger, :timeout, :open_timeout,
       :queue_size, :workers, :enabled, :error_notifications,
       :ignored_environments, :proxy, :ssl_verify, :user_agent,
       :max_payload_size, :gzip, :blocklist_keys, :allowlist_keys,
@@ -46,7 +47,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 +59,8 @@ module Chronos
       initialize_resilience_defaults
       initialize_rails_defaults
       initialize_apm_defaults
+      initialize_observability_defaults
+      initialize_correlation_defaults
     end
 
     def snapshot
@@ -86,6 +90,7 @@ module Chronos
       errors.concat(privacy_errors)
       errors.concat(context_errors)
       errors.concat(apm_errors)
+      errors.concat(observability_errors)
       errors
     end
 
@@ -117,6 +122,13 @@ module Chronos
       @breadcrumb_max_bytes = 2048
     end
 
+    def initialize_correlation_defaults
+      @revision = nil
+      @deploy_id = nil
+      @region = nil
+      @instance_id = nil
+    end
+
     def initialize_rails_defaults
       @rails_enabled = true
       @rails_capture_in_console = false
@@ -136,6 +148,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 +175,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", "deploy", "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/correlation_context.rb

@@ -0,0 +1,65 @@
+module Chronos
+  module Core
+    # Builds the bounded release/deploy correlation shared by every event envelope.
+    #
+    # @responsibility Normalize release, revision, deploy, environment, service, region, and instance.
+    # @motivation Give the SaaS stable before/after-deploy dimensions without integration-specific fields.
+    # @limits Values come only from explicit configuration or caller overrides; no environment is scanned.
+    # @collaborators PayloadSerializer, TelemetrySerializer, and Configuration::Snapshot.
+    # @thread_safety Instances hold immutable configuration and calls allocate independent frozen hashes.
+    # @compatibility Ruby 2.2.10 through Ruby 2.6.
+    # @example
+    #   CorrelationContext.new(config).call("revision" => "abc123")
+    # @errors Unreadable optional values become nil and do not escape.
+    # @performance Seven strings are copied with a fixed 128-byte maximum each.
+    class CorrelationContext
+      FIELDS = %w(release revision deploy_id environment service region instance).freeze
+
+      def initialize(config)
+        @config = config
+      end
+
+      def call(overrides = {})
+        values = defaults.merge(string_hash(overrides))
+        result = FIELDS.each_with_object({}) do |name, correlation|
+          correlation[name.freeze] = bounded(values[name], 128)
+        end
+        result.each_value { |value| value.freeze if value }
+        result.freeze
+      rescue StandardError
+        FIELDS.each_with_object({}) { |name, fallback| fallback[name] = nil }.freeze
+      end
+
+      private
+
+      def defaults
+        {
+          "release" => @config.app_version, "revision" => @config.revision,
+          "deploy_id" => @config.deploy_id, "environment" => @config.environment,
+          "service" => @config.service_name, "region" => @config.region,
+          "instance" => @config.instance_id
+        }
+      end
+
+      def string_hash(value)
+        return {} unless value.is_a?(Hash)
+
+        value.each_with_object({}) do |(key, child), result|
+          result[key.to_s] = child if key.is_a?(String) || key.is_a?(Symbol)
+        end
+      end
+
+      def bounded(value, limit)
+        return nil if value.nil?
+        return nil unless value.is_a?(String) || value.is_a?(Symbol) || value.is_a?(Numeric)
+
+        text = value.to_s
+        text = text.scrub("?") if text.respond_to?(:scrub)
+        text = text.byteslice(0, limit) if text.bytesize > limit
+        text
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/chronos/core/deploy_normalizer.rb

@@ -0,0 +1,102 @@
+require "securerandom"
+require "uri"
+
+module Chronos
+  module Core
+    # Normalizes explicit deployment metadata into the versioned deploy payload.
+    #
+    # @responsibility Validate required deploy identity and bound every public API field.
+    # @motivation Deployment commands need predictable safe input independent of frameworks.
+    # @limits It does not inspect Git, environment variables, credentials, or deployment systems.
+    # @collaborators Chronos.notify_deploy, CorrelationContext, and Configuration::Snapshot.
+    # @thread_safety Stateless apart from immutable configuration and an injected ID generator.
+    # @compatibility Ruby 2.2.10 through Ruby 2.6.
+    # @example
+    #   DeployNormalizer.new(config).call(:revision => "abc", :version => "1.2.3")
+    # @errors Missing environment or both revision/version raise ArgumentError for the agent to contain.
+    # @performance Constant work over nine bounded scalar fields.
+    class DeployNormalizer
+      def initialize(config, options = {})
+        @config = config
+        @id_generator = options[:id_generator] || proc { SecureRandom.uuid }
+      end
+
+      def call(attributes = {})
+        values = string_hash(attributes)
+        payload = {
+          "deploy_id" => deploy_id(values["deploy_id"] || @config.deploy_id),
+          "environment" => bounded(values["environment"] || @config.environment, 128),
+          "revision" => bounded(values["revision"] || @config.revision, 128),
+          "version" => bounded(values["version"] || @config.app_version, 128),
+          "repository" => repository(values["repository"]),
+          "actor" => bounded(values["actor"], 128),
+          "service" => bounded(values["service"] || @config.service_name, 128),
+          "region" => bounded(values["region"] || @config.region, 128),
+          "instance" => bounded(values["instance"] || @config.instance_id, 128)
+        }
+        validate!(payload)
+        payload
+      end
+
+      private
+
+      def validate!(payload)
+        raise ArgumentError, "deploy environment is required" if payload["environment"].to_s.empty?
+        return unless payload["revision"].to_s.empty? && payload["version"].to_s.empty?
+
+        raise ArgumentError, "deploy revision or version is required"
+      end
+
+      def generated_id
+        value = bounded(@id_generator.call, 128)
+        raise ArgumentError, "deploy ID is required" if value.to_s.empty?
+
+        value
+      end
+
+      def deploy_id(value)
+        normalized = bounded(value, 128)
+        normalized.to_s.empty? ? generated_id : normalized
+      end
+
+      def repository(value)
+        text = bounded(value, 512)
+        return nil if text.nil?
+
+        scp = text.match(/\A[^@]+@([^:]+):(.+)\z/)
+        return bounded("#{scp[1]}/#{scp[2]}", 512) if scp
+
+        uri = URI.parse(text)
+        return bounded("#{uri.host}#{uri.path}", 512) if uri.host
+        return bounded(uri.path, 512) unless uri.path.to_s.empty?
+
+        nil
+      rescue StandardError
+        nil
+      end
+
+      def string_hash(value)
+        raise ArgumentError, "deploy attributes must be a Hash" unless value.is_a?(Hash)
+
+        value.each_with_object({}) do |(key, child), result|
+          result[key.to_s] = child if key.is_a?(String) || key.is_a?(Symbol)
+        end
+      end
+
+      def bounded(value, limit)
+        return nil if value.nil?
+        return nil unless scalar?(value)
+
+        text = value.to_s
+        text = text.scrub("?") if text.respond_to?(:scrub)
+        text.bytesize > limit ? text.byteslice(0, limit) : text
+      rescue StandardError
+        nil
+      end
+
+      def scalar?(value)
+        value.is_a?(String) || value.is_a?(Symbol) || value.is_a?(Numeric)
+      end
+    end
+  end
+end

data/lib/chronos/core/payload_serializer.rb

@@ -44,6 +44,7 @@ module Chronos
         @sanitizer = options[:sanitizer] || Sanitizer.new(config)
         @safe_serializer = options[:safe_serializer] || SafeSerializer.new
         @max_payload_size = options[:max_payload_size] || proc { @config.max_payload_size }
+        @correlation = options[:correlation] || CorrelationContext.new(config)
       end
 
       def call(notice)
@@ -70,8 +71,10 @@ module Chronos
           "service" => {
             "name" => @config.service_name,
             "version" => @config.app_version,
-            "instance_id" => notice.host
+            "instance_id" => @config.instance_id || notice.host
           },
+          "correlation" => @correlation.call("environment" => notice.environment,
+                                             "instance" => @config.instance_id || notice.host),
           "runtime" => notice.runtime,
           "context" => notice.context,
           "payload" => payload(notice)

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 deploy metric_batch).freeze
 
       attr_reader :event_id, :event_type, :timestamp, :context, :payload
 
@@ -68,6 +68,7 @@ module Chronos
         @safe_serializer = options[:safe_serializer] || SafeSerializer.new
         @max_payload_size = options[:max_payload_size] || proc { @config.max_payload_size }
         @runtime_info = RuntimeInfo.new
+        @correlation = options[:correlation] || CorrelationContext.new(config)
       end
 
       def call(event)
@@ -89,13 +90,39 @@ module Chronos
           "schema_version" => "1.0", "event_id" => event.event_id,
           "event_type" => event.event_type, "occurred_at" => event.timestamp,
           "sent_at" => @clock.call.utc.iso8601(6), "project_key" => @config.project_id,
-          "environment" => @config.environment,
-          "service" => {"name" => @config.service_name, "version" => @config.app_version,
-                        "instance_id" => runtime[:host]},
+          "environment" => event_environment(event),
+          "service" => event_service(event, runtime),
+          "correlation" => event_correlation(event, runtime),
           "runtime" => runtime[:runtime], "context" => event.context, "payload" => event.payload
         }
       end
 
+      def event_environment(event)
+        event.event_type == "deploy" ? event.payload["environment"] : @config.environment
+      end
+
+      def event_service(event, runtime)
+        deploy = event.event_type == "deploy" ? event.payload : {}
+        {
+          "name" => deploy["service"] || @config.service_name,
+          "version" => deploy["version"] || @config.app_version,
+          "instance_id" => deploy["instance"] || @config.instance_id || runtime[:host]
+        }
+      end
+
+      def event_correlation(event, runtime)
+        overrides = {"instance" => @config.instance_id || runtime[:host]}
+        if event.event_type == "deploy"
+          overrides.merge!(
+            "release" => event.payload["version"], "revision" => event.payload["revision"],
+            "deploy_id" => event.payload["deploy_id"], "environment" => event.payload["environment"],
+            "service" => event.payload["service"], "region" => event.payload["region"],
+            "instance" => event.payload["instance"]
+          )
+        end
+        @correlation.call(overrides)
+      end
+
       def compact_envelope(envelope)
         envelope["context"] = {"_truncated" => true}
         envelope["payload"] = {"_truncated" => true}

data/lib/chronos/integrations/capistrano.rb

@@ -0,0 +1,61 @@
+module Chronos
+  module Integrations
+    # Optional Capistrano task installer using only the public task DSL.
+    #
+    # @responsibility Register one post-publish task that delegates explicit values to notify_deploy.
+    # @motivation Legacy deployments need release reporting without a Capistrano runtime dependency.
+    # @limits Values are read only from configured Capistrano variables; Git and ENV are not inspected.
+    # @collaborators Capistrano/Rake DSL and the Chronos public facade.
+    # @thread_safety Installation is idempotent per DSL object before task execution.
+    # @compatibility Capistrano task DSLs available to supported Ruby 2.2.10 through Ruby 2.6 apps.
+    # @example
+    #   require "chronos/capistrano"
+    # @errors Missing DSL methods return false; notification failures are contained by Chronos.
+    # @performance Adds one task and one after hook; no background worker is created.
+    module Capistrano
+      INSTALLED_KEY = :@__chronos_capistrano_installed
+
+      class << self
+        def install(dsl)
+          return false if dsl.instance_variable_get(INSTALLED_KEY)
+          return false unless compatible?(dsl)
+
+          dsl.send(:namespace, :chronos) do
+            dsl.send(:desc, "Notify Chronos about the published deployment") if dsl.respond_to?(:desc, true)
+            dsl.send(:task, :notify_deploy) { notify(dsl) }
+          end
+          dsl.send(:after, "deploy:published", "chronos:notify_deploy")
+          dsl.instance_variable_set(INSTALLED_KEY, true)
+          true
+        rescue StandardError
+          false
+        end
+
+        def notify(dsl)
+          Chronos.notify_deploy(
+            :environment => value(dsl, :stage).to_s,
+            :revision => value(dsl, :current_revision) || value(dsl, :branch),
+            :version => value(dsl, :chronos_version) || value(dsl, :release_name),
+            :repository => value(dsl, :repo_url), :actor => value(dsl, :chronos_actor),
+            :deploy_id => value(dsl, :chronos_deploy_id), :service => value(dsl, :chronos_service),
+            :region => value(dsl, :chronos_region), :instance => value(dsl, :chronos_instance)
+          )
+        rescue StandardError
+          false
+        end
+
+        private
+
+        def compatible?(dsl)
+          [:namespace, :task, :after, :fetch].all? { |name| dsl.respond_to?(name, true) }
+        end
+
+        def value(dsl, name)
+          dsl.send(:fetch, name, nil)
+        rescue StandardError
+          nil
+        end
+      end
+    end
+  end
+end