chronos-ruby 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3fc9daff111666fdf7309797c5f8aa81a639c8f59ea1733be48740b9aea6b247
-  data.tar.gz: a8d7cd786b233078e5516e3d1ce0c92b986d045ebd4d8c29a7d9cd80ae75fb93
+  metadata.gz: 0127def72275a2d4c08314040c04e34a9606fed13982d84b06c465dee7be4cf6
+  data.tar.gz: 99f272314517e6a525223ce86964b70fcdfce717eb0e434b9c77e275031913b7
 SHA512:
-  metadata.gz: 1f60a09480aa5766676d673579ffe1b5b007d044881fc9b1f70f672c414ddf7e1a014cc63eaeee8ee6f63fa7261aa5dc92f8f9b1cc6089898ecf015d1940a83c
-  data.tar.gz: '08342c5a665004cbfa9fec52164f86e82d003b3d587bf931ae220c44ec4188c91141852e424f726f55a7b7d5dec4592190dc7cef9dc6c4e05f0eec8255bd32b4'
+  metadata.gz: 93b37af1a5b51284a6c6de1c19e12de18ac23b04bfa4a04f33b7fce5cb611ec6f940d4ec2508c8a2b8d72f91e9a2a9a812a3b48d72f60dfefd642fb7cf3fe138
+  data.tar.gz: 4c653acb6d7aa90d534a7d496568fca64fb9ba9bce9039c6ca68fad71c1b5aef3f4e5de541a3f3d0f6064f08653359bcc2afc30e3a2d82c910942f0c1e103d4a

data/CHANGELOG.md

@@ -4,6 +4,24 @@ All notable changes are documented here. The project follows Semantic Versioning
 
 ## [Unreleased]
 
+## [1.1.0] - 2026-08-05
+
+### Added
+
+- bounded normalized SELECT analysis with access columns, index candidates, existing-index comparison, optional table statistics, and allowlisted non-executing query plans;
+- structured query diagnostics and severity counts for errors, warnings, information, and suggestions, including actionable N+1 and index guidance;
+- approximate p50/p95/p99 metrics, complete outer-transaction timing, expanded adapter error families, and trace/fingerprint loss counters;
+- explicit low-risk defaults and bounded opt-in configuration for database index/statistics/plan inspection.
+
+### Changed
+
+- aggregate drains preserve active trace trackers until request completion or idle TTL instead of discarding incomplete correlation;
+- possible N+1 now requires a non-cached SELECT, and query analysis sent to consumers prefers inspected evidence over an earlier static-only observation.
+
+### Security
+
+- query inspection never uses `EXPLAIN ANALYZE`, never executes DDL, omits raw SQL/binds/predicates/messages, and retains only bounded schema and planner fields.
+
 ## [1.0.0] - 2026-07-29
 
 ### Added

data/README.md

@@ -1,10 +1,10 @@
 # Chronos Ruby
 
-Chronos Ruby 1.0.0 é o agente independente de framework para enviar exceções e telemetria limitada de aplicações Ruby ao Chronos. Esta é a linha estável legado, compatível com o protocolo v1 e voltada a Ruby 2.2.10–2.6.
+Chronos Ruby 1.1.0 é o agente independente de framework para enviar exceções e telemetria limitada de aplicações Ruby ao Chronos. Esta é a linha estável legado, compatível com o protocolo v1 e voltada a Ruby 2.2.10–2.6.
 
 ## O que a gem coleta
 
-A versão 1.0 pode coletar:
+A versão 1.1 pode coletar:
 
 - classe, mensagem, backtrace estruturado e causas encadeadas da exceção;
 - timestamp, severidade, tags e fingerprint opcional;
@@ -20,11 +20,11 @@ Veja a tabela completa em [Dados coletados](docs/data-collected.md).
 
 ## O que não é coletado por padrão
 
-A gem não varre variáveis de ambiente, sistema de arquivos ou lockfiles e não lê bodies HTTP, cookies, headers de autorização, conteúdo de e-mail, SQL bruto, binds, valores de cache ou código-fonte. O inventário de dependências contém somente nomes e versões já carregados, uma vez por agente. A aplicação continua responsável por minimização e base legal dos dados enviados.
+A gem não varre variáveis de ambiente, sistema de arquivos ou lockfiles e não coleta bodies HTTP, cookies, headers de autorização, conteúdo de e-mail, SQL bruto, binds, valores de cache ou código-fonte. A inspeção de plano, desativada por padrão, usa o SQL original somente na conexão local para `EXPLAIN` sem `ANALYZE` e o descarta. O inventário de dependências contém somente nomes e versões já carregados, uma vez por agente. A aplicação continua responsável por minimização e base legal dos dados enviados.
 
 ## Versões Ruby e Rails suportadas
 
-A versão 1.0.0 suporta Ruby puro e Rack em Ruby 2.2.10, 2.3.8, 2.4.10, 2.5.9 e 2.6.10. As combinações Rails validadas são Rails 4.2 com Ruby 2.2.10/2.3.8 e Rails 5.2 com Ruby 2.5.9/2.6.10. Sidekiq 4.2.10 com Ruby 2.2.10 e Sidekiq 5.2.10 com Ruby 2.5.9 também possuem gates dedicados.
+A versão 1.1.0 suporta Ruby puro e Rack em Ruby 2.2.10, 2.3.8, 2.4.10, 2.5.9 e 2.6.10. As combinações Rails validadas são Rails 4.2 com Ruby 2.2.10/2.3.8 e Rails 5.2 com Ruby 2.5.9/2.6.10. Sidekiq 4.2.10 com Ruby 2.2.10 e Sidekiq 5.2.10 com Ruby 2.5.9 também possuem gates dedicados. Ruby 2.7/Rails 6 não é declarado nesta release porque ainda não possui aplicação e matriz completas.
 
 Rubies e frameworks antigos estão fora do suporte de segurança de seus mantenedores. A Chronos oferece compatibilidade técnica, não manutenção de segurança do runtime. Veja [Compatibilidade](docs/compatibility.md).
 
