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

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 metric_batch).freeze
 
       attr_reader :event_id, :event_type, :timestamp, :context, :payload
 

data/lib/chronos/integrations/job_payload.rb

@@ -0,0 +1,72 @@
+module Chronos
+  module Integrations
+    # Builds bounded job metadata before the shared privacy serializer runs.
+    #
+    # @responsibility Limit job arguments, tags, strings, containers, and nesting.
+    # @motivation Worker payloads are application-controlled and may be very large.
+    # @limits It limits values but deliberately leaves redaction to Core::Sanitizer.
+    # @collaborators Sidekiq middleware and the Chronos telemetry pipeline.
+    # @thread_safety Instances keep no mutable state and may be shared.
+    # @compatibility Ruby 2.2.10 through Ruby 2.6.
+    # @example
+    #   JobPayload.new.arguments(["account-1"])
+    # @errors Unreadable values become bounded class-name placeholders.
+    # @performance Traversal is capped by argument, collection, depth, and string limits.
+    class JobPayload
+      MAX_ARGUMENTS = 20
+      MAX_COLLECTION_ITEMS = 20
+      MAX_DEPTH = 4
+      MAX_STRING_BYTES = 512
+
+      def arguments(values)
+        source = values.is_a?(Array) ? values : []
+        [source.first(MAX_ARGUMENTS).map { |value| limit(value, 0) }, source.length > MAX_ARGUMENTS]
+      rescue StandardError
+        [[], true]
+      end
+
+      def tags(values)
+        Array(values).first(MAX_COLLECTION_ITEMS).map { |value| limit_string(value.to_s) }
+      rescue StandardError
+        []
+      end
+
+      private
+
+      def limit(value, depth)
+        return "[TRUNCATED]" if depth >= MAX_DEPTH
+
+        case value
+        when Hash
+          limit_hash(value, depth)
+        when Array
+          value.first(MAX_COLLECTION_ITEMS).map { |child| limit(child, depth + 1) }
+        when String
+          limit_string(value)
+        when NilClass, TrueClass, FalseClass, Numeric
+          value
+        else
+          limit_string(value.to_s)
+        end
+      rescue StandardError
+        "[UNREADABLE]"
+      end
+
+      def limit_hash(value, depth)
+        result = {}
+        value.to_a.first(MAX_COLLECTION_ITEMS).each do |key, child|
+          result[limit_string(key.to_s)] = limit(child, depth + 1)
+        end
+        result
+      end
+
+      def limit_string(value)
+        return value if value.bytesize <= MAX_STRING_BYTES
+
+        value.byteslice(0, MAX_STRING_BYTES) + "[TRUNCATED]"
+      rescue StandardError
+        "[UNREADABLE]"
+      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

