chronos-ruby 0.9.0.pre.4 → 1.1.0

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-007-feature-detection.md

@@ -0,0 +1,25 @@
+# ADR-007 — Feature detection nas integrações
+
+## Status
+
+Aceito para 1.0.
+
+## Contexto
+
+Rails 4.2/5.2, Active Job e Sidekiq 4/5 expõem conjuntos diferentes de constantes e hooks. Comparar apenas números de versão cria falsos positivos em instalações parciais.
+
+## Decisão
+
+Integrações opcionais verificam a presença da biblioteca e das APIs públicas necessárias antes de instalar middleware, subscribers ou extensões. A instalação é idempotente e não exige Zeitwerk.
+
+## Alternativas
+
+Branches por versão e uso de APIs privadas foram rejeitados por fragilidade e custo de manutenção.
+
+## Consequências positivas
+
+O núcleo permanece carregável em Ruby puro e combinações validadas compartilham adapters menores.
+
+## Consequências negativas
+
+Cada caminho detectado exige contrato e aplicação de exemplo; uma biblioteca que imite parcialmente a API pode precisar de tratamento dedicado.

data/docs/adr/ADR-008-context-store.md

@@ -0,0 +1,25 @@
+# ADR-008 — Context store por runtime
+
+## Status
+
+Aceito para 1.0 legado.
+
+## Contexto
+
+Requests e jobs concorrentes não podem compartilhar usuário, parâmetros, breadcrumbs ou trace ID, mas Ruby 2.2 não oferece uma estratégia fiber-local moderna uniforme.
+
+## Decisão
+
+Definir uma porta de context store e usar armazenamento thread-local na linha 0.x/1.0 legado. Todo escopo restaura o valor anterior e limpa em `ensure`; somente IDs permitidos atravessam processos.
+
+## Alternativas
+
+Estado global foi rejeitado por vazamento entre execuções. Fiber local foi adiado para a linha moderna.
+
+## Consequências positivas
+
+O isolamento é testável e o núcleo não depende da primitiva concreta.
+
+## Consequências negativas
+
+Threads e fibers criadas pela aplicação exigem propagação explícita; adapters futuros precisam preservar a mesma porta.

data/docs/adr/ADR-009-sampling.md

@@ -0,0 +1,25 @@
+# ADR-009 — Sampling limitado localmente
+
+## Status
+
+Aceito para 1.0.
+
+## Contexto
+
+O agente precisa controlar volume durante carga alta e aceitar redução remota sem permitir expansão inesperada da coleta.
+
+## Decisão
+
+Usar `sampling_rate` local como teto. Configuração remota pode somente reduzir a taxa, desabilitar tipos ou ativar kill switch. As opções são allowlisted, limitadas e nunca incluem código/regex.
+
+## Alternativas
+
+Sampling exclusivamente no servidor desperdiça transporte. Sampling remoto sem teto local foi rejeitado por privacidade e previsibilidade.
+
+## Consequências positivas
+
+O operador conserva controle e a decisão ocorre antes de HTTP/retry.
+
+## Consequências negativas
+
+Sampling uniforme pode perder eventos raros; análises devem considerar a taxa efetiva.

data/docs/adr/ADR-010-opentelemetry-interoperability.md

@@ -0,0 +1,25 @@
+# ADR-010 — Interoperabilidade futura com OpenTelemetry
+
+## Status
+
+Adiado; limite aceito para 1.0 legado.
+
+## Contexto
+
+O Chronos precisa correlacionar trace/request sem duplicar SDKs ou impor dependências modernas a Ruby 2.2–2.6.
+
+## 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.
+
+## Alternativas
+
+Adicionar o SDK como dependência obrigatória foi rejeitado por incompatibilidade e overhead. Copiar spans completos foi rejeitado por cardinalidade e privacidade.
+
+## Consequências positivas
+
+O protocolo v1 permanece estável e aplicações legadas não recebem novas dependências.
+
+## 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.

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-018-pre-1.0-hardening.md