@@ -33,7 +33,7 @@ Rubies e frameworks antigos estão fora do suporte de segurança de seus mantene
 Obrigatório: adicione a versão estável ao `Gemfile`.
 
 ```ruby
-gem "chronos-ruby", "~> 1.0.0"
+gem "chronos-ruby", "~> 1.1.0"
 ```
 
 Em runtimes antigos, use Bundler compatível:
@@ -46,7 +46,7 @@ bundle _1.17.3_ install
 Sem Bundler:
 
 ```bash
-gem install chronos-ruby -v 1.0.0
+gem install chronos-ruby -v 1.1.0
 ```
 
 ## Instalação em Rails
@@ -54,7 +54,7 @@ gem install chronos-ruby -v 1.0.0
 Obrigatório: carregue a integração Rails explicitamente para manter Rails/ActiveSupport fora de aplicações Ruby puras.
 
 ```ruby
-gem "chronos-ruby", "~> 1.0.0", :require => "chronos/rails"
+gem "chronos-ruby", "~> 1.1.0", :require => "chronos/rails"
 ```
 
 Gere o initializer:
@@ -174,7 +174,7 @@ A regra recebe um notice normalizado e imutável, e somente `true` descarta. Fal
 
 ## Monitoramento de performance
 
-A Versão 0.7 introduziu agregação local de requests, queries e jobs em `metric_batch`; a Versão 0.8 adicionou HTTP externo. Grupos possuem contagem, erro, duração, histograma, status e breakdown limitados. Percentis são calculados no SaaS.
+A Versão 0.7 introduziu agregação local de requests, queries e jobs em `metric_batch`; a Versão 0.8 adicionou HTTP externo. Grupos possuem contagem, erro, duração, histograma, percentis aproximados, severidades, diagnósticos, status e breakdown limitados.
 
 ```ruby
 Chronos.configure do |config|
@@ -185,10 +185,22 @@ Chronos.configure do |config|
   config.apm_max_queries_per_request = 100
   config.apm_slow_query_threshold_ms = 500.0
   config.apm_n_plus_one_threshold = 5
+  config.apm_trace_ttl_seconds = 60.0
+  config.apm_query_analysis_enabled = true
+  config.apm_query_analysis_max_queries = 100
+
+  # Opt-in: cada fingerprint elegível pode consultar catálogo/estatística/plano.
+  config.apm_query_inspection_enabled = false
+  config.apm_query_statistics_enabled = false
+  config.apm_query_plan_enabled = false
+  config.apm_query_inspection_min_duration_ms = 500.0
+  config.apm_query_inspection_max_queries = 20
+  config.apm_transaction_tracking_enabled = true
+  config.apm_transaction_max_connections = 100
 end
 ```
 
-SQL bruto e binds não são lidos. Sinais de query lenta, repetição, possível N+1, transação longa, conexão e deadlock são heurísticos. Veja [APM](docs/modules/apm-aggregation.md), [Requests](docs/modules/request-monitoring.md) e [SQL](docs/modules/sql-monitoring.md).
+Por padrão, SQL bruto e binds não são lidos pelo pipeline de análise. A inspeção opt-in usa o SQL original apenas localmente para solicitar `EXPLAIN` sem `ANALYZE`; nunca o inclui no evento. A análise estática produz candidatos, não ordens de criação de índice. Erros usam severidade `error`; lentidão e risco usam `warning`; padrões observados usam `info`; correções propostas usam `suggestion`. Veja [APM](docs/modules/apm-aggregation.md), [Requests](docs/modules/request-monitoring.md) e [SQL](docs/modules/sql-monitoring.md).
 
 ## Sidekiq e Active Job
 
@@ -196,7 +208,7 @@ A versão `0.6.0.pre.1` introduziu middleware Sidekiq 4/5; a API estável manté
 
 ```ruby
 gem "sidekiq", "~> 5.0"
-gem "chronos-ruby", "~> 1.0.0", :require => "chronos/sidekiq"
+gem "chronos-ruby", "~> 1.1.0", :require => "chronos/sidekiq"
 ```
 
 O envelope de contexto não altera argumentos públicos e contém somente IDs limitados de trace/request. Active Job usa um campo serializado com namespace (`chronos_context`) e hooks públicos. Erros aninhados são deduplicados e reerguidos. Veja [Sidekiq legado](docs/modules/sidekiq-legacy.md), [Active Job](docs/modules/active-job.md) e [Jobs](docs/modules/job-monitoring.md).

data/contracts/apm-batch-v1.schema.json

@@ -24,10 +24,60 @@
             "type": "object",
             "required": ["total", "min", "max", "average"]
           },
+          "percentiles_ms": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["p50", "p95", "p99"],
+            "properties": {
+              "p50": {"type": "number", "minimum": 0},
+              "p95": {"type": "number", "minimum": 0},
+              "p99": {"type": "number", "minimum": 0}
+            }
+          },
           "histogram": {"type": "array", "maxItems": 20},
           "breakdown_ms": {"type": "object"},
           "signals": {"type": "object"},
-          "status_codes": {"type": "object"}
+          "status_codes": {"type": "object"},
+          "severity_counts": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "error": {"type": "integer", "minimum": 0},
+              "warning": {"type": "integer", "minimum": 0},
+              "info": {"type": "integer", "minimum": 0},
+              "suggestion": {"type": "integer", "minimum": 0}
+            }
+          },
+          "diagnostics": {
+            "type": "array",
+            "maxItems": 20,
+            "items": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["code", "severity", "category", "message", "evidence", "count"],
+              "properties": {
+                "code": {"type": "string", "maxLength": 128},
+                "severity": {"enum": ["error", "warning", "info", "suggestion"]},
+                "category": {"type": "string", "maxLength": 64},
+                "message": {"type": "string", "maxLength": 512},
+                "recommendation": {"type": "string", "maxLength": 512},
+                "evidence": {"type": "object"},
+                "count": {"type": "integer", "minimum": 1}
+              }
+            }
+          },
+          "query_analysis": {"type": "object"},
+          "tracking": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["active_traces", "dropped_trace_trackers", "expired_trace_trackers", "dropped_query_fingerprints"],
+            "properties": {
+              "active_traces": {"type": "integer", "minimum": 0},
+              "dropped_trace_trackers": {"type": "integer", "minimum": 0},
+              "expired_trace_trackers": {"type": "integer", "minimum": 0},
+              "dropped_query_fingerprints": {"type": "integer", "minimum": 0}
+            }
+          }
         }
       }
     }

