chronos-ruby 1.0.0 → 1.1.0

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/notifications_subscriber.rb

@@ -12,7 +12,7 @@ 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
@@ -26,10 +26,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
@@ -122,6 +130,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 +141,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,

data/lib/chronos/rails.rb

@@ -1,4 +1,5 @@
 require "chronos"
+require "chronos/rails/active_record_query_inspector"
 require "chronos/rails/notifications_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
+  VERSION = "1.1.0".freeze
 end

data/lib/chronos.rb

@@ -20,10 +20,12 @@ 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"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: chronos-ruby
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Antonio Jefferson
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-07-29 00:00:00.000000000 Z
+date: 2026-08-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -125,6 +125,7 @@ files:
 - docs/adr/ADR-016-explicit-observability-integrations.md
 - docs/adr/ADR-017-deploy-events-and-correlation.md
 - docs/adr/ADR-018-pre-1.0-hardening.md
+- docs/adr/ADR-019-bounded-query-diagnostics.md
 - docs/architecture.md
 - docs/compatibility.md
 - docs/configuration.md
@@ -164,6 +165,7 @@ files:
 - docs/privacy-lgpd.md
 - docs/protocol-v1.md
 - docs/release-1.0-readiness.md
+- docs/release-1.1-readiness.md
 - docs/security-review.md
 - docs/semver.md
 - docs/troubleshooting.md
@@ -206,6 +208,7 @@ files:
 - lib/chronos/core/sanitizer.rb
 - lib/chronos/core/sensitive_value_filter.rb
 - lib/chronos/core/sql_normalizer.rb
+- lib/chronos/core/sql_query_analyzer.rb
 - lib/chronos/core/telemetry_event.rb
 - lib/chronos/errors.rb
 - lib/chronos/integrations.rb
@@ -225,8 +228,10 @@ files:
 - lib/chronos/observability_facade.rb
 - lib/chronos/ports.rb
 - lib/chronos/ports/context_store.rb
+- lib/chronos/ports/query_inspector.rb
 - lib/chronos/ports/transport.rb
 - lib/chronos/rails.rb
+- lib/chronos/rails/active_record_query_inspector.rb
 - lib/chronos/rails/installer.rb
 - lib/chronos/rails/notifications_subscriber.rb
 - lib/chronos/rails/railtie.rb