chronos-ruby 1.0.0 → 1.2.0.pre.1

data/lib/chronos/rails/active_record_query_inspector.rb

@@ -0,0 +1,235 @@
+require "json"
+
+module Chronos
+  module Rails
+    # Performs bounded, read-only ActiveRecord index, statistics, and query-plan inspection.
+    #
+    # @responsibility Read public schema metadata and optional non-executing SELECT plans.
+    # @motivation Add database evidence to query diagnostics without exposing raw SQL or bind values.
+    # @limits It never runs EXPLAIN ANALYZE or DDL; support is best-effort and explicitly opt-in.
+    # @collaborators An ActiveRecord connection supplied by sql.active_record notifications.
+    # @thread_safety Calls use the notification connection and a thread-local recursion guard.
+    # @compatibility Feature-detected Rails 4.2/5.2 connections for PostgreSQL and MySQL-family adapters.
+    # @example
+    #   inspector.call(sql, query_metadata, :plan => false)
+    # @errors Adapter failures become bounded error-class evidence and never escape.
+    # @performance Each uncached inspection adds schema/statistics queries and optionally EXPLAIN.
+    class ActiveRecordQueryInspector
+      GUARD_KEY = :__chronos_query_inspection
+      MAX_PLAN_NODES = 20
+
+      def self.suppressed?
+        Thread.current[GUARD_KEY] == true
+      rescue StandardError
+        false
+      end
+
+      def call(raw_sql, query, options = {})
+        connection = options[:connection]
+        return {} unless eligible?(raw_sql, query, connection)
+
+        previous = Thread.current[GUARD_KEY]
+        Thread.current[GUARD_KEY] = true
+        guarded = true
+        result = {"errors" => []}
+        capture(result) { result["indexes"] = indexes(connection, table(query)) }
+        if options[:statistics] == true
+          capture(result) { result["statistics"] = statistics(connection, table(query)) }
+        end
+        if options[:plan] == true
+          capture(result) do
+            plan_result = plan(connection, raw_sql, adapter_name(connection))
+            result["errors"].concat(Array(plan_result.delete("errors")))
+            result["plan"] = plan_result
+          end
+        end
+        result.delete("errors") if result["errors"].empty?
+        result
+      rescue StandardError => error
+        {"errors" => [safe_error_class(error)]}
+      ensure
+        Thread.current[GUARD_KEY] = previous if guarded
+      end
+
+      private
+
+      def capture(result)
+        yield
+      rescue StandardError => error
+        result["errors"] << safe_error_class(error) if result["errors"].length < 5
+      end
+
+      def eligible?(raw_sql, query, connection)
+        return false unless connection
+        return false unless (query["operation"] || query[:operation]).to_s == "SELECT"
+        return false if table(query).empty?
+        return false unless raw_sql.to_s.lstrip =~ /\ASELECT\b/i
+
+        normalized = (query["normalized_query"] || query[:normalized_query]).to_s
+        normalized.sub(/;\s*\z/, "") !~ /;/
+      end
+
+      def indexes(connection, table_name)
+        return [] unless connection.respond_to?(:indexes)
+
+        Array(connection.indexes(table_name)).first(20).map do |index|
+          {
+            "table" => bounded_identifier(table_name), "name" => bounded(value(index, :name), 128),
+            "columns" => Array(value(index, :columns)).first(12).map { |column| bounded_identifier(column) },
+            "unique" => value(index, :unique) == true
+          }
+        end
+      end
+
+      def statistics(connection, table_name)
+        adapter = adapter_name(connection)
+        if adapter =~ /postgres/i
+          row = first_row(connection, "SELECT reltuples AS estimated_rows FROM pg_class WHERE oid = " \
+                                      "#{quote(connection, table_name)}::regclass")
+          return {"estimated_rows" => numeric(row, "estimated_rows"), "source" => "pg_class"}
+        end
+        if adapter =~ /mysql|trilogy/i
+          sql = "SELECT table_rows AS estimated_rows FROM information_schema.tables " \
+                "WHERE table_schema = DATABASE() AND table_name = #{quote(connection, table_name)}"
+          row = first_row(connection, sql)
+          return {"estimated_rows" => numeric(row, "estimated_rows"), "source" => "information_schema"}
+        end
+
+        {}
+      end
+
+      def plan(connection, raw_sql, adapter)
+        return {} unless connection.respond_to?(:select_all)
+
+        if adapter =~ /postgres/i
+          rows = rows(connection.select_all("EXPLAIN (FORMAT JSON) #{raw_sql}"))
+          return postgres_plan(rows)
+        end
+        if adapter =~ /mysql|trilogy/i
+          return mysql_plan(rows(connection.select_all("EXPLAIN #{raw_sql}")))
+        end
+
+        {}
+      end
+
+      def postgres_plan(rows_value)
+        raw = rows_value.first || {}
+        document = raw["QUERY PLAN"] || raw["query_plan"] || raw.values.first
+        parsed = document.is_a?(String) ? JSON.parse(document) : document
+        root = Array(parsed).first
+        root = root["Plan"] if root.is_a?(Hash) && root["Plan"]
+        nodes = []
+        collect_postgres_nodes(root, nodes)
+        summarize_plan(nodes)
+      rescue StandardError => error
+        {"nodes" => [], "uses_index" => false, "sequential_scan" => false,
+         "errors" => [safe_error_class(error)]}
+      end
+
+      def collect_postgres_nodes(node, result)
+        return unless node.is_a?(Hash) && result.length < MAX_PLAN_NODES
+
+        result << {
+          "type" => bounded(node["Node Type"], 64),
+          "table" => bounded_identifier(node["Relation Name"]),
+          "index" => bounded(node["Index Name"], 128),
+          "estimated_rows" => integer(node["Plan Rows"]),
+          "total_cost" => number(node["Total Cost"])
+        }.delete_if { |_key, child| child.nil? || child == "" }
+        Array(node["Plans"]).each { |child| collect_postgres_nodes(child, result) }
+      end
+
+      def mysql_plan(rows_value)
+        nodes = rows_value.first(MAX_PLAN_NODES).map do |row|
+          {
+            "type" => bounded(row["type"] || row[:type] || row["select_type"], 64),
+            "table" => bounded_identifier(row["table"] || row[:table]),
+            "index" => bounded(row["key"] || row[:key], 128),
+            "estimated_rows" => integer(row["rows"] || row[:rows])
+          }.delete_if { |_key, child| child.nil? || child == "" }
+        end
+        summarize_plan(nodes)
+      end
+
+      def summarize_plan(nodes)
+        types = nodes.map { |node| node["type"].to_s }
+        {
+          "nodes" => nodes,
+          "uses_index" => nodes.any? { |node| !node["index"].to_s.empty? || node["type"].to_s =~ /Index/i },
+          "sequential_scan" => types.any? { |type| type =~ /Seq Scan|ALL/i }
+        }
+      end
+
+      def first_row(connection, sql)
+        return {} unless connection.respond_to?(:select_all)
+
+        rows(connection.select_all(sql)).first || {}
+      end
+
+      def rows(value)
+        return value.to_a if value.respond_to?(:to_a)
+
+        Array(value)
+      rescue StandardError
+        []
+      end
+
+      def quote(connection, value)
+        return connection.quote(value.to_s) if connection.respond_to?(:quote)
+
+        "'#{value.to_s.gsub("'", "''")}'"
+      end
+
+      def adapter_name(connection)
+        connection.respond_to?(:adapter_name) ? connection.adapter_name.to_s : ""
+      rescue StandardError
+        ""
+      end
+
+      def table(query)
+        bounded_identifier(query["table"] || query[:table])
+      end
+
+      def value(object, method_name)
+        object.respond_to?(method_name) ? object.public_send(method_name) : nil
+      rescue StandardError
+        nil
+      end
+
+      def numeric(row, key)
+        value = row[key] || row[key.to_sym]
+        integer(value)
+      end
+
+      def integer(value)
+        value.nil? ? nil : [value.to_i, 0].max
+      rescue StandardError
+        nil
+      end
+
+      def number(value)
+        value.nil? ? nil : [value.to_f, 0.0].max
+      rescue StandardError
+        nil
+      end
+
+      def safe_error_class(error)
+        bounded(error.class.name.to_s, 128)
+      rescue StandardError
+        "StandardError"
+      end
+
+      def bounded_identifier(value)
+        bounded(value, 128).gsub(/[^A-Za-z0-9_.$-]/, "")
+      end
+
+      def bounded(value, limit)
+        text = value.to_s
+        text = text.scrub("?") if text.respond_to?(:scrub)
+        text.bytesize > limit ? text.byteslice(0, limit).to_s : text
+      rescue StandardError
+        ""
+      end
+    end
+  end
+end

