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

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"].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
@@ -63,6 +65,11 @@ module Chronos
         snapshot["enabled_event_types"].include?(event_type.to_s)
       end
 
+      def delivery_enabled?(event_type)
+        values = snapshot
+        !values["kill_switch"] && values["enabled_event_types"].include?(event_type.to_s)
+      end
+
       def ignored_fingerprint?(fingerprint)
         snapshot["ignored_fingerprints"].include?(fingerprint.to_s)
       end

data/lib/chronos/configuration/apm_validation.rb

@@ -0,0 +1,76 @@
+module Chronos
+  module Internal
+    # Validates bounded APM aggregation, histogram, and detector settings.
+    #
+    # @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.
+    # @thread_safety Reads one mutable configuration instance without shared state.
+    # @compatibility Ruby 2.2.10 through Ruby 2.6.
+    # @errors Invalid values become messages and never raise from validation.
+    module ApmConfigurationValidation
+      private
+
+      def apm_errors
+        errors = apm_capacity_errors
+        errors.concat(apm_threshold_errors)
+        errors << "apm_enabled must be true or false" unless [true, false].include?(apm_enabled)
+        unless increasing_positive_numbers?(apm_histogram_buckets)
+          errors << "apm_histogram_buckets must contain increasing positive numbers"
+        end
+        errors
+      end
+
+      def apm_capacity_errors
+        errors = []
+        errors << "apm_max_groups must be a positive integer" unless positive_integer?(apm_max_groups)
+        errors << "apm_flush_count must be a positive integer" unless positive_integer?(apm_flush_count)
+        unless apm_batch_size.is_a?(Integer) && apm_batch_size >= 1 && apm_batch_size <= 50
+          errors << "apm_batch_size must be between 1 and 50"
+        end
+        unless positive_integer?(apm_max_queries_per_request)
+          errors << "apm_max_queries_per_request must be a positive integer"
+        end
+        errors
+      end
+
+      def apm_threshold_errors
+        errors = []
+        unless positive_number?(apm_slow_query_threshold_ms)
+          errors << "apm_slow_query_threshold_ms must be greater than zero"
+        end
+        unless positive_number?(apm_long_transaction_threshold_ms)
+          errors << "apm_long_transaction_threshold_ms must be greater than zero"
+        end
+        unless apm_n_plus_one_threshold.is_a?(Integer) && apm_n_plus_one_threshold >= 2
+          errors << "apm_n_plus_one_threshold must be an integer greater than or equal to 2"
+        end
+        errors
+      end
+
+      def increasing_positive_numbers?(values)
+        return false unless values.is_a?(Array) && !values.empty? && values.length <= 19
+        return false unless values.all? { |value| positive_number?(value) }
+
+        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

@@ -1,5 +1,6 @@
 require "uri"
 require "chronos/configuration/validation"
+require "chronos/configuration/apm_validation"
 
 module Chronos
   # Mutable configuration used only while the Chronos agent is being set up.
@@ -21,6 +22,7 @@ module Chronos
   #   snapshot = config.snapshot
   class Configuration
     include Internal::ConfigurationValidation
+    include Internal::ApmConfigurationValidation
     DEFAULT_BLOCKLIST_KEYS = %w(
       password password_confirmation passwd secret api_key apikey authorization
       token access_token refresh_token private_key client_secret cookie set-cookie
@@ -40,7 +42,12 @@ module Chronos
       :remote_configuration, :remote_config_max_bytes, :sampling_rate,
       :enabled_event_types, :max_remote_send_interval, :context_store,
       :breadcrumb_capacity, :breadcrumb_max_bytes, :rails_enabled,
-      :rails_capture_in_console, :rails_capture_in_test, :rails_capture_user_agent
+      :rails_capture_in_console, :rails_capture_in_test, :rails_capture_user_agent,
+      :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, :external_http_enabled, :external_http_trace_headers,
+      :cache_key_mode, :dependency_reporting, :dependency_max_items
     ].freeze
 
     attr_accessor(*ATTRIBUTES)
@@ -50,6 +57,8 @@ module Chronos
       initialize_privacy_defaults
       initialize_resilience_defaults
       initialize_rails_defaults
+      initialize_apm_defaults
+      initialize_observability_defaults
     end
 
     def snapshot
@@ -78,6 +87,8 @@ module Chronos
       errors.concat(resilience_errors)
       errors.concat(privacy_errors)
       errors.concat(context_errors)
+      errors.concat(apm_errors)
+      errors.concat(observability_errors)
       errors
     end
 
