chronos-ruby 1.0.0 → 1.2.0.pre.1

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.
 

data/docs/privacy-lgpd.md

@@ -15,7 +15,8 @@ Version 0.9 sanitizes exception, framework telemetry, dependency/deploy inventor
 | Unknown Ruby objects | Represented by class name without calling application serialization |
 | Request/response bodies, raw query strings, cookies, authorization headers, raw SQL/binds, cache values, mail bodies, environment variables | Never collected automatically |
 | Sidekiq arguments | Collected automatically, limited before sanitization, then redacted by the common policy |
-| SQL | Comments, quoted/numeric/boolean/null literals removed; binds never read; bounded identifiers remain |
+| SQL | Comments, quoted/numeric/boolean/null literals removed; binds never read; bounded identifiers remain; raw SQL is never transmitted |
+| Query inspection | Disabled by default; local `EXPLAIN` has no `ANALYZE`; only allowlisted plan/catalog metadata is retained |
 | External HTTP | Host/method/status/timing only; URL path/query, Authorization, bodies, headers, and error messages omitted |
 | Cache key | Omitted by default; optional project-scoped SHA-256 hash; cache value never read |
 | Dependencies | Bounded loaded gem names/versions and detected runtime labels; paths and lockfiles omitted |
@@ -39,16 +40,18 @@ Raw cache keys can contain user or business data and are never delivered. Option
 
 ## Rails telemetry
 
-Rails subscribers use per-notification allowlists. SQL events retain only the operation name, cached flag, and duration; cache events omit key and value; mailer events omit addresses and content; Active Job events omit job ID and arguments; view identifiers are reduced to basenames. Controller parameters are sanitized by the normal payload pipeline before queueing.
+Rails subscribers use per-notification allowlists. SQL events retain normalized value-free metadata, bounded analysis, cached flag, duration and optional allowlisted inspection evidence; cache events omit key and value; mailer events omit addresses and content; Active Job events omit arguments; view identifiers are reduced to basenames. Controller parameters are sanitized by the normal payload pipeline before queueing.
 
 ## Sidekiq jobs
 
 The optional Sidekiq middleware is the only version 0.6 integration that automatically reads job arguments. It traverses at most 20 top-level arguments, 20 items per nested collection, four levels, and 512 bytes per string. These structural limits run before the common key and content sanitizer. Trace propagation contains only trace and request identifiers. Do not place credentials or unnecessary personal, health, or financial data in job arguments; configure application-specific blocklist keys and audit representative synthetic payloads before enabling production delivery.
 
-## APM dimensions
+## APM dimensions and query inspection
 
 Metric groups deliberately exclude user IDs, JIDs, raw URLs, request parameters, bind values, exception messages, and cache keys. SQL normalization removes common literal forms and comments before fingerprinting, but retains bounded database identifiers and cannot parse every dialect. Do not encode personal or secret values in schema, table, column, SQL keyword, or operation names. Slow-query source contains a bounded file/line frame under the configured application root, not source-code contents.
 
+Static query analysis is enabled by default and processes only the normalized SQL. Index, statistics, and plan inspection are separate opt-ins. The original SELECT is used only to ask the same local connection for `EXPLAIN` without `ANALYZE`; it is never placed in telemetry. Plan predicates and arbitrary `Extra`/filter text are discarded. Only bounded node type, relation, index, estimated rows, cost and schema-index definitions cross the sanitizer. These identifiers can still disclose business vocabulary, so production enablement requires a representative synthetic payload audit.
+
 ## Rack context and breadcrumbs
 
 The Rack middleware copies only bounded operational fields and parameter hashes that another component already parsed. It does not read `rack.input` or copy `QUERY_STRING`. User context is opt-in through `chronos.user`, and user agent collection is disabled unless the middleware option enables it.

data/docs/protocol-v1.md

@@ -2,6 +2,6 @@
 
 The schemas under `contracts/` are the source of truth for protocol v1. Version `1.0.0` freezes `schema_version: "1.0"` and treats every required field, enum value, privacy exclusion, and maximum as a compatibility contract.
 