data/docs/adr/ADR-015-bounded-apm-aggregation.md

@@ -2,7 +2,7 @@
 
 ## Status
 
-Accepted for version 0.7.
+Accepted for version 0.7; trace-drain behavior amended by ADR-019.
 
 ## Context
 
@@ -12,7 +12,7 @@ Sending every request, SQL query, and job as an independent event increases netw
 
 Aggregate request, query, and job observations by bounded low-cardinality dimensions. Store only counters, error counters, duration sum/min/max, fixed histogram buckets, component totals, status counters, and heuristic signal counters. Calculate averages locally and percentiles in the SaaS.
 
-Use a fixed group limit, fixed query-fingerprint limit per trace, fixed batch size, and no new timer thread. Drain on observation threshold, explicit flush, and close. Clear incomplete trace trackers during drain. Normalize SQL comments and literal values before fingerprinting and never read binds. Use a `metric_batch` event through the existing sanitization, queue, retry, circuit breaker, and backlog pipeline.
+Use a fixed group limit, fixed query-fingerprint limit per trace, fixed batch size, and no new timer thread. Drain on observation threshold, explicit flush, and close. ADR-019 later preserves incomplete trace trackers across drains under capacity and idle-TTL limits. Normalize SQL comments and literal values before fingerprinting and never read binds. Use a `metric_batch` event through the existing sanitization, queue, retry, circuit breaker, and backlog pipeline.
 
 ## Alternatives
 
@@ -24,4 +24,4 @@ Delivery volume is reduced, memory remains bounded, request breakdown is availab
 
 ## Negative consequences
 
-Process crashes can lose undrained aggregates, incomplete trackers are discarded on drain, local signals are heuristic, and a defensive SQL normalizer cannot understand every database dialect.
+Process crashes can lose undrained aggregates, idle/over-capacity trackers can be discarded and are counted, local signals are heuristic, and a defensive SQL normalizer cannot understand every database dialect.

data/docs/adr/ADR-019-bounded-query-diagnostics.md

@@ -0,0 +1,44 @@
+# ADR-019 — Bounded query diagnostics and opt-in database inspection
+
+## Status
+
+Accepted.
+
+## Context
+
+Fingerprint repetition and duration identify useful SQL symptoms but do not tell the consumer which access columns were observed, whether an existing index covers them, or what the database planner estimated. Running deep analysis inside a legacy application can add latency, expose data, increase cardinality, and violate the fixed-memory requirement.
+
+## Decision
+
+Analyze normalized SELECT text by default with a dependency-free bounded heuristic. Emit structured diagnostics with stable code, severity (`error`, `warning`, `info`, `suggestion`), category, bounded evidence, count, and optional recommendation.
+
+Define `Ports::QueryInspector` and keep its ActiveRecord implementation in `Chronos::Rails`. Index, statistics, and plan inspection are independent explicit opt-ins. Inspect each eligible fingerprint at most once per subscriber, cap inspected fingerprints, and require a duration threshold. Plans use `EXPLAIN` only, never `EXPLAIN ANALYZE`; DDL and automatic index creation are prohibited. Retain only allowlisted schema/planner fields and exception class names. Never retain raw SQL, binds, plan predicates, arbitrary rows, or exception messages.
+
+Preserve trace trackers across metric drains with capacity and idle TTL. Report loss counters. Measure outer transaction time with bounded per-connection notification state. Derive approximate p50/p95/p99 from fixed histograms without retaining duration samples.
+
+Keep new metric fields optional in the v1 JSON Schema for backward compatibility, although the new agent emits them. Consumer models use diagnostic code/severity as stable fields and treat message text as a fallback presentation value.
+
+## Alternatives
+
+- Server-only static analysis was rejected because existing-index comparison requires local schema evidence and immediate signals remain useful.
+- Automatic `EXPLAIN ANALYZE` was rejected because it executes the query.
+- Automatic `CREATE INDEX` was rejected because it can block writes, consume storage, and regress mutation workloads.
+- Shipping raw SQL/plans was rejected for privacy and cardinality.
+- A full SQL-parser dependency was rejected for legacy compatibility, installation cost, and dialect complexity.
+- Unbounded trace/inspection caches were rejected for memory safety.
+
+## Positive consequences
+
+- Consumers receive actionable, typed evidence with clear confidence limits.
+- Default analysis adds no database round trip.
+- Opt-in inspection is read-only, sampled by fingerprint/duration, and contains adapter failures.
+- Errors, warnings, information, and suggestions can map directly to observer models.
+- Trace correlation no longer disappears at every aggregate flush.
+
+## Negative consequences
+
+- Static parsing can miss complex SQL, aliases, expressions, partial indexes, and dialect features.
+- Even non-executing `EXPLAIN` and catalog reads consume a connection/planner budget and have no portable legacy timeout.
+- Index recommendations do not know true selectivity, write cost, storage, or production distribution.
+- Approximate percentiles use histogram upper bounds and may be coarse.
+- Transaction elapsed time is measured between notification callbacks, not database wire boundaries.

data/docs/architecture.md

@@ -20,7 +20,10 @@ flowchart TB
   Sidekiq --> Envelope[Versioned job-envelope context]
   Application --> Telemetry[Core / TelemetryEvent]
   Telemetry --> APM[Application / ApmAggregator]