@@ -0,0 +1,260 @@
+require "securerandom"
+require "chronos/integrations/job_payload"
+
+module Chronos
+  module Integrations
+    # Optional Sidekiq 4/5 middleware integration for the legacy Chronos line.
+    #
+    # @responsibility Install client/server middleware and namespace worker telemetry.
+    # @motivation Sidekiq jobs need process-boundary context and failure capture.
+    # @limits It does not own Sidekiq lifecycle, Redis connections, retries, or threads.
+    # @collaborators Sidekiq public middleware configuration and Chronos facade.
+    # @thread_safety Installation is mutex-protected; middleware instances are stateless.
+    # @compatibility Sidekiq 4.x and 5.x; Ruby 2.2.10 through Ruby 2.6.
+    # @example
+    #   Chronos::Integrations::Sidekiq.install
+    # @errors Missing Sidekiq or configuration failures return false.
+    # @performance Adds bounded payload normalization and two clock reads per performed job.
+    module Sidekiq
+      CONTEXT_KEY = "chronos".freeze
+      CONTEXT_SCHEMA_VERSION = "1.0".freeze
+
+      @mutex = Mutex.new
+      @installed = false
+
+      class << self
+        def install(sidekiq = nil, notifier = Chronos)
+          library = sidekiq || (::Sidekiq if defined?(::Sidekiq))
+          return false unless library
+
+          @mutex.synchronize do
+            return false if @installed
+
+            configure_client(library, notifier)
+            configure_server(library, notifier)
+            @installed = true
+          end
+          true
+        rescue StandardError
+          false
+        end
+
+        private
+
+        def configure_client(library, notifier)
+          return unless library.respond_to?(:configure_client)
+
+          library.configure_client do |config|
+            next unless config.respond_to?(:client_middleware)
+
+            config.client_middleware { |chain| chain.add(ClientMiddleware, :notifier => notifier) }
+          end
+        end
+
+        def configure_server(library, notifier)
+          return unless library.respond_to?(:configure_server)
+
+          library.configure_server do |config|
+            if config.respond_to?(:client_middleware)
+              config.client_middleware { |chain| chain.add(ClientMiddleware, :notifier => notifier) }
+            end
+            if config.respond_to?(:server_middleware)
+              config.server_middleware { |chain| chain.add(ServerMiddleware, :notifier => notifier) }
+            end
+          end
+        end
+      end
+
+      # Adds a small allowlisted Chronos context to the Sidekiq job envelope.
+      #
+      # @responsibility Propagate trace/request identifiers without modifying `args`.
+      # @motivation Client and server usually execute in different processes.
+      # @limits It does not capture arguments, enqueue errors, or application context fields.
+      # @collaborators Chronos propagation context and Sidekiq client middleware chain.
+      # @thread_safety Calls allocate their own hashes and may execute concurrently.
+      # @compatibility Sidekiq 4.x/5.x client middleware signature.
+      # @example
+      #   ClientMiddleware.new.call(MyWorker, job, "default") { push(job) }
+      # @errors Context failures are contained and the enqueue chain still runs.
+      # @performance Adds one bounded hash to the job payload; opens no connection or thread.
+      class ClientMiddleware
+        def initialize(options = {})
+          @notifier = options[:notifier] || Chronos
+          @clock = options[:clock] || proc { Time.now.to_f }
+        end
+
+        def call(_worker_class, job, _queue, _redis_pool = nil)
+          add_context(job)
+          yield
+        end
+
+        private
+
+        def add_context(job)
+          return unless job.is_a?(Hash)
+
+          context = propagation_context
+          context["trace_id"] = SecureRandom.uuid if context["trace_id"].to_s.empty?
+          job[CONTEXT_KEY] = {
+            "schema_version" => CONTEXT_SCHEMA_VERSION,
+            "enqueued_at" => @clock.call.to_f,
+            "context" => context
+          }
+        rescue StandardError
+          nil
+        end
+
+        def propagation_context
+          return {} unless @notifier.respond_to?(:propagation_context)
+
+          source = @notifier.propagation_context
+          return {} unless source.is_a?(Hash)
+
+          %w(trace_id request_id).each_with_object({}) do |key, result|
+            value = source[key] || source[key.to_sym]
+            result[key] = value.to_s unless value.to_s.empty?
+          end
+        end
+      end
+
+      # Captures Sidekiq execution timing and failures around the worker call.
+      #
+      # @responsibility Scope propagated context, emit one job event, notify failures once, and re-raise.
+      # @motivation Worker failures otherwise lose queue metadata and request correlation.
+      # @limits It does not change retry behavior, acknowledge jobs, or install global error handlers.
+      # @collaborators Chronos facade, JobPayload, and Sidekiq server middleware chain.
+      # @thread_safety Shared instances keep only immutable collaborators.
+      # @compatibility Sidekiq 4.x/5.x server middleware signature.
+      # @example
+      #   ServerMiddleware.new.call(worker, job, "default") { worker.perform }
+      # @errors The original worker exception is always re-raised after contained notification.
+      # @performance No per-job thread or connection; normalization has strict collection limits.
+      class ServerMiddleware
+        def initialize(options = {})
+          @notifier = options[:notifier] || Chronos
+          @clock = options[:clock] || proc { monotonic_time }
+          @wall_clock = options[:wall_clock] || proc { Time.now.to_f }
+          @limiter = options[:limiter] || JobPayload.new
+        end
+
+        def call(worker, job, queue)
+          started_at = @clock.call
+          payload = base_payload(worker, job, queue)
+          context = execution_context(job, payload)
+          @notifier.with_context(context) do
+            begin
+              result = yield
+              finish(payload, started_at, "completed")
+              result
+            rescue Exception => error # rubocop:disable Lint/RescueException
+              finish(payload, started_at, "failed", error)
+              notify_failure(error, payload)
+              raise
+            end
+          end
+        end
+
+        private
+
+        def base_payload(worker, job, queue)
+          source = job.is_a?(Hash) ? job : {}
+          arguments, truncated = @limiter.arguments(source["args"] || source[:args])
+          payload = {
+            "kind" => "sidekiq", "class" => worker_class(worker, source),
+            "queue" => (source["queue"] || source[:queue] || queue).to_s,
+            "jid" => (source["jid"] || source[:jid]).to_s,
+            "retry_count" => retry_count(source), "arguments" => arguments,
+            "arguments_truncated" => truncated, "tags" => tags(worker, source),
+            "queue_latency_ms" => queue_latency(source)
+          }
+          payload
+        end
+
+        def execution_context(job, payload)
+          metadata = job.is_a?(Hash) ? (job[CONTEXT_KEY] || job[CONTEXT_KEY.to_sym]) : nil
+          propagated = metadata.is_a?(Hash) ? (metadata["context"] || metadata[:context]) : nil
+          propagated = {} unless propagated.is_a?(Hash)
+          {
+            :context => propagated.merge("job" => job_context(payload)),
+            :parameters => {"arguments" => payload["arguments"]},
+            :tags => payload["tags"],
+            :__chronos_captured_exceptions => {}
+          }
+        end
+
+        def finish(payload, started_at, status, error = nil)
+          payload["duration_ms"] = [elapsed_ms(started_at), 0.0].max
+          payload["status"] = status
+          payload["error_class"] = error.class.name.to_s if error
+          @notifier.record_event("job", payload)
+        rescue StandardError
+          false
+        end
+
+        def notify_failure(error, payload)
+          context = {:context => {"job" => job_context(payload)},
+                     :parameters => {"arguments" => payload["arguments"]}, :tags => payload["tags"]}
+          if @notifier.respond_to?(:notify_once)
+            @notifier.notify_once(error, context)
+          else
+            @notifier.notify(error, context)
+          end
+        rescue StandardError
+          false
+        end
+
+        def job_context(payload)
+          %w(kind class queue jid retry_count queue_latency_ms duration_ms status).each_with_object({}) do |key, result|
+            result[key] = payload[key] unless payload[key].nil?
+          end
+        end
+
+        def worker_class(worker, job)
+          explicit = job["wrapped"] || job[:wrapped] || job["class"] || job[:class]
+          explicit = worker.class.name if explicit.to_s.empty? && worker
+          explicit.to_s
+        rescue StandardError
+          ""
+        end
+
+        def retry_count(job)
+          value = job["retry_count"] || job[:retry_count]
+          value.to_i < 0 ? 0 : value.to_i
+        end
+
+        def tags(worker, job)
+          values = job["tags"] || job[:tags]
+          if values.nil? && worker
+            owner = worker.is_a?(Class) ? worker : worker.class
+            options = owner.get_sidekiq_options if owner.respond_to?(:get_sidekiq_options)
+            values = options["tags"] || options[:tags] if options.is_a?(Hash)
+          end
+          @limiter.tags(values)
+        rescue StandardError
+          []
+        end
+
+        def queue_latency(job)
+          metadata = job[CONTEXT_KEY] || job[CONTEXT_KEY.to_sym]
+          enqueued_at = job["enqueued_at"] || job[:enqueued_at]
+          enqueued_at ||= metadata["enqueued_at"] || metadata[:enqueued_at] if metadata.is_a?(Hash)
+          return nil unless enqueued_at
+
+          [((@wall_clock.call.to_f - enqueued_at.to_f) * 1000.0).round(3), 0.0].max
+        rescue StandardError
+          nil
+        end
+
+        def elapsed_ms(started_at)
+          ((@clock.call - started_at) * 1000.0).round(3)
+        end
+
+        def monotonic_time
+          Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        rescue StandardError
+          Time.now.to_f
+        end
+      end
+    end
+  end
+end