-Compatible changes may add optional bounded fields or new event types accepted by the server. Removing or renaming a field, changing its type/meaning, weakening a bound, or making an optional field required needs a new protocol major schema. Authentication remains outside the JSON payload. Contract tests and `script/verify_docs` must pass before a release.
+Compatible changes may add optional bounded fields or new event types accepted by the server. APM v1 metrics can now carry tracking-loss metadata, approximate percentiles, severity counts, at most 20 structured diagnostics, and one bounded query-analysis object. They remain optional in the schema for compatibility even though this agent version emits them. Consumers should persist diagnostic `code` and `severity` as stable model fields and treat English messages/recommendations as display fallback text. Removing or renaming a field, changing its type/meaning, weakening a bound, or adding a required field without coordinated consumer rollout needs a new protocol major schema. Authentication remains outside the JSON payload. Contract tests and `script/verify_docs` must pass before a release.
 
 The explicit integration check uses the normal exception envelope and identifies itself through `context.integration_verification`. Its receiver acknowledgement is governed separately by [`integration-verification-response-v1.schema.json`](../contracts/integration-verification-response-v1.schema.json). A successful HTTP status without a complete, correlated response is not proof of authentication or ingestion.

data/docs/release-1.1-readiness.md

@@ -0,0 +1,51 @@
+# Version 1.1 release evidence
+
+Version `1.1.0` is a backward-compatible minor release of the stable legacy line. It adds bounded SQL diagnostics, optional read-only database inspection, richer query metrics, and safer trace correlation while keeping `schema_version: "1.0"` and the previously validated Ruby/Rails/Sidekiq support matrix.
+
+## Scope decision
+
+The long-term roadmap associates a transitional 1.x line with Ruby 2.7 and Rails 6. This release does not claim that support: no runtime/framework pair becomes `Supported` without dedicated CI, a real example application, fake-endpoint delivery, shutdown, privacy, and integration evidence. Version 1.1.0 is therefore a SemVer-compatible capability release for the current legacy package; the transitional matrix remains future work.
+
+## Candidate evidence
+
+Local release preparation on 2026-08-05 used Ruby 2.2.10 x86_64 on macOS. The tag workflow must reproduce every supported Linux/container gate before RubyGems publication.
+
+| Gate | Local candidate evidence | Tag enforcement |
+|---|---|---|
+| Unit, integration, contract and documentation | 195 examples, zero failures | every legacy core job plus publish `rake` |
+| Ruby style and legacy syntax | 204 Ruby files, zero RuboCop offenses on Ruby 2.2.10 | every legacy core job plus publish `rake` |
+| Query analysis privacy | PostgreSQL/MySQL allowlist specs and final serialized-payload integration test | contract/unit/integration suite |
+| Normalized-query benchmark | 10,000 iterations with warmup; database inspection disabled | `release-readiness` |
+| Legacy Ruby 2.2.10–2.6.10 | locally exercised on 2.2.10; complete result belongs to tag CI | `legacy-core` matrix |
+| Rails 4.2/5.2 applications | no new support claim; complete result belongs to tag CI | `legacy-rails` matrix |
+| Sidekiq 4/5 applications | no new support claim; complete result belongs to tag CI | `legacy-sidekiq` matrix |
+| Repeatable Rack comparison | executed locally with warmup, five samples, median and MAD | `release-readiness` |
+| Fake endpoint load/privacy | 500-event local gate with complete receipt and no secret leakage | `release-readiness` |
+| Package metadata | gem version, contents, checksum and SPDX SBOM verified locally | publish job |
+| Trusted publication | no local push performed | protected RubyGems environment and OIDC |
+
+## Local measurements
+
+The 2026-08-05 Ruby 2.2.10 preparation run produced:
+
+| Measurement | Result |
+|---|---:|
+| SQL normalization, 10,000 iterations after 1,000 warmup | 453.981 µs/iteration |
+| First bounded static analysis, same fixture | 594.862 µs/iteration |
+| Direct Rack median, 10,000 calls × 5 samples | 0.015203 s; MAD 0.000351 s |
+| Chronos Rack median, same fixture | 0.454667 s; MAD 0.014678 s |
+| Median incremental Rack work | 43.946 µs/request |
+| Fake endpoint | 500/500 received, 1.322240 s, 378.15 events/s |
+
+The database-inspection path was not benchmarked because a synthetic adapter would not represent catalog/planner cost. Production opt-in requires an adapter/schema-specific staging measurement.
+
+## Release controls
+
+- the tag must be exactly `v1.1.0` and match `Chronos::VERSION`;
+- `publish` depends on the legacy core, Rails, Sidekiq, and release-readiness jobs;
+- query inspection is disabled by default and never uses `EXPLAIN ANALYZE` or DDL;
+- all new APM v1 properties remain optional in the schema for older consumers;
+- artifacts contain the gem, SHA-256 checksum, and SPDX SBOM;
+- a failed, skipped, or incomplete supported-matrix job blocks publication.
+
+The local artifact is evidence only. Publication must happen through the tag workflow, not with a manual `gem push`.