-  APM --> Metrics[Core / MetricAggregate and SqlNormalizer]
+  APM --> Metrics[Core / MetricAggregate, SqlNormalizer, and SqlQueryAnalyzer]
+  Rails --> Inspector[ActiveRecordQueryInspector opt-in]
+  Inspector --> QueryPort[Ports / QueryInspector]
+  Inspector --> Metrics
   NetHTTP[Explicit Net::HTTP instance wrapper] --> Facade
   Rails --> Cache[Core / CacheNormalizer]
   Application --> Dependencies[Application / DependencyReporter]
@@ -53,7 +56,7 @@ Rails timings become immutable `TelemetryEvent` values. `CaptureTelemetry` appli
 
 Sidekiq client middleware writes a versioned, allowlisted trace/request context beside the job's public arguments. Server middleware restores a job scope, limits arguments and tags, emits a job observation, and routes a failure through the existing notice pipeline before re-raising it. Sidekiq retains queue, retry, thread, and connection lifecycle ownership.
 
-Version 0.7 routes request, query, and job observations through `ApmAggregator`. `SqlNormalizer` removes values before grouping, while `MetricAggregate` owns fixed numerical statistics. Aggregates and per-trace query trackers are bounded and mutex-protected. Threshold or lifecycle drains create `metric_batch` telemetry that passes through the existing sanitizer and delivery pipeline. No APM-specific thread is created.
+Version 0.7 routes request, query, and job observations through `ApmAggregator`. `SqlNormalizer` removes values before grouping, `SqlQueryAnalyzer` derives bounded access evidence, and `MetricAggregate` owns fixed numerical statistics, approximate percentiles, severities, diagnostics, and one representative analysis. Active trace trackers survive group drains, expire by TTL, and expose loss counters. `ActiveRecordQueryInspector` is an optional Rails adapter behind `Ports::QueryInspector`; it reads public index metadata and allowlisted PostgreSQL/MySQL statistics/plans without `ANALYZE` or DDL. Threshold or lifecycle drains create `metric_batch` telemetry that passes through the existing sanitizer and delivery pipeline. No APM-specific thread is created.
 
 Version 0.8 prepends a wrapper only to each explicitly selected `Net::HTTP` object. The wrapper records bounded outcome metadata and feeds the existing APM aggregator; it does not modify `Net::HTTP` globally. `CacheNormalizer` turns public Rails cache notifications into bounded metadata before delivery. `DependencyReporter` reads already loaded runtime metadata once per agent under a mutex and queues it as a separate event.
 

data/docs/compatibility.md

@@ -1,6 +1,6 @@
 # Compatibility
 
-Chronos Ruby 1.0 is the stable legacy line. Technical compatibility does not make an end-of-life Ruby, Rails, Rack, or Sidekiq release secure.
+Chronos Ruby 1.1 is the current stable legacy line. Technical compatibility does not make an end-of-life Ruby, Rails, Rack, or Sidekiq release secure. The planned Ruby 2.7/Rails 6 transitional matrix remains deferred until it has dedicated CI and a real application gate.
 
 ## Core and Rack
 
@@ -33,11 +33,11 @@ Chronos Ruby 1.0 is the stable legacy line. Technical compatibility does not mak
 
 Active Job uses the public `serialize`, `deserialize`, and `perform_now` extension points with a bounded namespaced field. Support follows the validated Rails pairs above. Adapters that bypass these hooks require their own evidence.
 
-The release workflow repeats every supported pair before publishing. The green candidate evidence that permitted the 1.0 promotion is recorded in [Version 1.0 readiness](release-1.0-readiness.md).
+The release workflow repeats every supported pair before publishing. Historical 1.0 evidence remains in [Version 1.0 readiness](release-1.0-readiness.md); the 1.1 candidate is recorded in [Version 1.1 readiness](release-1.1-readiness.md).
 
 Status meanings:
 
 - Supported: every mandatory compatibility gate for the exact pair passes.
-- Best effort: intended to work but missing a complete gate; no 1.0 pair is advertised this way.
+- Best effort: intended to work but missing a complete gate; no 1.1 pair is advertised this way.
 - Deprecated: still tested while removal is planned.
-- Unsupported: outside the tested 1.0 contract.
+- Unsupported: outside the tested 1.1 contract.

data/docs/configuration.md

@@ -63,6 +63,16 @@
 | `apm_long_transaction_threshold_ms` | Optional | `1000.0` | Transaction-labelled SQL duration that produces a signal |
 | `apm_n_plus_one_threshold` | Optional | `5` | Repeated fingerprint count producing one possible-N+1 signal; minimum 2 |
 | `apm_histogram_buckets` | Optional | Fixed millisecond boundaries | Increasing positive duration boundaries; at most 19 plus `+Inf` |
+| `apm_trace_ttl_seconds` | Optional | `60.0` | Maximum idle time retained for an incomplete trace or transaction tracker |
+| `apm_query_analysis_enabled` | Optional | `true` | Analyzes bounded normalized SELECT shapes and emits informational/index-candidate diagnostics |
+| `apm_query_analysis_max_queries` | Optional | `100` | Maximum normalized fingerprints analyzed and cached per subscriber; range 1–500 |
+| `apm_query_inspection_enabled` | Optional | `false` | Opts in to read-only comparison with ActiveRecord index metadata |
+| `apm_query_statistics_enabled` | Optional | `false` | Adds adapter-specific estimated table-row statistics; requires query inspection |
+| `apm_query_plan_enabled` | Optional | `false` | Adds allowlisted `EXPLAIN` evidence for eligible SELECTs; never uses `ANALYZE` |
+| `apm_query_inspection_min_duration_ms` | Optional | `500.0` | Minimum observed query duration before an opt-in database inspection |
+| `apm_query_inspection_max_queries` | Optional | `20` | Maximum unique fingerprints inspected per subscriber; range 1–100 |
+| `apm_transaction_tracking_enabled` | Optional | `true` | Measures bounded outer transaction elapsed time by notification connection |
+| `apm_transaction_max_connections` | Optional | `100` | Maximum concurrently tracked transaction connections; range 1–500 |
 | `external_http_enabled` | Optional | `false` | Allows explicit per-instance outbound `Net::HTTP` instrumentation |
 | `external_http_trace_headers` | Optional | `true` | Propagates Chronos trace/request headers on instrumented requests |
 | `cache_key_mode` | Optional | `:none` | `:none` omits keys; `:sha256` emits a project-scoped key hash |
