chronos-ruby 1.0.0 → 1.2.0.pre.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3fc9daff111666fdf7309797c5f8aa81a639c8f59ea1733be48740b9aea6b247
-  data.tar.gz: a8d7cd786b233078e5516e3d1ce0c92b986d045ebd4d8c29a7d9cd80ae75fb93
+  metadata.gz: c13c2858edcb41d4b2a0bfc83049349ee13a5a9ecee873798750b4bf9f1da48c
+  data.tar.gz: a21babcc28ce763e7d867f35064735d661214724c1ed9d256e8d174a1a04c5dc
 SHA512:
-  metadata.gz: 1f60a09480aa5766676d673579ffe1b5b007d044881fc9b1f70f672c414ddf7e1a014cc63eaeee8ee6f63fa7261aa5dc92f8f9b1cc6089898ecf015d1940a83c
-  data.tar.gz: '08342c5a665004cbfa9fec52164f86e82d003b3d587bf931ae220c44ec4188c91141852e424f726f55a7b7d5dec4592190dc7cef9dc6c4e05f0eec8255bd32b4'
+  metadata.gz: 81ab0672785236e1ffaeecf0fbb5ae3187f319be349a06f724eee50dd0d20963afb74a84485267e8ea5e3a7dd37dacef15ab456783fee622bef901110b98344a
+  data.tar.gz: 835ee551ddcec646a44376dcdfc09748e12c0fa360fee62365455e6776503a0597baed504a33276059853e652f5a90458ad7ae43bb582f7647303af9940a5d1f

data/CHANGELOG.md

@@ -4,6 +4,42 @@ All notable changes are documented here. The project follows Semantic Versioning
 
 ## [Unreleased]
 
+## [1.2.0.pre.1] - 2026-08-11
+
+### Added
+
+- fiber-aware execution context with a thread-local fallback;
+- Sidekiq 7 and Rails 7 error reporter integration using public extension APIs;
+- Action Cable notification spans and a dependency-free Faraday middleware;
+- optional W3C `traceparent` propagation and an OpenTelemetry bridge that consumes the active span without installing an SDK or exporter.
+
+### Changed
+
+- the transitional runtime range is Ruby 2.7 through 3.4 and the default context strategy is `:fiber_local`;
+- Active Job and Sidekiq envelopes may propagate allowlisted span ID and trace flags in addition to trace/request IDs.
+
+### Security
+
+- W3C identifiers are syntax-validated, all-zero IDs are rejected, and Rails error reporter context is reduced to bounded allowlisted metadata.
+
+## [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 candidata 1.2.0.pre.1 inicia a linha transitional para Ruby 2.7–3.4, Rails 7.x e Sidekiq 7. Ela adiciona contexto por Fiber, Rails Error Reporter, Action Cable, Faraday, Trace Context W3C opcional e coexistência com um SDK OpenTelemetry já configurado. Use-a explicitamente em staging enquanto a matriz transitional é validada; as linhas legadas permanecem disponíveis em releases anteriores.
 
 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,21 +185,35 @@ 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
 
-A versão `0.6.0.pre.1` introduziu middleware Sidekiq 4/5; a API estável mantém o require explícito:
+A integração mantém o require explícito e suporta a API pública de middleware do Sidekiq 7:
+
+O suporte histórico começou em `0.6.0.pre.1`; aplicações em Sidekiq 4/5 devem permanecer numa release legada compatível.
 
 ```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).
+O envelope de contexto não altera argumentos públicos e contém somente IDs limitados de trace/span/request e flags. 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).
 
 ## Deploy tracking
 
@@ -307,7 +321,7 @@ Execute suíte e lint no runtime atual:
 bundle _1.17.3_ exec rake
 ```
 
-A matriz CI cobre Ruby 2.2.10–2.6.10, aplicações Rails 4.2/5.2 e Sidekiq 4/5. O workflow de release repete toda a matriz, documentação, benchmark comparativo e carga antes de publicar.
+A matriz CI cobre a linha transitional e os checks de pacote/documentação; workflows legados preservam evidência das releases anteriores.
 
 ## Contribuição
 

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-010-opentelemetry-interoperability.md

@@ -2,7 +2,7 @@
 
 ## Status
 
-Adiado; limite aceito para 1.0 legado.
+Aceito para 1.2.
 
 ## Contexto
 
@@ -10,7 +10,7 @@ O Chronos precisa correlacionar trace/request sem duplicar SDKs ou impor depend
 
 ## Decisão
 