data/docs/security-review.md

@@ -1,6 +1,6 @@
-# Security review for 1.0.0
+# Security review for 1.1.0
 
-Review date: 2026-07-29. Scope: capture, serialization, transport, integration verification, remote configuration, framework/job integrations, stable release workflow, examples, and fixtures.
+Review date: 2026-08-05. Scope: capture, serialization, transport, query analysis/inspection, integration verification, remote configuration, framework/job integrations, stable release workflow, examples, and fixtures.
 
 Verified by contracts and implementation review:
 
@@ -13,5 +13,9 @@ Verified by contracts and implementation review:
 - Active Job propagation uses a namespaced v1 field containing only bounded trace/request identifiers and does not alter job arguments;
 - fixture privacy is enforced by contract tests and dependency advisories are checked by the security workflow.
 - integration verification accepts only a strict correlated response and never exposes raw receiver bodies, credentials, stack traces, paths, SQL, or internal architecture.
+- normalized query analysis is bounded by fingerprint; raw SQL and binds are never transmitted;
+- database inspection is disabled by default, read-only, limited by duration/fingerprint, and never executes `EXPLAIN ANALYZE` or DDL;
+- plan predicates, arbitrary planner text, database rows, and exception messages are excluded; only allowlisted schema/planner fields and error classes remain;
+- new APM properties are additive/optional under protocol v1, and diagnostics/evidence pass through the common sanitizer and serializer limits.
 
-Residual risks: supported Ruby/Rails versions are end-of-life; in-memory backlog is lost at exit; application filters/ignore rules execute application code; project identifiers and documented job IDs may be personal data in some deployments; package signing is not enabled because no trusted certificate/key lifecycle exists. Stable artifacts use a protected environment, Trusted Publishing, SHA-256 checksums and SPDX SBOMs until signing can be operated safely.
+Residual risks: supported Ruby/Rails versions are end-of-life; opt-in catalog and planner calls add database work and lack one portable timeout across legacy adapters; static index recommendations remain heuristic; in-memory backlog is lost at exit; application filters/ignore rules execute application code; project/schema identifiers and documented job IDs may be personal data in some deployments; package signing is not enabled because no trusted certificate/key lifecycle exists. Stable artifacts use a protected environment, Trusted Publishing, SHA-256 checksums and SPDX SBOMs until signing can be operated safely.

data/docs/troubleshooting.md

@@ -74,6 +74,12 @@ This is intentional. The normalizer removes common literal forms and never reads
 
 Local detectors emit bounded heuristics, not confirmed diagnoses. Repetition can be legitimate and exception class names can be adapter-specific. Confirm the trace in the SaaS and application logs before changing application behavior.
 
+## Index recommendation is inaccurate or inspection reports an error
+
+An `index_candidate` uses normalized SQL only and has low confidence. `missing_index_candidate` means the observed index prefix was absent from the bounded catalog snapshot; it does not evaluate selectivity, write cost, partial/expression indexes, storage, or production data distribution. Validate with a DBA and the actual workload before creating a migration.
+
+Inspection is disabled by default. Enable `apm_query_inspection_enabled` first in staging, keep the fingerprint and duration limits small, then opt into statistics or plans. `query_inspection_failed` contains only the exception class. Unsupported adapters, prepared placeholders, permissions, planner timeouts, or unavailable catalog APIs can cause it. The gem never retries an inspection or falls back to `EXPLAIN ANALYZE`.
+
 ## Context appears missing
 
 The legacy context store is thread-local. A new application-created thread does not inherit context. Establish a new `Chronos.with_context` scope inside that thread, and issue manual notification before the scope exits. For Rack capture, supply user and explicit parameters through the documented environment keys.

data/lib/chronos/adapters/fiber_local_context_store.rb