@@ -102,6 +112,17 @@ Chronos.configure do |config|
   config.apm_slow_query_threshold_ms = 500.0
   config.apm_long_transaction_threshold_ms = 1000.0
   config.apm_n_plus_one_threshold = 5
+  config.apm_trace_ttl_seconds = 60.0
+  config.apm_query_analysis_enabled = true
+  config.apm_query_analysis_max_queries = 100
+  # Database access is explicit because each inspected fingerprint adds read-only work.
+  config.apm_query_inspection_enabled = false
+  config.apm_query_statistics_enabled = false
+  config.apm_query_plan_enabled = false
+  config.apm_query_inspection_min_duration_ms = 500.0
+  config.apm_query_inspection_max_queries = 20
+  config.apm_transaction_tracking_enabled = true
+  config.apm_transaction_max_connections = 100
   config.external_http_enabled = false
   config.external_http_trace_headers = true
   config.cache_key_mode = :none

data/docs/data-collected.md

@@ -33,13 +33,19 @@ Version 0.9 emits exceptions, cache telemetry, dependency/deploy events, and agg
 | Sidekiq arguments | Collected, sanitized, and bounded | First 20 job arguments; collections/depth/strings limited |
 | Sidekiq tags | Collected and bounded | Job payload or public worker options |
 | Sidekiq trace/request IDs | Propagated when present; trace generated otherwise | Chronos job-envelope metadata |
-| APM counts, error counts/rates, duration total/min/max/average | Aggregated by default | Request, query, and job observations |
-| Fixed duration histogram and status counts | Aggregated by default | Local bounded counters |
+| APM counts, error counts/rates, duration total/min/max/average and approximate p50/p95/p99 | Aggregated by default | Request, query, and job observations plus fixed histogram |
+| Fixed duration histogram, status counts, severity counts and bounded diagnostics | Aggregated by default | Local bounded counters and classifiers |
 | Component breakdown | database/view/external_http/cache/queue/application when observable | Trace-local bounded totals |
 | Normalized SQL and SHA-256 fingerprint | Collected without comments, literals, or binds | `sql.active_record` payload |
 | SQL adapter, operation, inferred table, AR name, cache flag, role/shard | Collected when exposed | Public notification payload and connection feature detection |
 | Slow SQL source frame | Collected only for threshold-selected slow queries | Bounded application call frame |
 | APM diagnostic signals | Heuristic counters | Local threshold and repetition detection |
+| SELECT tables and equality/range/join/order columns; index candidates | Collected by default from normalized SQL; bounded | Local static query analyzer |
+| Existing index names/columns/uniqueness | Disabled by default; read-only opt-in | Public ActiveRecord schema metadata |
+| Estimated table rows | Disabled by default; read-only opt-in | PostgreSQL `pg_class` or MySQL `information_schema` |
+| Allowlisted plan node type/table/index/estimated rows/cost | Disabled by default; `EXPLAIN` without `ANALYZE` | Local database planner |
+| Complete outer transaction approximate duration | Collected by default with bounded state | BEGIN/COMMIT/ROLLBACK notifications keyed by local connection identity |
+| Trace tracking loss/expiration counters | Aggregated by default | Local bounded tracker lifecycle |
 | External HTTP host, method, status, duration, timeout, connection-error flag, error class | Disabled by default; per-instance opt-in | Instrumented `Net::HTTP` object |
 | Chronos trace/request headers | Propagated when available | Current execution context |
 | Cache operation, backend, namespace, hit/miss, duration | Collected; key/value omitted | ActiveSupport cache notifications |
@@ -50,7 +56,7 @@ Version 0.9 emits exceptions, cache telemetry, dependency/deploy events, and agg
 | Deploy environment, revision, version, repository, actor, deploy ID, service, region, instance | Explicit synchronous deploy API | Application/deployment integration arguments |
 | Integration verification ID, fixed test marker, synthetic exception class/message, and receipt correlation | Only when `Chronos.verify_integration` or its Rake task is invoked | Locally generated bounded values |
 
-The gem never collects request bodies, response bodies, raw query strings, cookies, HTTP authorization headers, environment variables in bulk, Git state, source code, raw SQL, SQL bind values, database rows, raw cache keys/values, mail bodies/recipients, Active Job arguments, gem paths, or lockfile contents. Active Job IDs, Sidekiq JIDs/arguments, loaded gem names/versions, and deploy fields are documented integration data.
+The gem never transmits request bodies, response bodies, raw query strings, cookies, HTTP authorization headers, environment variables in bulk, Git state, source code, raw SQL, SQL bind values, database rows, plan predicates, raw cache keys/values, mail bodies/recipients, Active Job arguments, gem paths, or lockfile contents. Opt-in plan inspection temporarily supplies the already observed local SELECT to `EXPLAIN` without `ANALYZE` and discards it. Active Job IDs, Sidekiq JIDs/arguments, loaded gem names/versions, and deploy fields are documented integration data.
 
 APM dimensions never include user ID, job ID, raw URL, exception message, bind value, or cache key. Normalized routes replace common numeric/UUID segments. Normalized SQL can retain schema, table, and column identifiers; review those identifiers as part of the privacy audit.
 

data/docs/examples/plain-ruby.md

@@ -29,6 +29,12 @@ For network-free per-instance outbound HTTP instrumentation, run:
 bundle _1.17.3_ exec ruby examples/plain-ruby/external_http.rb
 ```
 
+For a network-free normalized-query/index diagnostic example, run:
+
+```bash
+bundle _1.17.3_ exec ruby examples/plain-ruby/query_analysis.rb
+```
+
 For a network-free deploy event with complete release correlation, run:
 
 ```bash

data/docs/modules/apm-aggregation.md