data/lib/chronos/rails/error_reporter_subscriber.rb

@@ -0,0 +1,39 @@
+module Chronos
+  module Rails
+    # Sends exceptions observed by the Rails 7 error reporter to Chronos once.
+    # @responsibility Translate the public Rails reporter callback into one notice.
+    # @motivation Rails can report handled errors that never reach Rack middleware.
+    # @limits Only handled, severity, source, and one bounded component are retained.
+    # @collaborators ActiveSupport::ErrorReporter and Chronos facade.
+    # @thread_safety Instances contain only an immutable notifier reference.
+    # @compatibility Rails 7 public error reporter subscriber API.
+    # @example Rails.error.subscribe(ErrorReporterSubscriber.new)
+    # @errors Agent and context failures are contained and return false.
+    # @performance Allocates one small allowlisted metadata hash per report.
+    class ErrorReporterSubscriber
+      def initialize(notifier = Chronos)
+        @notifier = notifier
+      end
+
+      def report(error, handled:, severity:, context:, source: nil)
+        details = {
+          :context => {"rails_error_reporter" => {
+            "handled" => handled == true, "severity" => severity.to_s, "source" => source.to_s
+          }}
+        }
+        details[:context]["rails_error_reporter"]["component"] = component(context)
+        @notifier.notify_once(error, details)
+      rescue StandardError
+        false
+      end
+
+      private
+
+      def component(context)
+        return "" unless context.is_a?(Hash)
+
+        (context[:controller] || context["controller"] || context[:job] || context["job"]).to_s[0, 128]
+      end
+    end
+  end
+end