data/lib/chronos/internal/worker_pool.rb

@@ -24,6 +24,7 @@ module Chronos
         @mutex = Mutex.new
         @threads = []
         @active = 0
+        @pending = 0
         @closed = false
         @pid = Process.pid
       end
@@ -32,7 +33,9 @@ module Chronos
         prepare_after_fork
         return false if closed?
 
+        increment_pending
         accepted = @queue.push(event)
+        decrement_pending unless accepted
         ensure_started if accepted
         accepted
       end
@@ -42,7 +45,7 @@ module Chronos
         ensure_started unless @queue.empty?
         deadline = monotonic_time + timeout.to_f
         loop do
-          return true if @queue.empty? && active_count.zero?
+          return true if delivery_complete?
           return false if monotonic_time >= deadline
           sleep(POLL_INTERVAL)
         end
@@ -91,6 +94,7 @@ module Chronos
             @logger.warn("Chronos worker contained #{error.class}")
           ensure
             decrement_active
+            decrement_pending
           end
         end
       rescue StandardError => error
@@ -104,13 +108,14 @@ module Chronos
           @pid = Process.pid
           @threads = []
           @active = 0
+          @pending = @queue.size
         end
       end
 
       def flush_without_reopening(timeout)
         deadline = monotonic_time + timeout.to_f
         loop do
-          return true if @queue.empty? && active_count.zero?
+          return true if delivery_complete?
           return false if monotonic_time >= deadline
           sleep(POLL_INTERVAL)
         end
@@ -138,6 +143,18 @@ module Chronos
         @mutex.synchronize { @active }
       end
 
+      def increment_pending
+        @mutex.synchronize { @pending += 1 }
+      end
+
+      def decrement_pending
+        @mutex.synchronize { @pending -= 1 }
+      end
+
+      def delivery_complete?
+        @mutex.synchronize { @pending.zero? && @active.zero? }
+      end
+
       def closed?
         @mutex.synchronize { @closed }
       end