chronos-ruby 1.0.0 → 1.1.1

data/lib/chronos/configuration.rb

@@ -23,6 +23,7 @@ module Chronos
   class Configuration
     include Internal::ConfigurationValidation
     include Internal::ApmConfigurationValidation
+    DEFAULT_HOST = "https://chronosmonitor.com.br".freeze
     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
@@ -47,7 +48,13 @@ module Chronos
       :apm_enabled, :apm_max_groups, :apm_flush_count, :apm_batch_size,
       :apm_max_queries_per_request, :apm_slow_query_threshold_ms,
       :apm_long_transaction_threshold_ms, :apm_n_plus_one_threshold,
-      :apm_histogram_buckets, :external_http_enabled, :external_http_trace_headers,
+      :apm_histogram_buckets, :apm_trace_ttl_seconds,
+      :apm_query_analysis_enabled, :apm_query_inspection_enabled,
+      :apm_query_analysis_max_queries,
+      :apm_query_statistics_enabled, :apm_query_plan_enabled,
+      :apm_query_inspection_min_duration_ms, :apm_query_inspection_max_queries,
+      :apm_transaction_tracking_enabled, :apm_transaction_max_connections,
+      :external_http_enabled, :external_http_trace_headers,
       :cache_key_mode, :dependency_reporting, :dependency_max_items
     ].freeze
 
@@ -99,7 +106,7 @@ module Chronos
     def initialize_core_defaults
       @project_id = nil
       @project_key = nil
-      @host = nil
+      @host = DEFAULT_HOST
       @environment = "production"
       @app_version = nil
       @service_name = nil
@@ -146,6 +153,16 @@ module Chronos
       @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]
+      @apm_trace_ttl_seconds = 60.0
+      @apm_query_analysis_enabled = true
+      @apm_query_analysis_max_queries = 100
+      @apm_query_inspection_enabled = false
+      @apm_query_statistics_enabled = false
+      @apm_query_plan_enabled = false
+      @apm_query_inspection_min_duration_ms = 500.0
+      @apm_query_inspection_max_queries = 20
+      @apm_transaction_tracking_enabled = true
+      @apm_transaction_max_connections = 100
     end
 
     def initialize_observability_defaults

data/lib/chronos/core/metric_aggregate.rb

@@ -2,18 +2,20 @@ module Chronos
   module Core
     # Accumulates one bounded APM metric group and serializes aggregate statistics.
     #
-    # @responsibility Track counts, errors, durations, histogram, breakdown, and signals.
+    # @responsibility Track counts, errors, durations, histogram, breakdown, signals, and diagnostics.
     # @motivation Keep numerical accumulation separate from grouping and request correlation.
-    # @limits It does not choose dimensions, retain observations, or calculate percentiles.
+    # @limits It does not choose dimensions, retain observations, or calculate exact 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}, {})
+    #   metric.observe(12.0, false, {"database" => 3.0}, {}, :diagnostics => [])
     # @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
+      DIAGNOSTIC_SEVERITIES = %w(error warning info suggestion).freeze
+      MAX_DIAGNOSTICS = 20
 
       def initialize(metric_type, dimensions, boundaries)
         @metric_type = metric_type
@@ -28,9 +30,12 @@ module Chronos
         @breakdown = {}
         @signals = {}
         @status_codes = {}
+        @diagnostics = {}
+        @severity_counts = {}
+        @query_analysis = nil
       end
 
-      def observe(duration, error, breakdown, signals, status = nil)
+      def observe(duration, error, breakdown, signals, options = {})
         value = non_negative(duration)
         @count += 1
         @error_count += 1 if error
@@ -41,7 +46,9 @@ module Chronos
         @buckets[bucket || @boundaries.length] += 1
         add_breakdown(breakdown)
         add_signals(signals)
-        add_status(status)
+        add_status(options[:status])
+        add_diagnostics(options[:diagnostics])
+        retain_query_analysis(options[:query_analysis])
         self
       end
 
@@ -50,9 +57,10 @@ module Chronos
           "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,
+          "duration_ms" => duration_summary, "percentiles_ms" => percentiles, "histogram" => histogram,
           "breakdown_ms" => rounded_hash(@breakdown), "signals" => @signals,