data/lib/chronos/rails/installer.rb

@@ -34,6 +34,7 @@ module Chronos
 
           install_middleware(application, options)
           install_active_job
+          install_error_reporter
           @subscriber.install
           self.class.applications[application.object_id] = true
         end
@@ -65,6 +66,18 @@ module Chronos
         Chronos::Integrations::ActiveJob.install(::ActiveJob::Base, @notifier)
       end
 
+      def install_error_reporter
+        return false unless defined?(::Rails) && ::Rails.respond_to?(:error)
+
+        reporter = ::Rails.error
+        return false unless reporter && reporter.respond_to?(:subscribe)
+
+        reporter.subscribe(ErrorReporterSubscriber.new(@notifier))
+        true
+      rescue StandardError
+        false
+      end
+
       def environment
         defined?(::Rails) && ::Rails.respond_to?(:env) ? ::Rails.env.to_s : nil
       end

data/lib/chronos/rails/notifications_subscriber.rb

@@ -12,11 +12,12 @@ module Chronos
     #   Chronos::Rails::NotificationsSubscriber.new.install
     # @errors Subscriber failures are contained and never escape into Rails.
     # @performance Each notification builds a small allowlisted hash and queues asynchronously.
-    class NotificationsSubscriber
+    class NotificationsSubscriber # rubocop:disable Metrics/ClassLength
       EVENTS = %w(
         process_action.action_controller render_template.action_view sql.active_record
         deliver.action_mailer perform.active_job cache_read.active_support
         cache_write.active_support cache_fetch_hit.active_support
+        perform_action.action_cable transmit.action_cable broadcast.action_cable
       ).freeze
 
       @mutex = Mutex.new
@@ -26,10 +27,18 @@ module Chronos
         attr_reader :mutex, :installed_buses
       end
 
-      def initialize(notifier = Chronos, notifications = nil)
+      def initialize(notifier = Chronos, notifications = nil, options = {})
         @notifier = notifier
         @notifications = notifications || active_support_notifications
         @sql_normalizer = Core::SqlNormalizer.new
+        @query_analyzer = options[:query_analyzer] || Core::SqlQueryAnalyzer.new
+        @query_inspector = options[:query_inspector] || default_query_inspector
+        @query_inspection_mutex = Mutex.new
+        @query_inspections = {}
+        @query_analyses = {}
+        @clock = options[:clock] || proc { Process.clock_gettime(Process::CLOCK_MONOTONIC) }
+        @transaction_mutex = Mutex.new
+        @transactions = {}
         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
@@ -97,6 +106,8 @@ module Chronos
         when "sql.active_record" then sql(payload, duration)
         when "deliver.action_mailer" then mailer(payload, duration)
         when "perform.active_job" then active_job(payload, duration)
+        when "perform_action.action_cable", "transmit.action_cable", "broadcast.action_cable"
+          action_cable(name, payload, duration)
         else cache(name, payload, duration)
         end
       end
@@ -122,6 +133,8 @@ module Chronos
       end
 
       def sql(payload, duration)
+        return false if query_inspection_suppressed?
+
         metadata = {
           :name => value(payload, :name), :cached => value(payload, :cached),
           :adapter => value(payload, :adapter), :connection => value(payload, :connection),
@@ -131,9 +144,160 @@ module Chronos
         }
         metadata[:source] = sampled_query_source if duration >= slow_query_threshold
         data = @sql_normalizer.call(value(payload, :sql), metadata).merge("duration_ms" => duration)