@@ -1,9 +1,13 @@
 # ADR-018: Pre-1.0 hardening gates
 
+## Status
+
+Concluído pela versão 1.0.0.
+
 ## Decision
 
-Keep the release at `0.9.0.pre.2` while any mandatory 1.0 evidence remains external or incomplete. Add bounded local ignore rules, Active Job envelope propagation, real Sidekiq compatibility jobs, repeatable comparative/load benchmarks, and explicit release/security policies.
+Keep the release in prerelease while any mandatory 1.0 evidence remains external or incomplete. Promote only after bounded local ignore rules, Active Job envelope propagation, real Sidekiq compatibility jobs, repeatable comparative/load benchmarks, and explicit release/security policies are present and green.
 
 ## Consequences
 
-The stable API is not promised before the full legacy matrix passes. Active Job gains one namespaced serialized field without changing arguments. Application callbacks remain bounded in count but their execution cost belongs to the application. Package checksums are used until a trusted signing lifecycle is available.
+The complete candidate matrix passed before the 1.0 promotion. Active Job has one namespaced serialized field without changing arguments. Application callbacks remain bounded in count but their execution cost belongs to the application. Trusted Publishing, package checksums and SBOMs are used until a trusted signing lifecycle is available.

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,36 +1,43 @@
 # Compatibility
 
-Chronos Ruby 0.x is the legacy line. Technical compatibility does not make an end-of-life Ruby or Rails 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.
 
-| Ruby | Rails integration | Status | Evidence |
-|---|---|---|---|
-| 2.2.10 | Rails 4.2 | Best effort | Core CI, Rails 4.2 example, dedicated smoke gate |
-| 2.3.8 | Rails 4.2 / 5.0 | Best effort | Core CI and feature-detection contract; dedicated app gate incomplete |
-| 2.4.10 | Rails 4.2 / 5.0 | Best effort | Core CI and feature-detection contract; dedicated app gate incomplete |
-| 2.5.9 | Rails 5.2 | Best effort | Core CI, Rails 5.2 example, dedicated smoke gate |
-| 2.6.10 | Rails 5.2 | Best effort | Core CI and feature-detection contract; dedicated app gate incomplete |
-| 2.7 and newer | None in 0.x | Unsupported | Belongs to transitional or modern lines |
-
-| Ruby | Sidekiq integration | Status | Evidence |
-|---|---|---|---|
-| 2.2.10 | Sidekiq 4.2.10 | Best effort | Unit/integration contracts and dedicated real-gem Docker job |
-| 2.5.9 | Sidekiq 5.2.10 | Best effort | Unit/integration contracts and dedicated real-gem Docker job |
+## Core and Rack
 
-Version 0.5 includes Rails 4.2 and 5.2 applications plus a dedicated matrix, but this document conservatively keeps the combinations at `Best effort` until all release-gate evidence, including fake-server payload validation, is green. Rails 5.0 uses the same feature-detected public APIs but does not yet have its own example application.
+| 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 |
 
-Version `0.9.0.pre.2` adds dedicated Sidekiq 4.2.10 and 5.2.10 real-gem jobs. Status remains `Best effort` until both external jobs pass on the release candidate.
+## Rails
 
-Active Job propagation uses the standard `serialize`, `deserialize`, and `perform_now` extension points with a namespaced bounded field. Rails 4.2/5.2 example jobs and unit contracts provide evidence; the complete external matrix must still pass before stable support is declared.
+| 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 |
 
-Version `0.7.0.pre.1` keeps the same Ruby/Rails matrix and implements APM aggregation without modern concurrency or SQL-parser dependencies. Its compatibility remains `Best effort` until request/SQL/job aggregate payloads pass the dedicated fake-server gates for every listed runtime.
+## 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 |
 
-Version `0.8.0.pre.1` uses per-object `Module#prepend`, legacy `Net::HTTP`, standard-library SHA-256, and loaded-spec feature detection. It adds no runtime dependency and keeps the same matrix. Outbound HTTP, cache, and dependency gates must pass every listed runtime before support is promoted.
+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.
 