-          "status_codes" => @status_codes
+          "status_codes" => @status_codes, "severity_counts" => @severity_counts,
+          "diagnostics" => @diagnostics.values, "query_analysis" => @query_analysis || {}
         }
       end
 
@@ -81,6 +89,46 @@ module Chronos
         @status_codes[key] += 1
       end
 
+      def add_diagnostics(values)
+        Array(values).first(MAX_DIAGNOSTICS).each do |diagnostic|
+          data = hash(diagnostic)
+          severity = data["severity"].to_s
+          next unless DIAGNOSTIC_SEVERITIES.include?(severity)
+
+          @severity_counts[severity] ||= 0
+          @severity_counts[severity] += 1
+          key = diagnostic_key(data)
+          existing = @diagnostics[key]
+          if existing
+            existing["count"] += 1
+          elsif @diagnostics.length < MAX_DIAGNOSTICS
+            @diagnostics[key] = data.merge("count" => 1)
+          end
+        end
+      end
+
+      def diagnostic_key(data)
+        evidence = hash(data["evidence"])
+        [data["code"], data["severity"], evidence["table"], Array(evidence["columns"]).join(",")].join("|")
+      end
+
+      def retain_query_analysis(value)
+        return unless value.is_a?(Hash) && !value.empty?
+        return if @query_analysis && analysis_score(@query_analysis) >= analysis_score(value)
+
+        @query_analysis = value.reject { |key, _child| key.to_s == "diagnostics" }
+      end
+
+      def analysis_score(value)
+        data = hash(value)
+        inspection = hash(data["inspection"] || data[:inspection])
+        score = inspection.empty? ? 0 : 1
+        score += 1 unless Array(inspection["indexes"] || inspection[:indexes]).empty?
+        score += 1 unless hash(inspection["statistics"] || inspection[:statistics]).empty?
+        score += 1 unless hash(inspection["plan"] || inspection[:plan]).empty?
+        score
+      end
+
       def duration_summary
         {
           "total" => @total.round(3), "min" => @min.round(3), "max" => @max.round(3),
@@ -94,6 +142,20 @@ module Chronos
         end
       end
 
+      def percentiles
+        {"p50" => percentile(0.50), "p95" => percentile(0.95), "p99" => percentile(0.99)}
+      end
+
+      def percentile(ratio)
+        target = (@count * ratio).ceil
+        accumulated = 0
+        @buckets.each_with_index do |count, index|
+          accumulated += count
+          return (@boundaries[index] || @max).to_f.round(3) if accumulated >= target
+        end
+        @max.to_f.round(3)
+      end
+
       def rounded_hash(values)
         values.each_with_object({}) { |(key, value), result| result[key] = value.round(3) }
       end

data/lib/chronos/core/sql_query_analyzer.rb

@@ -0,0 +1,309 @@
+module Chronos
+  module Core
+    # Derives bounded query-shape evidence and index recommendations from normalized SQL.
+    #
+    # @responsibility Extract tables and access columns, compare index metadata, and emit diagnostics.
+    # @motivation Give the Chronos consumer actionable SQL evidence without collecting binds or raw SQL.
+    # @limits It is a defensive heuristic for SELECT statements, not a dialect-complete parser or optimizer.
+    # @collaborators SqlNormalizer and an optional query-inspection adapter.
+    # @thread_safety Instances are stateless and safe to share.
+    # @compatibility Ruby 2.2.10 through Ruby 2.6; independent of Rails and database drivers.
+    # @example
+    #   SqlQueryAnalyzer.new.call("normalized_query" => "SELECT * FROM users WHERE email = ?")
+    # @errors Malformed input returns an empty bounded analysis and never escapes.
+    # @performance Input, tables, columns, candidates, diagnostics, and inspection evidence are capped.
+    class SqlQueryAnalyzer # rubocop:disable Metrics/ClassLength
+      MAX_TABLES = 8
+      MAX_COLUMNS = 12
+      MAX_INDEXES = 20
+      MAX_DIAGNOSTICS = 20
+      IDENTIFIER = "[A-Za-z_][A-Za-z0-9_$]*".freeze
+      TABLE_PATTERN = /\b(?:FROM|JOIN)\s+["`\[]?(#{IDENTIFIER}(?:\.#{IDENTIFIER})?)["`\]]?
+                       (?:\s+(?:AS\s+)?(#{IDENTIFIER}))?/ix
+      CLAUSE_END = /\b(?:GROUP\s+BY|ORDER\s+BY|HAVING|LIMIT|OFFSET|UNION|RETURNING)\b/i
+      RESERVED = %w(WHERE JOIN LEFT RIGHT INNER OUTER FULL CROSS ON GROUP ORDER HAVING LIMIT OFFSET).freeze
+
+      def call(query, inspection = {})
+        data = hash(query)
+        normalized = bounded(data["normalized_query"] || data[:normalized_query], 512)
+        operation = (data["operation"] || data[:operation]).to_s.upcase
+        return empty_analysis(operation) unless operation == "SELECT" && !normalized.empty?
+
+        aliases = table_aliases(normalized, data["table"] || data[:table])
+        access = access_columns(normalized, aliases)
+        candidates = index_candidates(access, hash(inspection))
+        evidence = inspection_evidence(inspection)
+        {
+          "operation" => operation,
+          "tables" => aliases.values.uniq.first(MAX_TABLES),
+          "access_columns" => access,
+          "index_candidates" => candidates,
+          "inspection" => evidence,
+          "diagnostics" => diagnostics(candidates, evidence)
+        }
+      rescue StandardError
+        empty_analysis("UNKNOWN")
+      end
+
+      private
+
+      def empty_analysis(operation)
+        {
+          "operation" => operation.to_s.empty? ? "UNKNOWN" : operation.to_s,
+          "tables" => [], "access_columns" => {}, "index_candidates" => [],
+          "inspection" => {}, "diagnostics" => []
+        }
+      end
+
+      def table_aliases(sql, fallback)
+        result = {}
+        sql.scan(TABLE_PATTERN) do |table, name|
+          alias_name = name.to_s
+          alias_name = table.to_s.split(".").last if alias_name.empty? || RESERVED.include?(alias_name.upcase)
+          result[alias_name] = bounded_identifier(table)
+          break if result.length >= MAX_TABLES
+        end
+        if result.empty? && !fallback.to_s.empty?
+          table = bounded_identifier(fallback)
+          result[table.split(".").last] = table unless table.empty?
+        end
+        result
+      end
+
+      def access_columns(sql, aliases)
+        result = {}
+        aliases.values.uniq.each do |table|
+          result[table] = {"equality" => [], "range" => [], "join" => [], "order" => []}
+        end
+        base_table = aliases.values.first
+        where = clause(sql, /\bWHERE\b/i, CLAUSE_END)
+        collect_predicates(where, aliases, base_table, result)
+        collect_join_predicates(sql, aliases, result)
+        collect_order_columns(clause(sql, /\bORDER\s+BY\b/i, /\b(?:LIMIT|OFFSET|UNION|RETURNING)\b/i), aliases,
+                              base_table, result)
+        result.delete_if { |_table, groups| groups.values.all?(&:empty?) }
+      end
+
+      def collect_predicates(section, aliases, base_table, result)
+        return if section.empty?
+
+        pattern = /(?:(#{IDENTIFIER})\.)?(#{IDENTIFIER})\s*(=|<>|!=|<=|>=|<|>|\bIN\b|\bIS\b|\bLIKE\b)/i
+        section.scan(pattern).each do |alias_name, column, operator|
+          table = alias_name.to_s.empty? ? base_table : aliases[alias_name]
+          next unless table && result[table]
+
+          group = ["=", "IN", "IS"].include?(operator.to_s.upcase) ? "equality" : "range"
+          append_column(result[table][group], column)
+        end
+      end
+
+      def collect_join_predicates(sql, aliases, result)
+        sql.scan(/\bON\b(.*?)(?=\b(?:JOIN|WHERE|GROUP\s+BY|ORDER\s+BY|HAVING|LIMIT|OFFSET)\b|\z)/im) do |match|
+          match.first.to_s.scan(/(#{IDENTIFIER})\.(#{IDENTIFIER})/i).each do |alias_name, column|
+            table = aliases[alias_name]
+            append_column(result[table]["join"], column) if table && result[table]
+          end
+        end
+      end
+
+      def collect_order_columns(section, aliases, base_table, result)
+        section.split(",").first(MAX_COLUMNS).each do |item|
+          match = item.match(/(?:(#{IDENTIFIER})\.)?(#{IDENTIFIER})(?:\s+(?:ASC|DESC))?/i)
+          next unless match
+
+          table = match[1].to_s.empty? ? base_table : aliases[match[1]]
+          append_column(result[table]["order"], match[2]) if table && result[table]
+        end
+      end
+
+      def index_candidates(access, inspection)
+        indexes = Array(inspection["indexes"] || inspection[:indexes]).first(MAX_INDEXES)
+        access.map do |table, groups|
+          columns = (groups["equality"] + groups["join"] + groups["range"] + groups["order"]).uniq.first(MAX_COLUMNS)
+          next if columns.empty?
+
+          covering = indexes.find { |index| index_covers?(index, table, columns) }
+          {
+            "table" => table, "columns" => columns,
+            "status" => candidate_status(indexes, covering),
+            "covered_by" => covering ? bounded(hash(covering)["name"] || hash(covering)[:name], 128) : nil,
+            "confidence" => candidate_confidence(inspection, covering)
+          }.delete_if { |_key, value| value.nil? || value == "" }
+        end.compact.first(MAX_TABLES)
+      end
+
+      def candidate_status(indexes, covering)
+        return "unverified" if indexes.empty?
+
+        covering ? "covered" : "missing"
+      end
+
+      def index_covers?(index, table, columns)
+        data = hash(index)
+        return false unless (data["table"] || data[:table]).to_s == table.to_s
+
+        existing = Array(data["columns"] || data[:columns]).map(&:to_s)
+        existing.first(columns.length) == columns
+      end
+
+      def candidate_confidence(inspection, covering)
+        return "high" if covering
+
+        plan = hash(hash(inspection)["plan"] || hash(inspection)[:plan])
+        return "high" if plan["sequential_scan"] == true || plan[:sequential_scan] == true
+        return "medium" unless Array(hash(inspection)["indexes"] || hash(inspection)[:indexes]).empty?
+
+        "low"
+      end
+
+      def inspection_evidence(value)
+        data = hash(value)
+        result = {"indexes" => bounded_indexes(data["indexes"] || data[:indexes])}
+        statistics = hash(data["statistics"] || data[:statistics])
+        result["statistics"] = bounded_statistics(statistics) unless statistics.empty?
+        plan = hash(data["plan"] || data[:plan])
+        result["plan"] = bounded_plan(plan) unless plan.empty?
+        errors = bounded_errors(data["errors"] || data[:errors])
+        result["errors"] = errors unless errors.empty?
+        result
+      end
+
+      def bounded_indexes(values)
+        Array(values).first(MAX_INDEXES).map do |index|
+          item = hash(index)
+          columns = Array(item["columns"] || item[:columns]).first(MAX_COLUMNS)
+          {
+            "table" => bounded_identifier(item["table"] || item[:table]),
+            "name" => bounded(item["name"] || item[:name], 128),
+            "columns" => columns.map { |column| bounded_identifier(column) },
+            "unique" => item["unique"] == true || item[:unique] == true
+          }
+        end
+      end
+
+      def bounded_errors(values)
+        Array(values).first(5).map { |error| bounded(error, 128) }
+      end
+
+      def bounded_statistics(statistics)
+        {
+          "estimated_rows" => non_negative_integer(statistics["estimated_rows"] || statistics[:estimated_rows]),
+          "source" => bounded(statistics["source"] || statistics[:source], 64)
+        }.delete_if { |_key, value| value.nil? || value == "" }
+      end
+
+      def bounded_plan(plan)
+        {
+          "nodes" => Array(plan["nodes"] || plan[:nodes]).first(20).map do |node|
+            bounded_plan_node(node)
+          end,
+          "uses_index" => plan["uses_index"] == true || plan[:uses_index] == true,
+          "sequential_scan" => plan["sequential_scan"] == true || plan[:sequential_scan] == true
+        }
+      end
+
+      def bounded_plan_node(node)
+        data = hash(node)
+        {
+          "type" => bounded(data["type"] || data[:type], 64),
+          "table" => bounded_identifier(data["table"] || data[:table]),
+          "index" => bounded(data["index"] || data[:index], 128),
+          "estimated_rows" => non_negative_integer(data["estimated_rows"] || data[:estimated_rows]),
+          "total_cost" => non_negative_number(data["total_cost"] || data[:total_cost])
+        }.delete_if { |_key, child| child.nil? || child == "" }
+      end
+
+      def diagnostics(candidates, inspection)
+        result = [diagnostic("query_pattern_analyzed", "info", "query_pattern", {},
+                             "Normalized SELECT access pattern was analyzed")]
+        candidates.each do |candidate|
+          status = candidate["status"]
+          code = index_diagnostic_code(status)
+          severity = status == "covered" ? "info" : "suggestion"
+          result << diagnostic(code, severity, "index", candidate, index_diagnostic_message(status))
+        end
+        plan = hash(inspection["plan"])
+        if plan["sequential_scan"] == true
+          result << diagnostic("sequential_scan", "warning", "plan", {},
+                               "The bounded query plan contains a sequential scan")
+        end
+        Array(inspection["errors"]).each do |error|
+          result << diagnostic("query_inspection_failed", "error", "inspection", {"error_class" => error},
+                               "Read-only query inspection failed")
+        end
+        result.first(MAX_DIAGNOSTICS)
+      end
+
+      def index_diagnostic_code(status)
+        return "missing_index_candidate" if status == "missing"
+        return "index_covered" if status == "covered"
+
+        "index_candidate"
+      end
+
+      def index_diagnostic_message(status)
+        return "Existing index covers the observed access pattern" if status == "covered"
+
+        "Review a candidate index for the observed access pattern"
+      end
+
+      def diagnostic(code, severity, category, evidence, message)
+        result = {
+          "code" => code, "severity" => severity, "category" => category,
+          "message" => message, "evidence" => evidence
+        }
+        if severity == "suggestion"
+          result["recommendation"] = "Validate selectivity and write cost before creating the candidate index"
+        end
+        result
+      end
+
+      def clause(sql, start_pattern, finish_pattern)
+        start = sql.index(start_pattern)
+        return "" unless start
+
+        tail = sql[start..-1].to_s.sub(start_pattern, "")
+        finish = tail.index(finish_pattern)
+        finish ? tail[0...finish] : tail
+      end
+
+      def append_column(collection, value)
+        column = bounded_identifier(value)
+        collection << column if !column.empty? && !collection.include?(column) && collection.length < MAX_COLUMNS
+      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
+
+      def non_negative_integer(value)
+        return nil if value.nil?
+
+        [value.to_i, 0].max
+      rescue StandardError
+        nil
+      end
+
+      def non_negative_number(value)
+        return nil if value.nil?
+
+        number = value.to_f
+        number < 0.0 ? 0.0 : number
+      rescue StandardError
+        nil
+      end
+
+      def hash(value)
+        value.is_a?(Hash) ? value : {}
+      end
+    end
+  end
+end

data/lib/chronos/ports/query_inspector.rb

@@ -0,0 +1,23 @@
+module Chronos
+  module Ports
+    # Documents the optional read-only database-inspection boundary used by SQL monitoring.
+    #
+    # @responsibility Define compatibility for index, statistics, and plan inspection adapters.
+    # @motivation Keep database and ActiveRecord behavior outside the framework-independent core.
+    # @limits It does not require inspection, execute DDL, or prescribe a database driver.
+    # @thread_safety Implementations define their own connection and concurrency guarantees.
+    # @compatibility The compatibility check uses APIs available in Ruby 2.2.10.
+    # @example
+    #   QueryInspector.compatible?(adapter) #=> true
+    # @errors Compatibility checks contain objects with failing reflection methods.
+    module QueryInspector
+      REQUIRED_METHODS = [:call].freeze
+
+      def self.compatible?(object)
+        REQUIRED_METHODS.all? { |method_name| object.respond_to?(method_name) }
+      rescue StandardError
+        false
+      end
+    end
+  end
+end