+        track_transaction(data, metadata[:connection])
+        if query_analysis_options[:analysis_enabled]
+          inspection = query_inspection(value(payload, :sql), data, metadata[:connection], duration)
+          analysis = cached_query_analysis(data, inspection)
+          data["analysis"] = analysis unless analysis.empty?
+        end
         @notifier.record_event("query", data)
       end
 
+      def cached_query_analysis(data, inspection)
+        options = query_analysis_options
+        fingerprint = data["fingerprint"].to_s
+        @query_inspection_mutex.synchronize do
+          existing = @query_analyses[fingerprint]
+          return existing if existing && inspection.empty?
+          return existing if existing && !hash(existing["inspection"]).empty?
+          return {} unless existing || @query_analyses.length < options[:max_analyses]
+
+          @query_analyses[fingerprint] = @query_analyzer.call(data, inspection)
+        end
+      rescue StandardError => error
+        {"diagnostics" => [{"code" => "query_analysis_failed", "severity" => "error",
+                            "category" => "analysis", "message" => "Normalized query analysis failed",
+                            "evidence" => {"error_class" => safe_error_class(error)}}]}
+      end
+
+      def query_inspection(raw_sql, data, connection, duration)
+        options = query_analysis_options
+        return {} unless options[:inspection_enabled]
+        return {} unless duration >= options[:min_duration_ms]
+        return {} unless @query_inspector && Ports::QueryInspector.compatible?(@query_inspector)
+
+        fingerprint = data["fingerprint"].to_s
+        @query_inspection_mutex.synchronize do
+          return @query_inspections[fingerprint] if @query_inspections.key?(fingerprint)
+          return {} if @query_inspections.length >= options[:max_queries]
+
+          @query_inspections[fingerprint] = @query_inspector.call(
+            raw_sql, data, :connection => connection,
+                           :statistics => options[:statistics_enabled], :plan => options[:plan_enabled]
+          )
+        end
+      rescue StandardError => error
+        {"errors" => [safe_error_class(error)]}
+      end
+
+      def query_analysis_options
+        values = @notifier.respond_to?(:apm_integration_options) ? @notifier.apm_integration_options : {}
+        {
+          :analysis_enabled => values.fetch(:query_analysis_enabled, true) == true,
+          :max_analyses => (values[:query_analysis_max_queries] || 100).to_i,
+          :inspection_enabled => values[:query_inspection_enabled] == true,
+          :statistics_enabled => values[:query_statistics_enabled] == true,
+          :plan_enabled => values[:query_plan_enabled] == true,
+          :min_duration_ms => (values[:query_inspection_min_duration_ms] || 500.0).to_f,
+          :max_queries => (values[:query_inspection_max_queries] || 20).to_i,
+          :transaction_tracking_enabled => values.fetch(:transaction_tracking_enabled, true) == true,
+          :transaction_max_connections => (values[:transaction_max_connections] || 100).to_i,
+          :transaction_ttl_seconds => (values[:transaction_ttl_seconds] || 60.0).to_f
+        }
+      rescue StandardError
+        {:analysis_enabled => true, :max_analyses => 100,
+         :inspection_enabled => false, :statistics_enabled => false,
+         :plan_enabled => false, :min_duration_ms => 500.0, :max_queries => 20,
+         :transaction_tracking_enabled => true, :transaction_max_connections => 100,
+         :transaction_ttl_seconds => 60.0}
+      end
+
+      def track_transaction(data, connection)
+        options = query_analysis_options
+        return unless options[:transaction_tracking_enabled] && connection
+
+        operation = data["operation"].to_s
+        normalized = data["normalized_query"].to_s
+        key = connection.object_id.to_s
+        current_time = monotonic_now
+        @transaction_mutex.synchronize do
+          expire_tracked_transactions(current_time, options[:transaction_ttl_seconds])
+          details = {
+            :operation => operation, :normalized => normalized, :current_time => current_time,
+            :max_connections => options[:transaction_max_connections]
+          }
+          update_transaction_state(data, key, details)
+        end
+      rescue StandardError
+        nil
+      end
+
+      def update_transaction_state(data, key, details)
+        operation = details[:operation]
+        normalized = details[:normalized]
+        current_time = details[:current_time]
+        state = @transactions[key]
+        return start_tracked_transaction(key, state, current_time, details) if transaction_start?(operation, normalized)
+        return unless state
+
+        if operation == "SAVEPOINT"
+          state["depth"] += 1
+        elsif operation == "RELEASE" || normalized =~ /\AROLLBACK\s+TO\b/i
+          state["depth"] = [state["depth"] - 1, 1].max
+        elsif ["COMMIT", "ROLLBACK"].include?(operation)
+          finish_tracked_transaction(data, key, state, current_time)
+          return
+        end
+        state["last_seen_at"] = current_time
+      end
+
+      def transaction_start?(operation, normalized)
+        operation == "BEGIN" || normalized =~ /\ASTART\s+TRANSACTION\b/i
+      end
+
+      def start_tracked_transaction(key, state, current_time, details)
+        if state
+          state["depth"] += 1
+          state["last_seen_at"] = current_time
+        elsif @transactions.length < details[:max_connections]
+          @transactions[key] = {"started_at" => current_time, "last_seen_at" => current_time, "depth" => 1}
+        end
+      end
+
+      def finish_tracked_transaction(data, key, state, current_time)
+        @transactions.delete(key)
+        elapsed = [(current_time - state["started_at"]) * 1000.0, 0.0].max
+        data["transaction_duration_ms"] = elapsed.round(3)
+      end
+
+      def expire_tracked_transactions(current_time, ttl)
+        @transactions.delete_if { |_key, state| current_time - state["last_seen_at"] > ttl }
+      end
+
+      def monotonic_now
+        @clock.call.to_f
+      rescue StandardError
+        Time.now.to_f
+      end
+
+      def default_query_inspector
+        defined?(ActiveRecordQueryInspector) ? ActiveRecordQueryInspector.new : nil
+      rescue StandardError
+        nil
+      end
+
+      def query_inspection_suppressed?
+        defined?(ActiveRecordQueryInspector) && ActiveRecordQueryInspector.suppressed?
+      rescue StandardError
+        false
+      end
+
+      def safe_error_class(error)
+        error.class.name.to_s[0, 128]
+      rescue StandardError
+        "StandardError"
+      end
+
       def mailer(payload, duration)
         data = {
           "kind" => "mailer", "mailer" => value(payload, :mailer).to_s,
@@ -184,6 +348,15 @@ module Chronos
         @notifier.record_event("cache", data)
       end
 
+      def action_cable(name, payload, duration)
+        data = {
+          "kind" => "action_cable", "operation" => name.split(".").first,
+          "channel" => safe_class_name(value(payload, :channel)),
+          "action" => value(payload, :action).to_s[0, 128], "duration_ms" => duration
+        }
+        @notifier.record_event("request", data)
+      end
+
       def capture_controller_exception(payload)
         exception = value(payload, :exception_object)
         details = value(payload, :exception)

data/lib/chronos/rails.rb

@@ -1,5 +1,7 @@
 require "chronos"
+require "chronos/rails/active_record_query_inspector"
 require "chronos/rails/notifications_subscriber"
+require "chronos/rails/error_reporter_subscriber"
 require "chronos/integrations/active_job"
 require "chronos/rails/installer"
 

data/lib/chronos/version.rb

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

data/lib/chronos.rb

@@ -16,20 +16,24 @@ require "chronos/core/sensitive_value_filter"
 require "chronos/core/sanitizer"
 require "chronos/core/safe_serializer"
 require "chronos/core/correlation_context"
+require "chronos/core/trace_context"
 require "chronos/core/deploy_normalizer"
 require "chronos/core/payload_serializer"
 require "chronos/core/telemetry_event"
 require "chronos/core/sql_normalizer"
+require "chronos/core/sql_query_analyzer"
 require "chronos/core/metric_aggregate"
 require "chronos/core/cache_normalizer"
 require "chronos/ports/transport"
 require "chronos/ports/context_store"
+require "chronos/ports/query_inspector"
 require "chronos/internal/safe_logger"
 require "chronos/internal/bounded_queue"
 require "chronos/internal/memory_backlog"
 require "chronos/internal/worker_pool"
 require "chronos/adapters/net_http_transport"
 require "chronos/adapters/thread_local_context_store"
+require "chronos/adapters/fiber_local_context_store"
 require "chronos/core/breadcrumb"
 require "chronos/application/retry_policy"
 require "chronos/application/circuit_breaker"
@@ -47,6 +51,8 @@ require "chronos/observability_facade"
 require "chronos/integrations"
 require "chronos/integrations/rack"
 require "chronos/integrations/rack/middleware"
+require "chronos/integrations/opentelemetry"
+require "chronos/integrations/faraday"
 
 # Framework-independent public facade for the Chronos Ruby agent.
 #