-Manter IDs de correlação e portas independentes do fornecedor na 1.0. Não depender de OpenTelemetry nem instalar instrumentação global na linha legado. Uma ponte opcional será projetada na linha transitional/modern e deverá traduzir somente campos permitidos.
+Manter IDs de correlação e portas independentes do fornecedor. Na 1.2, a ponte opcional consulta somente o span atual de um SDK já carregado, traduz `trace_id`, `span_id` e flags, e nunca instala SDK, instrumentação ou exporter. IDs Chronos explícitos têm precedência; a presença de OTel deve ser usada pelas integrações para evitar spans paralelos equivalentes.
 
 ## Alternativas
 
@@ -22,4 +22,4 @@ O protocolo v1 permanece estável e aplicações legadas não recebem novas depe
 
 ## Consequências negativas
 
-Não há propagação automática com ecossistemas OpenTelemetry na 1.0; integrações futuras exigirão contrato e matriz próprios.
+A ponte não exporta spans OTel completos nem controla exporters; consumidores que precisam desses dados continuam responsáveis pela configuração do SDK.

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,43 +1,37 @@
 # 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.2.0.pre.1 is the first candidate of the transitional line for Rails 7 and Sidekiq 7. Combinations remain `Best effort` until their dedicated CI and real-application gates pass. Technical compatibility does not make an end-of-life Ruby, Rails, Rack, or Sidekiq release secure. Versions 1.0 and 1.1 remain the frozen legacy line.
 
 ## Core and Rack
 
 | Ruby | Status | Evidence |
 |---|---|---|
-| 2.2.10 | Supported | Full unit, integration, contract, Rack, concurrency, fork, transport, privacy, and lint gate |
-| 2.3.8 | Supported | Same dedicated Docker gate |
-| 2.4.10 | Supported | Same dedicated Docker gate |
-| 2.5.9 | Supported | Same dedicated Docker gate |
-| 2.6.10 | Supported | Same dedicated Docker gate |
-| 2.7 and newer | Unsupported in 1.x legacy | Belongs to the transitional or modern lines |
+| 2.7–3.2 | Best effort | Transitional matrix introduced in this candidate; promotion requires green CI evidence |
+| 3.3–3.4 | Best effort | Core checks run in modern CI; Rails 8-specific behavior belongs to 2.x |
+| Earlier than 2.7 | Unsupported in 1.2 | Use an appropriate frozen legacy release |
 
 ## Rails
 
 | Ruby | Rails | Status | Evidence |
 |---|---|---|---|
-| 2.2.10 | 4.2 | Supported | Real application boot, successful/error request, SQL, view, cache, Active Job, mailer, fake endpoint, flush, and shutdown |
-| 2.3.8 | 4.2 | Supported | Same dedicated application gate |
-| 2.5.9 | 5.2 | Supported | Same dedicated application gate |
-| 2.6.10 | 5.2 | Supported | Same dedicated application gate |
-| Other Ruby/Rails pairs | — | Unsupported | No complete release gate; feature detection alone is not a support claim |
+| 2.7–3.2 | 7.0–7.1 | Best effort | Real Rails applications and the complete integration gate are pending |
+| 3.1–3.4 | 7.2 | Best effort | Feature and package checks; use a validated application combination before production rollout |
+| Rails 4–6 | — | Unsupported in 1.2 | Use a matching earlier Chronos release |
 
 ## Sidekiq
 
 | Ruby | Sidekiq | Status | Evidence |
 |---|---|---|---|
-| 2.2.10 | 4.2.10 | Supported | Real-gem client/server middleware smoke with context, success/failure, and deduplication |
-| 2.5.9 | 5.2.10 | Supported | Same dedicated application gate |
-| Other Ruby/Sidekiq pairs | — | Unsupported | No complete release gate |
+| 2.7–3.4 | 7.x | Best effort | Real Sidekiq 7 smoke applications are pending |
+| Sidekiq 4–6 | — | Unsupported in 1.2 | Use a matching earlier Chronos release |
 
 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).