@@ -0,0 +1,57 @@
+module Chronos
+  module Adapters
+    # Stores execution context on the current Fiber when Ruby exposes Fiber storage.
+    #
+    # @responsibility Isolate context between concurrent fibers and restore nested scopes.
+    # @motivation Rails 7 applications increasingly multiplex work on one thread.
+    # @limits Fiber storage is not propagated automatically to newly-created fibers.
+    # @collaborators ContextStore port and Agent composition root.
+    # @thread_safety Each fiber owns its value and may be used from concurrent threads.
+    # @compatibility Ruby 3.2+ Fiber storage; falls back to thread-local storage otherwise.
+    # @example
+    #   store.with_context(:request_id => "r1") { store.get }
+    # @errors Previous context is restored even when the block raises.
+    # @performance Constant-time storage operations with a bounded hash merge.
+    class FiberLocalContextStore
+      def initialize(fallback = ThreadLocalContextStore.new)
+        @key = "chronos_context_#{object_id}".to_sym
+        @fallback = fallback
+      end
+
+      def get
+        supported? ? (Fiber[@key] || {}) : @fallback.get
+      end
+
+      def set(context)
+        raise ArgumentError, "context must be a Hash" unless context.is_a?(Hash)
+
+        supported? ? Fiber[@key] = context : @fallback.set(context)
+      end
+
+      def clear
+        supported? ? Fiber[@key] = nil : @fallback.clear
+        nil
+      end
+
+      def with_context(context)
+        previous = get
+        set(previous.merge(valid_context(context)))
+        yield
+      ensure
+        previous && !previous.empty? ? set(previous) : clear
+      end
+
+      private
+
+      def supported?
+        Fiber.respond_to?(:[]) && Fiber.respond_to?(:[]=)
+      end
+
+      def valid_context(context)
+        raise ArgumentError, "context must be a Hash" unless context.is_a?(Hash)
+
+        context
+      end
+    end
+  end
+end

data/lib/chronos/agent.rb

@@ -11,7 +11,7 @@ module Chronos
   #   agent.notify(RuntimeError.new("failed"))
   # @errors Capture errors return false; explicit construction requires valid configuration.
   # @performance No worker threads are created until the first asynchronous event.
-  class Agent
+  class Agent # rubocop:disable Metrics/ClassLength
     DEFAULT_FLUSH_TIMEOUT = 5.0
 
     attr_reader :config
@@ -133,12 +133,23 @@ module Chronos
       {
         :enabled => @config.apm_enabled,
         :slow_query_threshold_ms => @config.apm_slow_query_threshold_ms,
-        :root_directory => @config.root_directory
+        :root_directory => @config.root_directory,
+        :query_analysis_enabled => @config.apm_query_analysis_enabled,
+        :query_analysis_max_queries => @config.apm_query_analysis_max_queries,
+        :query_inspection_enabled => @config.apm_query_inspection_enabled,
+        :query_statistics_enabled => @config.apm_query_statistics_enabled,
+        :query_plan_enabled => @config.apm_query_plan_enabled,
+        :query_inspection_min_duration_ms => @config.apm_query_inspection_min_duration_ms,
+        :query_inspection_max_queries => @config.apm_query_inspection_max_queries,
+        :transaction_tracking_enabled => @config.apm_transaction_tracking_enabled,
+        :transaction_max_connections => @config.apm_transaction_max_connections,
+        :transaction_ttl_seconds => @config.apm_trace_ttl_seconds
       }
     end
 
     def external_http_integration_options
-      {:enabled => @config.external_http_enabled, :trace_headers => @config.external_http_trace_headers}
+      {:enabled => @config.external_http_enabled, :trace_headers => @config.external_http_trace_headers,
+       :w3c_trace_context => @config.w3c_trace_context}
     end
 
     def cache_integration_options
@@ -155,6 +166,10 @@ module Chronos
         "request_id" => nested["request_id"] || nested[:request_id] ||
                         request["request_id"] || request[:request_id]
       }
+      if @config.opentelemetry_bridge
+        otel = Integrations::OpenTelemetry.current_context
+        values = otel.merge(values.delete_if { |_key, value| value.to_s.empty? })
+      end
       values.delete_if { |_key, value| value.to_s.empty? }
     rescue StandardError
       {}
@@ -227,6 +242,7 @@ module Chronos
 
     def build_context_store(strategy)
       return Adapters::ThreadLocalContextStore.new if strategy == :thread_local
+      return Adapters::FiberLocalContextStore.new if strategy == :fiber_local
 
       strategy
     end