@@ -4,13 +4,13 @@ Version `0.8.0.pre.1` aggregates request, SQL, job, and explicitly instrumented
 
 ## Request metrics
 
-Request groups use normalized route and HTTP method. Status codes are counted inside the group so error rate can be calculated without making status part of an unbounded key. Each metric contains count, error count/rate, total, minimum, maximum, average, fixed histogram buckets, and component breakdown. Percentiles remain server-side because retaining every duration locally would violate the memory boundary.
+Request groups use normalized route and HTTP method. Status codes are counted inside the group so error rate can be calculated without making status part of an unbounded key. Each metric contains count, error count/rate, total, minimum, maximum, average, fixed histogram buckets, approximate p50/p95/p99 upper bounds, severity counts, bounded diagnostics, and component breakdown. The SaaS may calculate more precise percentiles from merged histograms; the agent never retains raw duration arrays.
 
 Rack records request metrics for non-Rails applications. Rails controller notifications and Rack share `record_event_once`, so the same request is counted only once. Controller notification data wins when available because its route is more precise.
 
 ## SQL metrics and signals
 
-`Chronos::Core::SqlNormalizer` removes block/line comments, quoted literal values, numeric values, booleans, nulls, and repeated `IN` values before producing a SHA-256 fingerprint. Binds are never read. Query dimensions can contain adapter, operation, inferred table, bounded normalized query, fingerprint, Active Record operation name, cache flag, connection role/shard, and a bounded source frame for slow sampled queries.
+`Chronos::Core::SqlNormalizer` removes block/line comments, quoted literal values, numeric values, booleans, nulls, and repeated `IN` values before producing a SHA-256 fingerprint. Binds are never read. `SqlQueryAnalyzer` extracts bounded SELECT access columns. The optional `ActiveRecordQueryInspector` compares existing indexes and adds allowlisted statistics/plans without retaining raw SQL. Query dimensions can contain adapter, operation, inferred table, bounded normalized query, fingerprint, Active Record operation name, cache flag, connection role/shard, and a bounded source frame for slow sampled queries.
 
 Local signals are intentionally heuristic:
 
@@ -18,7 +18,8 @@ Local signals are intentionally heuristic:
 - `repeated_query` after the same fingerprint appears again in one trace;
 - `possible_n_plus_one` once when the configured repetition threshold is reached;
 - `long_transaction` for transaction-labelled SQL over its threshold;
-- `connection_error` and `deadlock` from bounded exception class names.
+- `connection_error`, query/pool/lock timeout, constraint violation, and `deadlock` from bounded exception class names;
+- index candidate/coverage and sequential-scan evidence from bounded query analysis.
 
 The SaaS must confirm and correlate these signals. They are not proof of an N+1, deadlock, or application defect.
 
@@ -29,9 +30,11 @@ The SaaS must confirm and correlate these signals. They are not proof of an N+1,
 - at most `apm_max_queries_per_request` fingerprints per trace;
 - at most 19 configured histogram boundaries plus `+Inf`;
 - at most `apm_batch_size` groups per payload, with a hard maximum of 50;
-- trackers are removed when their request completes and all remaining trackers are cleared on aggregate drain.
+- trackers are removed when their request completes or their idle TTL expires; aggregate drain preserves active trackers;
+- at most 20 diagnostics and one representative bounded query analysis per metric group;
+- at most `apm_query_inspection_max_queries` database inspections per Rails subscriber.
 
-New groups beyond capacity are dropped and counted in `dropped_groups`. Existing groups continue accumulating. The state is process-local and is lost on restart.
+New groups beyond capacity are dropped and counted in `dropped_groups`. Tracking loss is reported through `dropped_trace_trackers`, `expired_trace_trackers`, and `dropped_query_fingerprints`. Existing groups continue accumulating. The state is process-local and is lost on restart.
 
 ## Breakdown
 
@@ -51,6 +54,16 @@ Chronos.configure do |config|
   config.apm_long_transaction_threshold_ms = 1000.0
   config.apm_n_plus_one_threshold = 5
   config.apm_histogram_buckets = [5.0, 10.0, 25.0, 50.0, 100.0, 250.0, 500.0, 1000.0]
+  config.apm_trace_ttl_seconds = 60.0
+  config.apm_query_analysis_enabled = true
+  config.apm_query_analysis_max_queries = 100
+  config.apm_query_inspection_enabled = false
+  config.apm_query_statistics_enabled = false
+  config.apm_query_plan_enabled = false
+  config.apm_query_inspection_min_duration_ms = 500.0
+  config.apm_query_inspection_max_queries = 20
+  config.apm_transaction_tracking_enabled = true
+  config.apm_transaction_max_connections = 100
 end
 ```
 

data/docs/modules/sidekiq-legacy.md

@@ -4,7 +4,7 @@ Version `0.6.0.pre.1` starts the legacy jobs line with optional Sidekiq 4 and 5
 
 ```ruby
 gem "sidekiq", "~> 5.0"