+Historical evidence remains in [Version 1.0 readiness](release-1.0-readiness.md) and [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

@@ -47,7 +47,7 @@
 | `sampling_rate` | Optional | `1.0` | Local upper bound for event sampling |
 | `enabled_event_types` | Optional | exception, request, query, job, cache, external_http, dependencies, deploy, metric_batch | Local allowlist for supported event envelopes |
 | `max_remote_send_interval` | Optional | `60.0` | Local upper bound for remotely requested send spacing |
-| `context_store` | Optional | `:thread_local` | `:thread_local` or an object implementing `get`, `set`, `clear`, and `with_context` |
+| `context_store` | Optional | `:fiber_local` | `:fiber_local`, `:thread_local`, or an object implementing `get`, `set`, `clear`, and `with_context` |
 | `breadcrumb_capacity` | Optional | `20` | Positive count of newest breadcrumbs retained per execution |
 | `breadcrumb_max_bytes` | Optional | `2048` | Maximum bytes per normalized breadcrumb; minimum `128` |
 | `rails_enabled` | Optional | `true` | Enables automatic Rails middleware and subscribers |
@@ -63,8 +63,20 @@
 | `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 |
+| `w3c_trace_context` | Optional | `false` | Injects a validated W3C `traceparent` header when trace and span IDs exist |
+| `opentelemetry_bridge` | Optional | `true` | Consumes the current OpenTelemetry span when an SDK is already active; installs nothing |
 | `cache_key_mode` | Optional | `:none` | `:none` omits keys; `:sha256` emits a project-scoped key hash |
 | `dependency_reporting` | Optional | `true` | Emits one bounded dependency event per configured agent |
 | `dependency_max_items` | Optional | `100` | Loaded gem entries retained in the inventory; range 1–200 |
@@ -90,7 +102,7 @@ Chronos.configure do |config|
   config.max_retries = 3
   config.backlog_size = 100
   config.circuit_failure_threshold = 5
-  config.context_store = :thread_local
+  config.context_store = :fiber_local
   config.breadcrumb_capacity = 20
   config.rails_capture_in_test = false
   config.rails_capture_in_console = false
@@ -102,8 +114,21 @@ 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.w3c_trace_context = false
+  config.opentelemetry_bridge = true
   config.cache_key_mode = :none
   config.dependency_reporting = true
   config.dependency_max_items = 100

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/context.md

@@ -6,7 +6,7 @@ O contexto relaciona uma exceção ou métrica ao request/job atual sem criar de
 
 ## Fluxo e classes
 
-`Chronos::Ports::ContextStore` define `get`, `set`, `clear` e `with_context`. Na linha legado, `Chronos::Adapters::ThreadLocalContextStore` isola o valor por thread. A fachada combina o contexto explícito com o escopo atual; o serializer sanitiza e limita tudo antes da fila. Rack limpa o escopo em `ensure`, enquanto Sidekiq e Active Job propagam apenas `trace_id` e `request_id`.
+`Chronos::Ports::ContextStore` define `get`, `set`, `clear` e `with_context`. Na linha 1.2, `Chronos::Adapters::FiberLocalContextStore` usa storage do Fiber quando disponível e volta com segurança ao adapter thread-local. A fachada combina o contexto explícito com o escopo atual; o serializer sanitiza e limita tudo antes da fila. Rack limpa o escopo em `ensure`, enquanto Sidekiq e Active Job propagam somente `trace_id`, `span_id`, `trace_flags` e `request_id`.
 
 ## Extensão, riscos e exemplo
 

data/docs/modules/external-http.md

@@ -10,6 +10,7 @@ Chronos.configure do |config|
   # connection settings omitted
   config.external_http_enabled = true
   config.external_http_trace_headers = true
+  config.w3c_trace_context = true
 end
 
 http = Net::HTTP.new("payments.example.com", 443)
@@ -18,10 +19,10 @@ Chronos.instrument_net_http(http)
 response = http.request(Net::HTTP::Get.new("/health"))
 ```
 
-The event contains a bounded lowercase host, uppercase method, response status, monotonic duration, timeout flag, connection-error flag, and error class. A request made inside a Chronos context receives `X-Chronos-Trace-ID` and `X-Chronos-Request-ID` unless the application already set those headers. Disable propagation with `external_http_trace_headers = false`.
+The event contains a bounded lowercase host, uppercase method, response status, monotonic duration, timeout flag, connection-error flag, and error class. A request made inside a Chronos context receives `X-Chronos-Trace-ID` and `X-Chronos-Request-ID` unless the application already set those headers. With `w3c_trace_context = true`, Net::HTTP and `Chronos::Integrations::FaradayMiddleware` also preserve an existing header or inject a validated `traceparent`. Disable all propagation with `external_http_trace_headers = false`.
 
 The wrapper never reads or records the path, query string, Authorization, other request headers, request body, response headers/body, or exception message. The native streaming block is forwarded and the identical HTTP exception is re-raised. Telemetry failures are contained.
 
-Successful and failed calls become bounded `external_http` APM groups keyed only by host and method. A call carrying a trace ID contributes its duration to the enclosing request's `external_http` breakdown. Faraday, HTTP.rb, Excon, and RestClient are outside this release.
+Successful and failed calls become bounded `external_http` APM groups keyed only by host and method. A call carrying a trace ID contributes its duration to the enclosing request's `external_http` breakdown. Faraday is supported through explicit middleware installation; HTTP.rb, Excon, and RestClient remain outside this release.
 
 Installation is idempotent per object. A `false` result means collection is disabled, the object is incompatible or already instrumented, or installation was contained after an internal error.