-Version `0.9.0.pre.1` adds only standard-library URI/SecureRandom processing, bounded hashes, and the existing synchronous delivery path. Capistrano is optional and feature-detected; Kamal and GitHub Actions integrations are commands/examples. The Ruby/Rails matrix remains unchanged and `Best effort` until deploy/correlation payload gates pass every listed runtime.
+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: the complete required compatibility gate passes.
-- Best effort: intended to work, but the complete gate has not passed yet.
+- Supported: every mandatory compatibility gate for the exact pair passes.
+- 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 this release line.
+- 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/deprecation-policy.md

@@ -4,4 +4,4 @@ After `1.0.0`, a public API scheduled for removal remains available for at least
 
 Warnings are emitted at most once per process through the configured safe logger and must not include application payloads. Security fixes, behavior that can expose secrets, and upstream runtime incompatibilities may require faster action; the security advisory and changelog must explain the exception. Ruby/Rails support changes are recorded in `docs/compatibility.md` before removal.
 
-Prereleases may revise APIs without the full stable window, but every incompatible revision must remain explicit. Version `0.9.0.pre.2` introduces no removal.
+Prereleases may revise APIs without the full stable window, but every incompatible revision must remain explicit. Version `1.0.0` starts the stable deprecation window and introduces no removal.

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/migration-from-airbrake.md

@@ -1,6 +1,6 @@
 # Migration from Airbrake
 
-Version `0.9.0.pre.2` provides a staged migration path. Run both agents only long enough to compare delivery, then remove Airbrake to avoid duplicate reports and overhead.
+Version `1.0.0` provides a staged migration path. Run both agents only long enough to compare delivery, then remove Airbrake to avoid duplicate reports and overhead.
 
 | Airbrake concept | Chronos equivalent |
 |---|---|

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

@@ -0,0 +1,23 @@
+# Breadcrumbs
+
+## Problema e limite
+
+Breadcrumbs preservam uma trilha curta do fluxo que antecedeu uma falha. Não são logs, tracing completo ou armazenamento de payloads brutos.
+
+## Fluxo e classes
+
+`Chronos.add_breadcrumb` normaliza a categoria e os metadados em `Chronos::Core::Breadcrumb`. `BreadcrumbBuffer` mantém um anel de capacidade fixa no context store. O `NoticeBuilder` copia a fotografia atual; sanitizer e serializer aplicam novamente limites antes da entrega.
+
+## Extensão, riscos e exemplo
+
+Integrações podem registrar apenas categorias conhecidas e metadados de baixa cardinalidade. Mensagens e metadados continuam sendo dados da aplicação e podem conter informação pessoal se o chamador ignorar minimização.
+
+```ruby
+Chronos.add_breadcrumb(
+  :category => "custom",
+  :message => "invoice queued",
+  :metadata => {"provider" => "example"}
+)
+```
+
+Os limites e a herança por captura são testados em `spec/unit/core/breadcrumb_spec.rb`, `spec/unit/agent_spec.rb` e nos specs de Rack.

data/docs/modules/context.md

@@ -0,0 +1,21 @@
+# Contexto de execução
+
+## Problema e limite
+
+O contexto relaciona uma exceção ou métrica ao request/job atual sem criar dependência do núcleo com Rack, Rails ou Sidekiq. Ele guarda somente valores delimitados e não é um repositório de estado da aplicação.
+
+## 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`.
+
+## Extensão, riscos e exemplo
+
+Um adaptador alternativo pode ser configurado quando implementar a porta completa. Ele precisa restaurar escopos aninhados e garantir limpeza após exceções. Thread local não acompanha automaticamente fibers ou threads criadas pela aplicação; nesses casos, propague somente os identificadores permitidos.
+
+```ruby
+Chronos.with_context("trace_id" => "trace-42", "request_id" => "request-7") do
+  Chronos.notify(RuntimeError.new("failure"))
+end
+```
+
+Os contratos estão em `spec/unit/ports/context_store_spec.rb`, `spec/unit/adapters/thread_local_context_store_spec.rb` e `spec/integration/rack_middleware_concurrency_spec.rb`.