-gem "chronos-ruby", "~> 1.0.0", :require => "chronos/sidekiq"
+gem "chronos-ruby", "~> 1.1.0", :require => "chronos/sidekiq"
 ```
 
 `chronos/sidekiq` installs middleware through the public `configure_client` and `configure_server` APIs. It does nothing when Sidekiq is unavailable, and the core gem never requires Sidekiq. Installation adds no Chronos thread or Redis/database connection per job; delivery continues through the agent's existing fixed worker pool.

data/docs/modules/sql-monitoring.md

@@ -1,22 +1,76 @@
 # Monitoramento SQL
 
-## Problema e limite
+## Problema e limites
 
-O monitoramento SQL mede operação, tabela e duração sem transmitir SQL bruto ou binds. Sinais locais de lentidão, repetição, possível N+1, transação longa, conexão e deadlock são diagnósticos heurísticos.
+O monitoramento SQL mede padrões de acesso e duração sem transmitir SQL bruto ou binds. Ele identifica query lenta/repetida, possível N+1, transação longa, famílias de erro e candidatos a índice. Recomendações são evidências heurísticas: a gem não cria índices, não executa DDL, não usa `EXPLAIN ANALYZE` e não substitui revisão do DBA.
 
 ## Fluxo e classes
 
-`Rails::NotificationsSubscriber` extrai somente campos permitidos. `Core::SqlNormalizer` remove comentários e literais, limita identificadores e calcula fingerprint SHA-256. `ApmAggregator` mantém grupos e fingerprints por trace com capacidades fixas, então drena lotes pelo pipeline comum.
+```mermaid
+flowchart LR
+  AS[sql.active_record] --> N[SqlNormalizer]
+  N --> A[SqlQueryAnalyzer]
+  A --> M[ApmAggregator]
+  I[ActiveRecordQueryInspector opt-in] -->|índices, estatística, EXPLAIN allowlisted| A
+  M --> B[metric_batch sanitizado]
+```
+
+`Rails::NotificationsSubscriber` extrai campos permitidos. `Core::SqlNormalizer` remove comentários e literais, limita identificadores e calcula fingerprint SHA-256. `Core::SqlQueryAnalyzer` analisa somente o `SELECT` normalizado, extrai tabelas e colunas de igualdade, faixa, join e ordenação e produz candidatos limitados. `Rails::ActiveRecordQueryInspector` implementa a porta `Ports::QueryInspector` e, quando habilitado, compara o candidato com índices existentes, lê estimativa de linhas e obtém plano sem executar a consulta.
+
+O inspector envia somente nomes limitados de tabela/índice/coluna, estimativa de linhas e nós de plano allowlisted: tipo, tabela, índice, custo e linhas estimadas. Predicados, filtros, valores, SQL original e mensagens de erro são descartados. Falhas viram apenas classe limitada em um diagnóstico `error`.
+
+`Application::ApmAggregator` agrega no grupo da query:
+
+- `severity_counts`: `error`, `warning`, `info` e `suggestion`;
+- `diagnostics`: até 20 diagnósticos estáveis com código, categoria, evidência e contagem;
+- `query_analysis`: uma análise representativa, preferindo a observação com inspeção mais rica;
+- `signals`: contadores compatíveis de slow query, repetição, N+1, transação e erros;
+- duração total/mínima/máxima/média, histograma e p50/p95/p99 aproximados.
+
+## Severidades
+
+| Severidade | Exemplos |
+|---|---|
+| `error` | exceção SQL, conexão, pool/statement/lock timeout, deadlock, constraint e falha da inspeção |
+| `warning` | query lenta, transação longa, possível N+1 e sequential scan observado |
+| `info` | padrão normalizado analisado, query repetida e índice existente que cobre o padrão |
+| `suggestion` | candidato de índice e uso de eager/batch loading para possível N+1 |
+
+No projeto consumidor, cada item de `diagnostics` pode ser persistido como informação associada à métrica usando `code`, `severity`, `category`, `message`, `recommendation`, `evidence` e `count`. `code + severity + evidence.table + evidence.columns` forma a identidade agregada atual. O consumidor deve usar `severity` para apresentação e ordenação, não inferir severidade pelo texto. Campos desconhecidos devem ser preservados ou ignorados para manter compatibilidade aditiva.
 
-## Extensão, riscos e exemplo
+Um candidato permanece `unverified` até o catálogo ser consultado. Ele se torna `covered` quando um índice possui o prefixo observado ou `missing` quando índices foram lidos e nenhum cobre esse prefixo. Seletividade, custo de escrita e distribuição de dados ainda precisam ser avaliados antes de qualquer migração.
 
-Thresholds podem ser configurados, mas dimensões de alta cardinalidade não devem ser adicionadas. Nomes de schema, tabela e coluna ainda podem revelar domínio e precisam de avaliação LGPD.
+## Configuração segura
 
 ```ruby
 Chronos.configure do |config|
   config.apm_slow_query_threshold_ms = 500.0
   config.apm_n_plus_one_threshold = 5