@@ -116,6 +127,26 @@ module Chronos
       @rails_capture_user_agent = false
     end
 
+    def initialize_apm_defaults
+      @apm_enabled = true
+      @apm_max_groups = 200
+      @apm_flush_count = 100
+      @apm_batch_size = 50
+      @apm_max_queries_per_request = 100
+      @apm_slow_query_threshold_ms = 500.0
+      @apm_long_transaction_threshold_ms = 1000.0
+      @apm_n_plus_one_threshold = 5
+      @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 = []
@@ -135,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"]
+      @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/metric_aggregate.rb

@@ -0,0 +1,113 @@
+module Chronos
+  module Core
+    # Accumulates one bounded APM metric group and serializes aggregate statistics.
+    #
+    # @responsibility Track counts, errors, durations, histogram, breakdown, and signals.
+    # @motivation Keep numerical accumulation separate from grouping and request correlation.
+    # @limits It does not choose dimensions, retain observations, or calculate percentiles.
+    # @collaborators ApmAggregator and immutable histogram boundaries.
+    # @thread_safety Mutable by design; callers must synchronize access.
+    # @compatibility Ruby 2.2.10 through Ruby 2.6.
+    # @example
+    #   metric.observe(12.0, false, {"database" => 3.0}, {})
+    # @errors Non-numeric durations become zero and never escape.
+    # @performance Memory is fixed by the configured histogram boundary count.
+    class MetricAggregate
+      BREAKDOWN_CATEGORIES = %w(database view external_http cache queue application unknown).freeze
+
+      def initialize(metric_type, dimensions, boundaries)
+        @metric_type = metric_type
+        @dimensions = dimensions
+        @boundaries = boundaries
+        @count = 0
+        @error_count = 0
+        @total = 0.0
+        @min = nil
+        @max = nil
+        @buckets = Array.new(boundaries.length + 1, 0)
+        @breakdown = {}
+        @signals = {}
+        @status_codes = {}
+      end
+
+      def observe(duration, error, breakdown, signals, status = nil)
+        value = non_negative(duration)
+        @count += 1
+        @error_count += 1 if error
+        @total += value
+        @min = value if @min.nil? || value < @min
+        @max = value if @max.nil? || value > @max
+        bucket = @boundaries.index { |boundary| value <= boundary }
+        @buckets[bucket || @boundaries.length] += 1
+        add_breakdown(breakdown)
+        add_signals(signals)
+        add_status(status)
+        self
+      end
+
+      def to_h
+        {
+          "metric_type" => @metric_type, "dimensions" => @dimensions,
+          "count" => @count, "error_count" => @error_count,
+          "error_rate" => (@error_count.to_f / @count).round(6),
+          "duration_ms" => duration_summary, "histogram" => histogram,
+          "breakdown_ms" => rounded_hash(@breakdown), "signals" => @signals,
+          "status_codes" => @status_codes
+        }
+      end
+
+      private
+
+      def add_breakdown(values)
+        hash(values).each do |category, duration|
+          name = BREAKDOWN_CATEGORIES.include?(category.to_s) ? category.to_s : "unknown"
+          @breakdown[name] ||= 0.0
+          @breakdown[name] += non_negative(duration)
+        end
+      end
+
+      def add_signals(values)
+        hash(values).each do |name, count|
+          @signals[name.to_s] ||= 0
+          @signals[name.to_s] += count.to_i
+        end
+      end
+
+      def add_status(status)
+        return if status.nil?
+
+        key = status.to_i.to_s
+        @status_codes[key] ||= 0
+        @status_codes[key] += 1
+      end
+
+      def duration_summary
+        {
+          "total" => @total.round(3), "min" => @min.round(3), "max" => @max.round(3),
+          "average" => (@total / @count).round(3)
+        }
+      end
+
+      def histogram
+        @buckets.each_with_index.map do |count, index|
+          {"le" => @boundaries[index] || "+Inf", "count" => count}
+        end
+      end
+
+      def rounded_hash(values)
+        values.each_with_object({}) { |(key, value), result| result[key] = value.round(3) }
+      end
+
+      def non_negative(value)
+        number = value.to_f
+        number < 0.0 ? 0.0 : number
+      rescue StandardError
+        0.0
+      end
+
+      def hash(value)
+        value.is_a?(Hash) ? value : {}
+      end
+    end
+  end
+end

data/lib/chronos/core/sql_normalizer.rb