data/docs/modules/deploys.md

@@ -0,0 +1,23 @@
+# Deploys
+
+## Problema e limite
+
+Deploys criam o marco temporal usado para comparar erros e desempenho antes/depois de uma release. A gem informa o evento; reconciliação e análise pertencem ao SaaS.
+
+## Fluxo e classes
+
+`Chronos.notify_deploy` passa atributos explícitos a `Core::DeployNormalizer`, sanitiza o evento e usa entrega síncrona com idempotência. `CorrelationContext` copia release, revision, deploy ID, ambiente, serviço, região e instância para todos os envelopes. Uma entrega bem-sucedida libera um novo snapshot de dependências.
+
+## Extensão, riscos e exemplo
+
+Capistrano possui hook opcional; Kamal e GitHub Actions usam comandos documentados. A gem não lê Git nem variáveis automaticamente. O retorno `false` deve ser tratado conforme a política de deploy da aplicação.
+
+```ruby
+Chronos.notify_deploy(
+  :environment => "production",
+  :revision => ENV["GIT_SHA"],
+  :version => ENV["APP_VERSION"]
+)
+```
+
+Veja `spec/unit/core/deploy_normalizer_spec.rb`, `spec/unit/integrations/capistrano_spec.rb` e `spec/integration/deploy_delivery_spec.rb`.

data/docs/modules/job-monitoring.md

@@ -0,0 +1,22 @@
+# Monitoramento de jobs
+
+## Problema e limite
+
+Jobs precisam manter correlação entre enqueue e execução e registrar duração/falha sem abrir threads ou conexões por job. A versão 1.0 cobre Sidekiq 4/5 e Active Job disponível em Rails 4.2/5.2; Resque e Delayed Job permanecem fora do escopo estável.
+
+## Fluxo e classes
+
+O middleware Sidekiq injeta um envelope Chronos separado dos argumentos públicos. O servidor restaura contexto, mede fila/execução e deduplica exceções aninhadas. A integração Active Job usa os hooks públicos de serialização e `perform_now`. As observações seguem para `ApmAggregator` e as exceções para o notice pipeline.
+
+## Extensão, riscos e exemplo
+
+Adapters que substituem hooks públicos exigem testes próprios. Argumentos Sidekiq são limitados e sanitizados, mas a aplicação deve evitar segredos e dados pessoais desnecessários.
+
+```ruby
+require "chronos/sidekiq"
+Sidekiq.configure_server do |config|
+  config.server_middleware { |chain| chain.add Chronos::Integrations::Sidekiq::ServerMiddleware }
+end
+```
+
+Veja `spec/unit/integrations/sidekiq_spec.rb`, `spec/unit/integrations/active_job_spec.rb` e `spec/integration/sidekiq_delivery_spec.rb`.

data/docs/modules/request-monitoring.md

@@ -0,0 +1,20 @@
+# Monitoramento de requests
+
+## Problema e limite
+
+Requests Rack/Rails alimentam métricas de duração, status e breakdown com dimensões limitadas. O módulo não lê bodies, cookies, autorização ou query string bruta.
+
+## Fluxo e classes
+
+O middleware Rack cria contexto isolado e mede o request. Subscribers Rails enriquecem controller/action e evitam duplicação. `CaptureTelemetry` envia a observação a `ApmAggregator`; por padrão ela integra um `metric_batch`, e com APM desativado vira evento individual sanitizado.
+
+## Extensão, riscos e exemplo
+
+Rotas devem ser normalizadas para evitar cardinalidade por ID. Aplicações Rack podem fornecer um normalizador por meio dos campos já aceitos, sem incluir parâmetros sensíveis.
+
+```ruby
+use Chronos::Integrations::Rack::Middleware,
+    :include_user_agent => false
+```
+
+Veja `spec/integration/rack_middleware_spec.rb`, `spec/integration/rack_middleware_concurrency_spec.rb` e `spec/integration/apm_aggregation_delivery_spec.rb`.