+  config.apm_trace_ttl_seconds = 60.0
+  config.apm_query_analysis_enabled = true
+  config.apm_query_analysis_max_queries = 100
+
+  # Opt-in por adicionar consultas de somente leitura ao banco.
+  config.apm_query_inspection_enabled = true
+  config.apm_query_statistics_enabled = true
+  config.apm_query_plan_enabled = true
+  config.apm_query_inspection_min_duration_ms = 500.0
+  config.apm_query_inspection_max_queries = 20
 end
 ```
 
-Veja `spec/unit/core/sql_normalizer_spec.rb`, `spec/unit/application/apm_aggregator_spec.rb` e `spec/integration/rails_telemetry_delivery_spec.rb`.
+A análise normalizada é ativada por padrão, não consulta o banco e é calculada uma vez por fingerprint até o limite do cache. Inspeção, estatísticas e plano são desativados por padrão. Cada fingerprint é inspecionado no máximo uma vez por subscriber até o limite configurado; uma inspeção posterior pode enriquecer a análise estática já armazenada. PostgreSQL usa `pg_class` e `EXPLAIN (FORMAT JSON)`; MySQL/Trilogy usa `information_schema` e `EXPLAIN`. Adapters não reconhecidos ainda recebem análise estática e índices caso exponham `connection.indexes`.
+
+## Transações e N+1
+
+O subscriber mede o intervalo aproximado entre os callbacks de `BEGIN`/`START TRANSACTION` e `COMMIT`/`ROLLBACK`, por identidade local da conexão. Savepoints não encerram a transação externa. Estados ociosos expiram e conexões rastreadas são limitadas. O valor não inclui o tempo gasto antes do callback de `BEGIN` nem depois do callback final.
+
+Possível N+1 exige `SELECT` não cacheado, mesmo fingerprint, mesmo trace e repetição até o threshold. A sugestão recomenda eager loading ou carregamento em lote, mas o consumidor deve confirmar a semântica antes da alteração.
+
+## Riscos e extensão
+
+`EXPLAIN` ainda usa planner, conexão e locks leves de catálogo; por isso é opt-in e selecionado por duração. Não existe timeout portátil entre os adapters legacy, então habilite primeiro em staging e monitore o orçamento. Nomes de schema/tabela/coluna/índice podem revelar o domínio e precisam de avaliação LGPD.
+
+Um inspector alternativo pode implementar `call(raw_sql, query, options)` e retornar `indexes`, `statistics`, `plan` e `errors` nos limites do contrato. Ele deve ser somente leitura e nunca devolver valores ou mensagens livres.
+
+Os testes principais são `spec/unit/core/sql_query_analyzer_spec.rb`, `spec/unit/rails/active_record_query_inspector_spec.rb`, `spec/unit/application/apm_aggregator_spec.rb` e `spec/integration/rails_telemetry_delivery_spec.rb`. O exemplo executável está em `examples/plain-ruby/query_analysis.rb`.

data/docs/modules/telemetry-events.md

@@ -6,6 +6,6 @@ Telemetry has the same `schema_version`, event ID, timestamps, project, environm
 
 `Chronos.record_event` is the narrow integration entry point. Application code should prefer documented higher-level APIs; its payload is allowlisted by each bundled integration and then sanitized. Remote configuration can reduce or disable any locally enabled telemetry type but cannot enable a type excluded by local configuration.
 
-Version 0.8 aggregates request, query, job, and enabled external HTTP observations into `metric_batch` events by default. Cache remains an individual event while contributing to an existing traced request breakdown. Dependencies use one separate event per agent. Set `apm_enabled = false` only when individual legacy telemetry is required for diagnostics. Percentiles remain server-side; see [Essential APM aggregation](apm-aggregation.md).
+Version 0.8 aggregates request, query, job, and enabled external HTTP observations into `metric_batch` events by default. Cache remains an individual event while contributing to an existing traced request breakdown. Dependencies use one separate event per agent. Set `apm_enabled = false` only when individual legacy telemetry is required for diagnostics. The agent emits histogram-derived approximate p50/p95/p99 while the SaaS may calculate more precise merged values; see [Essential APM aggregation](apm-aggregation.md).
 
 Version 0.9 delivers deploy telemetry synchronously because deployment commands are short-lived. Every telemetry and exception envelope contains the fixed correlation fields documented in [Deploy tracking and release correlation](deploy-tracking.md).

data/docs/performance.md

@@ -1,6 +1,6 @@
 # Performance
 
-Performance is a functional requirement, but version 1.0 makes no unverified speed claim.
+Performance is a functional requirement, but version 1.1 makes no unverified speed claim.
 
 Current controls:
 
@@ -18,9 +18,11 @@ Current controls:
 - shutdown and flush have caller-controlled timeouts;
 - request context and breadcrumbs have fixed structural and byte limits;
 - Rack middleware never consumes request or response bodies.
-- Rails subscribers copy only small allowlisted field sets and never copy raw SQL or job arguments.
+- Rails subscribers copy only small allowlisted field sets and never deliver raw SQL or job arguments.
 - Sidekiq middleware creates no per-job thread or connection and bounds arguments, collections, nesting, strings, and tags before telemetry capture.
 - APM group, trace, query-fingerprint, histogram, and batch counts are fixed; no APM timer thread is created.
+- active trace trackers survive aggregate drains but expire after `apm_trace_ttl_seconds`; query inspections and transaction connections have independent fixed caps;
+- normalized query analysis is bounded and database inspection is disabled by default; opt-in index/statistics/plan inspection adds database round trips only once per selected fingerprint;
 - outbound HTTP instrumentation uses two clock reads and bounded metadata without body/header traversal;
 - cache normalization is bounded and SHA-256 runs only when explicitly enabled;
 - dependency inventory runs at most once per agent and is capped at 200 loaded specs.
@@ -29,7 +31,21 @@ Current controls:
 
 Run the scripts under `benchmarks/` and record Ruby version, operating system, CPU, warmup, iteration count, median, and dispersion before publishing results. `benchmarks/filtering.rb` measures privacy filtering, `benchmarks/retry_backlog.rb` measures fixed-memory outage behavior, `benchmarks/request_overhead.rb` compares Rack-protocol calls, and `benchmarks/rails_notifications.rb` isolates subscriber normalization overhead.
 
-## Version 1.0.0 release gates
+`benchmarks/query_analysis.rb` compares normalization alone with normalization plus bounded static analysis. It deliberately excludes database inspection because catalog and planner cost must be measured against the actual adapter, schema, statistics, and database host before production enablement.
+
+```bash
+ITERATIONS=100000 WARMUP=5000 bundle exec ruby benchmarks/query_analysis.rb
+```
+
+## Version 1.1.0 release gates
+
+Version 1.1 adds a release-gate benchmark for normalized SQL analysis. Static analysis is calculated once per fingerprint and cached under `apm_query_analysis_max_queries`; database inspection remains disabled in the benchmark because its cost depends on the actual adapter, schema, statistics, network, and database host.
+
+The tag workflow runs query analysis with 1,000 warmup and 10,000 measured iterations, then repeats the existing Rack comparison and 500-event fake-endpoint privacy/load gate. Local preparation evidence is recorded in [Version 1.1 readiness](release-1.1-readiness.md). Results are environment-specific and are not a cross-runtime performance promise.
+
+The local Ruby 2.2.10 preparation run measured 453.981 µs per normalization, 594.862 µs for the first static analysis of a fingerprint, 43.946 µs median incremental Rack work, and 500/500 fake-endpoint deliveries at 378.15 events/s. Static analysis is cached; the 594.862 µs value is not paid for every repeated fingerprint.
+
+## Historical version 1.0.0 release gates
 
 `benchmarks/comparative.rb` compares the same successful Rack fixture without and with Chronos instrumentation. It performs configurable warmup, at least three samples, and reports median plus median absolute deviation. `benchmarks/fake_endpoint_load.rb` sends asynchronous exception events to a local TCP endpoint, verifies the v1 schema marker, ensures the secret key is absent from every payload, and fails on loss, rejection, invalid payload, or timeout.