@@ -0,0 +1,114 @@
+require "digest"
+
+module Chronos
+  module Core
+    # Produces bounded, value-free SQL metadata for aggregation and local signals.
+    #
+    # @responsibility Remove comments/literals and derive operation, table, and fingerprint.
+    # @motivation SQL metrics need stable low-cardinality identity without bind values.
+    # @limits It is a defensive lexer, not a complete dialect-specific SQL parser.
+    # @collaborators Rails notification adapter and APM aggregator.
+    # @thread_safety Instances are stateless and safe to share.
+    # @compatibility Ruby 2.2.10 through Ruby 2.6; no ActiveRecord dependency.
+    # @example
+    #   SqlNormalizer.new.call("SELECT * FROM users WHERE id = 42")
+    # @errors Malformed or unreadable input returns bounded unknown metadata.
+    # @performance Input and normalized output are capped before fingerprinting.
+    class SqlNormalizer
+      MAX_SQL_BYTES = 4096
+      MAX_NORMALIZED_BYTES = 512
+      KEYWORDS = %w(
+        select insert update delete from into where join left right inner outer on set values
+        and or order group by having limit offset as distinct begin commit rollback savepoint release
+      ).freeze
+
+      def call(sql, metadata = {})
+        normalized = normalize(sql)
+        {
+          "adapter" => adapter(metadata), "operation" => operation(normalized),
+          "table" => table(normalized), "normalized_query" => normalized,
+          "fingerprint" => Digest::SHA256.hexdigest(normalized),
+          "name" => value(metadata, :name).to_s,
+          "cached" => value(metadata, :cached) == true,
+          "role" => optional_string(metadata, :role, :connection_role),
+          "shard" => optional_string(metadata, :shard, :connection_shard),
+          "source" => bounded(value(metadata, :source).to_s, 256),
+          "error_class" => error_class(metadata)
+        }.delete_if { |_key, child| child.nil? || child == "" }
+      rescue StandardError
+        {"operation" => "UNKNOWN", "normalized_query" => "", "fingerprint" => Digest::SHA256.hexdigest("")}
+      end
+
+      private
+
+      def normalize(sql)
+        text = bounded(sql.to_s, MAX_SQL_BYTES)
+        text = text.gsub(%r{/\*.*?\*/}m, " ").gsub(/--[^\r\n]*/, " ")
+        text = text.gsub(/'(?:''|[^'])*'/, "?")
+        text = text.gsub(/\$([A-Za-z_][A-Za-z0-9_]*)?\$.*?\$\1\$/m, "?")
+        text = text.gsub(/\b(?:0x[0-9a-f]+|\d+(?:\.\d+)?)\b/i, "?")
+        text = text.gsub(/\b(?:true|false|null)\b/i, "?")
+        text = text.gsub(/\(\s*\?(?:\s*,\s*\?)+\s*\)/, "(?)")
+        text = text.gsub(/\s+/, " ").strip
+        KEYWORDS.each { |keyword| text.gsub!(/\b#{keyword}\b/i, keyword.upcase) }
+        bounded(text, MAX_NORMALIZED_BYTES)
+      end
+
+      def operation(normalized)
+        candidate = normalized.to_s.split(/\s+/, 2).first.to_s.upcase
+        candidate =~ /\A[A-Z]+\z/ ? candidate : "UNKNOWN"
+      end
+
+      def table(normalized)
+        match = normalized.match(/\b(?:FROM|INTO|UPDATE|JOIN)\s+["`\[]?([A-Za-z0-9_.-]+)/i)
+        bounded(match && match[1].to_s, 128)
+      end
+
+      def adapter(metadata)
+        direct = value(metadata, :adapter)
+        return bounded(direct.to_s, 64) unless direct.to_s.empty?
+
+        connection = value(metadata, :connection)
+        return "" unless connection && connection.respond_to?(:adapter_name)
+
+        bounded(connection.adapter_name.to_s, 64)
+      rescue StandardError
+        ""
+      end
+
+      def error_class(metadata)
+        error = value(metadata, :exception_object) || value(metadata, :exception)
+        return error.class.name.to_s if error.is_a?(Exception)
+        return Array(error).first.to_s unless error.nil?
+
+        ""
+      rescue StandardError
+        ""
+      end
+
+      def optional_string(metadata, *names)
+        names.each do |name|
+          candidate = value(metadata, name)
+          return bounded(candidate.to_s, 64) unless candidate.to_s.empty?
+        end
+        ""
+      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)
+        return text if text.bytesize <= limit
+
+        text.byteslice(0, limit)
+      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).freeze
+      TYPES = %w(request query job cache external_http dependencies metric_batch).freeze
 
       attr_reader :event_id, :event_type, :timestamp, :context, :payload