chronos-ruby 0.9.0.pre.4 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 84266b3c93fc92c15268d44e3625762f471c9cf99fa0523b6f5d883f846906e4
-  data.tar.gz: bf3d2c641bbb7f117a1c9c76519fa756057f72108d899cb64d86e2eeff305423
+  metadata.gz: 0127def72275a2d4c08314040c04e34a9606fed13982d84b06c465dee7be4cf6
+  data.tar.gz: 99f272314517e6a525223ce86964b70fcdfce717eb0e434b9c77e275031913b7
 SHA512:
-  metadata.gz: 9b54a3aef38f706677794b39740558586d9c69f083a3c2b3f2dc6ea20e3b60f2fe84765eb61a44fe2f230a03c03dcb27047cdd7a1853b14fc805fcb914d7cfb8
-  data.tar.gz: 2f915f461e658f93269d35e52f6d728ff32ef90a4a6ac765a6b92194a1fc53b06ca5350b2bc34c8d84197bf2263d523ead9a62ada46edbd9ae46363d3de27e05
+  metadata.gz: 93b37af1a5b51284a6c6de1c19e12de18ac23b04bfa4a04f33b7fce5cb611ec6f940d4ec2508c8a2b8d72f91e9a2a9a812a3b48d72f60dfefd642fb7cf3fe138
+  data.tar.gz: 4c653acb6d7aa90d534a7d496568fca64fb9ba9bce9039c6ca68fad71c1b5aef3f4e5de541a3f3d0f6064f08653359bcc2afc30e3a2d82c910942f0c1e103d4a

data/CHANGELOG.md

@@ -4,6 +4,42 @@ All notable changes are documented here. The project follows Semantic Versioning
 
 ## [Unreleased]
 
+## [1.1.0] - 2026-08-05
+
+### Added
+
+- bounded normalized SELECT analysis with access columns, index candidates, existing-index comparison, optional table statistics, and allowlisted non-executing query plans;
+- structured query diagnostics and severity counts for errors, warnings, information, and suggestions, including actionable N+1 and index guidance;
+- approximate p50/p95/p99 metrics, complete outer-transaction timing, expanded adapter error families, and trace/fingerprint loss counters;
+- explicit low-risk defaults and bounded opt-in configuration for database index/statistics/plan inspection.
+
+### Changed
+
+- aggregate drains preserve active trace trackers until request completion or idle TTL instead of discarding incomplete correlation;
+- possible N+1 now requires a non-cached SELECT, and query analysis sent to consumers prefers inspected evidence over an earlier static-only observation.
+
+### Security
+
+- query inspection never uses `EXPLAIN ANALYZE`, never executes DDL, omits raw SQL/binds/predicates/messages, and retains only bounded schema and planner fields.
+
+## [1.0.0] - 2026-07-29
+
+### Added
+
+- stable legacy release gates for Ruby 2.2.10 through 2.6.10, Rails 4.2/5.2, Sidekiq 4/5, documentation, repeatable comparison, and fake-endpoint load validation;
+- the remaining mandatory module documents and ADRs for feature detection, context storage, sampling, and future OpenTelemetry interoperability.
+
+### Changed
+
+- promoted the reviewed public API and protocol v1 implementation from `0.9.0.pre.4` to `1.0.0`;
+- release publishing now accepts `v1.*` tags and cannot publish until every legacy compatibility and release-readiness job succeeds;
+- compatibility status is now `Supported` only for the exact runtime/framework combinations covered by green release gates.
+
+### Security
+
+- stable artifacts continue to use RubyGems Trusted Publishing, SHA-256 checksums, SPDX SBOMs, strict payload privacy contracts, and dependency auditing;
+- package signing remains deferred until a trusted signing-key lifecycle is available.
+
 ## [0.9.0.pre.4] - 2026-07-22
 
 ### Added

data/README.md

@@ -1,73 +1,73 @@
 # Chronos Ruby
 
-Chronos Ruby is the framework-independent client for sending Ruby application errors and bounded telemetry to Chronos. Version 0.9 adds synchronous deploy tracking and bounded release correlation across every event.
+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.
 
-## What the gem collects
+## O que a gem coleta
 
-Version 0.9 can collect:
+A versão 1.1 pode coletar:
 
-- exception class, message, structured backtrace, and chained causes;
-- timestamp, severity, tags, and an optional fingerprint;
-- application-supplied context, parameters, session, and user fields;
-- Ruby version, engine, platform, process ID, opaque thread ID, and hostname;
-- application version, environment, and service name.
-- Rack method, normalized route, status, duration, request ID, host, query-free path, optional user agent, controller/action, response size, trace ID, and already-parsed parameters when the middleware is used;
-- bounded breadcrumbs explicitly supplied by the application or integration.
-- release, revision, deploy ID, environment, service, region, and instance correlation;
-- explicit bounded deployment metadata supplied through the public API or integration.
+- classe, mensagem, backtrace estruturado e causas encadeadas da exceção;
+- timestamp, severidade, tags e fingerprint opcional;
+- contexto, parâmetros, sessão e usuário fornecidos pela aplicação;
+- versão, engine e plataforma Ruby, PID, thread opaca e hostname;
+- ambiente, serviço, versão da aplicação, release, revision, deploy ID, região e instância;
+- método, rota normalizada, status, duração e breakdown de requests Rack/Rails;
+- SQL normalizado sem literais/binds e sinais heurísticos de desempenho;
+- jobs Sidekiq/Active Job, cache, HTTP externo explicitamente instrumentado e dependências carregadas;
+- breadcrumbs limitados fornecidos pela aplicação ou por integrações.
 
-See [Data collected](docs/data-collected.md) for the complete field table.
+Veja a tabela completa em [Dados coletados](docs/data-collected.md).
 
-## What is not collected by default
+## O que não é coletado por padrão
 
-Chronos Ruby does not inspect environment variables, request/response bodies, cookies, Authorization headers, source code, database contents, lockfiles, or gem paths. Dependency reporting reads only already loaded gem names and versions once per agent. Application-supplied fields are recursively sanitized, but applications should still avoid sending unnecessary personal, health, financial, or authentication data.
+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.
 
-## Supported Ruby and Rails versions
+## Versões Ruby e Rails suportadas
 
-Version 0.x targets Ruby 2.2.10 through Ruby 2.6. Version 0.5 provides best-effort Rails 4.2 through 5.2 integration through public framework APIs and feature detection. All supported combinations must pass dedicated CI before being listed as supported.
+A versão 1.1.0 suporta Ruby puro e Rack em Ruby 2.2.10, 2.3.8, 2.4.10, 2.5.9 e 2.6.10. As combinações Rails validadas são Rails 4.2 com Ruby 2.2.10/2.3.8 e Rails 5.2 com Ruby 2.5.9/2.6.10. Sidekiq 4.2.10 com Ruby 2.2.10 e Sidekiq 5.2.10 com Ruby 2.5.9 também possuem gates dedicados. Ruby 2.7/Rails 6 não é declarado nesta release porque ainda não possui aplicação e matriz completas.
 
-See [Compatibility](docs/compatibility.md).
+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).
 
-## Plain Ruby installation
+## Instalação em Ruby puro
 
-The current public build is a pre-release. Add its exact version to the application's `Gemfile`:
+Obrigatório: adicione a versão estável ao `Gemfile`.
 
 ```ruby
-gem "chronos-ruby", "0.9.0.pre.4"
+gem "chronos-ruby", "~> 1.1.0"
 ```
 
-Install with a Bundler version compatible with the application. For the oldest supported runtime:
+Em runtimes antigos, use Bundler compatível:
 
 ```bash
 gem install bundler -v 1.17.3
 bundle _1.17.3_ install
 ```
 
-Without Bundler:
+Sem Bundler:
 
 ```bash
-gem install chronos-ruby --pre
+gem install chronos-ruby -v 1.1.0
 ```
 
-## Rails installation
+## Instalação em Rails
 
-Version 0.5 exposes Rails support explicitly, keeping Rails and ActiveSupport out of plain Ruby applications:
+Obrigatório: carregue a integração Rails explicitamente para manter Rails/ActiveSupport fora de aplicações Ruby puras.
 
 ```ruby
-gem "chronos-ruby", "0.9.0.pre.4", :require => "chronos/rails"
+gem "chronos-ruby", "~> 1.1.0", :require => "chronos/rails"
 ```
 
-Generate the initializer with:
+Gere o initializer:
 
 ```bash
 rails generate chronos:install
 ```
 
-The Railtie installs the Rack middleware and notification subscribers idempotently. Automatic integration is disabled in test and console by default and can be controlled with `rails_enabled`, `rails_capture_in_test`, `rails_capture_in_console`, and `rails_capture_user_agent`. See [Rails 4.2 and 5.2 integration](docs/modules/rails-legacy.md).
+A Versão 0.5 introduziu Railtie, middleware e subscribers idempotentes por APIs públicas e feature detection. A coleta automática fica desativada em test e console por padrão. Veja [Rails legado](docs/modules/rails-legacy.md).
 
-## Minimum configuration
+## Configuração mínima
 
-`project_id`, `project_key`, and an HTTPS `host` are required while the agent is enabled:
+Obrigatório quando o agente está habilitado: `project_id`, `project_key` e `host` HTTPS. Recomendado: definir ambiente e serviço explicitamente.
 
 ```ruby
 require "chronos"
@@ -82,43 +82,28 @@ Chronos.configure do |config|
 end
 ```
 
-HTTPS verification is enabled by default. HTTP requires explicitly setting `ssl_verify = false` and should only be used with a local test server.
-
-## Verify the Chronos integration
-
-After configuring the application, Rails projects can verify credentials and end-to-end ingestion with:
+TLS é verificado por padrão. HTTP exige `ssl_verify = false` explicitamente e deve ser limitado a endpoints locais de teste. Depois de configurar, valide credenciais e ingestão:
 
 ```bash
 bundle exec rake chronos:verify_integration
 ```
 
-The task sends one synthetic exception identified as an integration verification and prints one JSON object. It exits with status `0` only when Chronos confirms valid credentials and receipt of the correlated event; configuration, authentication, inactive-project, network, protocol, rate-limit, and receiver failures exit nonzero with safe guidance.
-
-Plain Ruby Rakefiles can install the same task explicitly after loading their configuration:
+O task envia uma exceção sintética identificada e só retorna código `0` após uma resposta v1 correlacionada. Em Ruby puro, instale o task com `require "chronos/rake_tasks"` e `Chronos::RakeTasks.install`; por código, use `Chronos.verify_integration`. Veja [Verificação da integração](docs/modules/integration-verification.md).
 
-```ruby
-require "chronos"
-# Chronos.configure { |config| ... }
-require "chronos/rake_tasks"
-Chronos::RakeTasks.install
-```
+## Captura automática
 
-Ruby code may call `result = Chronos.verify_integration`, inspect `result.success?`, and serialize `result.to_h` or `result.to_json`. The result contains only bounded contract fields; it never exposes `project_key`, raw server responses, stack traces, source paths, or receiver internals. See [Integration verification](docs/modules/integration-verification.md).
-
-## Automatic capture
-
-Rack applications can capture unhandled exceptions automatically and preserve the application error semantics:
+Opcional em Rack: instale o middleware. Ele notifica exceções não tratadas, preserva a mesma exceção para a aplicação e não consome bodies.
 
 ```ruby
 use Chronos::Integrations::Rack::Middleware,
     :include_user_agent => false
 ```
 
-The middleware notifies asynchronously and re-raises the same exception. It never reads the request body, raw query string, cookies, authorization headers, or response body. See [Rack integration and context](docs/modules/rack-context.md).
+Em Rails, o Railtie instala middleware e subscribers uma única vez. Veja [Monitoramento de requests](docs/modules/request-monitoring.md).
 
-## Manual capture
+## Captura manual
 
-Asynchronous capture is recommended for application code:
+Recomendado no fluxo da aplicação: captura assíncrona.
 
 ```ruby
 begin
@@ -129,27 +114,27 @@ rescue StandardError => error
 end
 ```
 
-Synchronous capture waits for the HTTP result and is useful in scripts or controlled shutdown paths:
+Opcional para scripts e shutdown controlado: captura síncrona.
 
 ```ruby
 delivered = Chronos.notify_sync(RuntimeError.new("import failed"))
 ```
 
-Both methods return `false` instead of allowing an internal agent error to escape.
+Falhas internas retornam `false` e não escapam para o fluxo principal.
 
-## User context
+## Contexto de usuário
 
-User data is opt-in and must contain only values your application is allowed to send:
+Contexto de usuário é opt-in. Envie somente campos necessários e autorizados:
 
 ```ruby
 Chronos.notify(error, :user => {"id" => "customer-42", "role" => "operator"})
 ```
 
-Version 0.4 sanitizes this context before delivery and before it can enter retry storage. Data minimization remains the application's responsibility.
+O valor é limitado e sanitizado, mas a minimização continua sendo responsabilidade da aplicação. Veja [Contexto de execução](docs/modules/context.md).
 
 ## Breadcrumbs
 
-Breadcrumbs use a fixed circular buffer scoped to the current execution:
+Breadcrumbs formam um buffer circular delimitado no escopo atual:
 
 ```ruby
 Chronos.add_breadcrumb(
@@ -159,35 +144,25 @@ Chronos.add_breadcrumb(
 )
 ```
 
-No log, SQL, HTTP, cache, job, request body, or response body payload is collected automatically. Unknown categories become `custom`, and metadata is bounded and sanitized before queueing.
+A gem não transforma logs, SQL ou bodies em breadcrumbs brutos. Veja [Breadcrumbs](docs/modules/breadcrumbs.md).
 
-## Filters and LGPD
+## Filtros e LGPD
 
-Version 0.4 recursively redacts sensitive keys and detects Bearer tokens, JWTs, e-mail addresses, CPF, CNPJ, and valid payment-card candidates in free text. IPv4 addresses are anonymized by default. Applications can add blocklist matchers, hash selected identifiers, or install custom filters:
+A gem bloqueia chaves sensíveis e detecta Bearer tokens, JWTs, e-mails, CPF, CNPJ e candidatos válidos a cartão. IPv4 é anonimizado por padrão. Opcionalmente, amplie a blocklist, aplique hash irreversível ou filtros próprios:
 
 ```ruby
 Chronos.configure do |config|
-  # required options omitted
   config.blocklist_keys += [:medical_record, /bank_account/i]
   config.hash_keys += [:customer_id]
   config.filters << proc { |key, value| key.to_s == "internal_reference" ? "[REMOVED]" : value }
 end
 ```
 
-Sanitization runs before queueing and transport. See [Privacy and LGPD](docs/privacy-lgpd.md) for behavior, limitations, health and financial examples, and a payload audit procedure.
+Sanitização ocorre antes de fila, retry e backlog. Veja [Privacidade e LGPD](docs/privacy-lgpd.md).
 
 ## Ignore rules
 
-Entire environments can be ignored:
-
-```ruby
-Chronos.configure do |config|
-  # required options omitted
-  config.ignored_environments = ["development", "test"]
-end
-```
-
-Version `0.9.0.pre.2` adds bounded local rules after configuration:
+Ambientes inteiros podem ser ignorados na configuração. A versão `0.9.0.pre.2` introduziu regras locais limitadas, preservadas na API estável:
 
 ```ruby
 Chronos.ignore_if do |notice|
@@ -195,17 +170,14 @@ Chronos.ignore_if do |notice|
 end
 ```
 
-Rules receive an immutable normalized notice, run before serialization/queueing, and must return exactly `true` to discard. The default limit is 20 and the hard configurable maximum is 100. A failing rule is contained. See [Bounded local ignore rules](docs/modules/ignore-rules.md).
+A regra recebe um notice normalizado e imutável, e somente `true` descarta. Falhas do callback são contidas. Veja [Ignore rules](docs/modules/ignore-rules.md).
 
-## Performance monitoring
+## Monitoramento de performance
 
-Version 0.7 aggregates request, query, and job observations into bounded `metric_batch` events. Groups include count, error count/rate, total/min/max/average duration, fixed histogram buckets, status counts, and component breakdown. Percentiles are calculated in the SaaS without retaining every local duration.
-
-SQL comments and literal values are removed before a bounded normalized query and SHA-256 fingerprint are produced. Binds are never read. Slow, repeated, possible N+1, long-transaction, connection-error, and deadlock signals are heuristic and require server-side confirmation. Group count, active trace count, fingerprints per trace, histogram buckets, and batch size all have fixed limits. See [Essential APM aggregation](docs/modules/apm-aggregation.md).
+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|
-  # required connection settings omitted
   config.apm_enabled = true
   config.apm_max_groups = 200
   config.apm_flush_count = 100
@@ -213,45 +185,37 @@ 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
 ```
 
-## Sidekiq and Active Job
-
-Version `0.6.0.pre.1` adds optional Sidekiq 4/5 middleware:
-
-```ruby
-gem "sidekiq", "~> 5.0"
-gem "chronos-ruby", "0.9.0.pre.4", :require => "chronos/sidekiq"
-```
-
-The client middleware propagates only trace/request identifiers in a versioned Sidekiq-envelope field and never changes worker arguments. The server records class, queue, JID, retry count, duration, calculable queue latency, bounded arguments/tags, status, and error class. Values pass through the shared sanitizer before delivery. Failed jobs are notified once and the original exception is re-raised. See [Sidekiq 4/5 legacy integration](docs/modules/sidekiq-legacy.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).
 
-When Active Job is available, the Rails integration propagates only bounded trace/request identifiers in a namespaced serialized field without changing job arguments. It records adapter, job/provider IDs, class, queue, attempts, duration, status, and error class, and captures a supplied failure once. See [Active Job legacy integration](docs/modules/active-job.md).
+## Sidekiq e Active Job
 
-## External HTTP, cache, and dependencies
-
-Version 0.8 instruments only explicitly selected `Net::HTTP` connection objects, avoiding a global monkey patch:
+A versão `0.6.0.pre.1` introduziu middleware Sidekiq 4/5; a API estável mantém o require explícito:
 
 ```ruby
-Chronos.configure do |config|
-  # required connection settings omitted
-  config.external_http_enabled = true
-  config.external_http_trace_headers = true
-end
-
-http = Net::HTTP.new("payments.example.com", 443)
-http.use_ssl = true
-Chronos.instrument_net_http(http)
+gem "sidekiq", "~> 5.0"
+gem "chronos-ruby", "~> 1.1.0", :require => "chronos/sidekiq"
 ```
 
-The wrapper records only sanitized host, method, status, duration, timeout, connection-error flag, and error class. It propagates `X-Chronos-Trace-ID` and `X-Chronos-Request-ID` when available and never reads URL path/query, Authorization, request body, response body, or error message.
-
-Rails cache telemetry omits raw keys by default. Set `cache_key_mode = :sha256` to emit a project-scoped hash; `:none` is the default. Dependency reporting is enabled by default, reads at most 100 already loaded gem specs, and emits one independent `dependencies` event per agent. Set `dependency_reporting = false` to disable it. See [External HTTP](docs/modules/external-http.md), [Cache observability](docs/modules/cache-observability.md), and [Dependency inventory](docs/modules/dependencies.md).
+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).
 
 ## Deploy tracking
 
-Version 0.9 sends deployment metadata synchronously and adds a bounded correlation block to every event:
+A Versão 0.9 introduziu deploy síncrono e correlação fixa em todos os eventos:
 
 ```ruby
 Chronos.notify_deploy(
@@ -263,55 +227,35 @@ Chronos.notify_deploy(
 )
 ```
 
-Configure `app_version`, `revision`, `deploy_id`, `environment`, `service_name`, `region`, and `instance_id` in each newly deployed process so subsequent telemetry carries the same release identity. The gem never scans environment variables or Git automatically.
+Configure release/revision/deploy na inicialização de cada novo processo. A gem não lê Git ou variáveis automaticamente. Capistrano é opcional; Kamal e GitHub Actions usam exemplos em `examples/deploy/`. Veja [Deploys](docs/modules/deploys.md).
 
-Optional Capistrano support loads through `chronos/capistrano`. Manual, Kamal-command, and GitHub Actions examples share the explicit deploy command under `examples/deploy/`. See [Deploy tracking and release correlation](docs/modules/deploy-tracking.md).
+## Fila assíncrona
 
-## Asynchronous queue
-
-The queue has a fixed capacity and drops the newest event when full. Worker threads are created lazily after the first accepted event. The default capacity is 100 events with one worker.
+A fila tem capacidade fixa, descarta o evento mais novo quando cheia e cria workers somente após a primeira captura aceita.
 
 ```mermaid
 flowchart LR
-  E[Exception] --> N[Notice builder]
-  N --> P[Privacy sanitizer]
-  P --> S[Safe bounded serializer]
-  S --> D[Delivery pipeline]
-  D --> Q[Bounded queue]
-  Q --> W[Fixed worker pool]
-  W --> R[Retry and circuit breaker]
-  R --> H[Net::HTTP transport]
-  R --> B[Bounded memory backlog]
+  E[Exceção ou telemetria] --> N[Normalização]
+  N --> P[Sanitização]
+  P --> S[Serialização limitada]
+  S --> D[Pipeline de entrega]
+  D --> Q[Fila limitada]
+  Q --> W[Workers fixos]
+  W --> H[Net::HTTP]
+  W --> B[Backlog em memória]
 ```
 
-Use `Chronos.flush(timeout)` to wait for accepted events and `Chronos.close(timeout)` during shutdown. Workers are recreated after a process fork.
-
-## Retry and backlog
-
-The resilience layer introduced in version 0.3 retries network errors, HTTP `408`, `429`, and `5xx` responses with exponential backoff, bounded jitter, and a finite attempt count. Other `4xx` responses are permanent and are not retried. A circuit breaker pauses requests after repeated failures, preventing retry storms.
-
-After retries are exhausted, the already sanitized `SerializedEvent` may enter a fixed-capacity memory backlog. The backlog drops new items when full, is lost when the process exits, and never writes to disk. A later successful half-open probe drains backlog items as new events arrive.
-
-The SaaS may return a JSON policy in the bounded `X-Chronos-Remote-Configuration` response header. Only sampling rate, enabled event types, a lower payload limit, exact ignored fingerprints, send interval, and kill switch are accepted. Remote values cannot change the host, project credentials, TLS, local maximums, code, or regular expressions. See [Retry and backlog](docs/modules/retry-backlog.md) and [Remote configuration](docs/modules/remote-configuration.md).
+Use `Chronos.flush(timeout)` antes de encerrar e `Chronos.close(timeout)` no shutdown. Workers são recriados após fork. Veja [Fila assíncrona](docs/modules/async-queue.md).
 
-## How it works internally
+## Retry e backlog
 
-The code follows hexagonal boundaries:
+Retry cobre erros de rede, HTTP `408`, `429` e `5xx`, com backoff exponencial, jitter e tentativas limitadas. Outros `4xx` são permanentes. Circuit breaker reduz tempestades de retry.
 
-- `Chronos::Core` contains immutable notices, sanitization, and safe normalization;
-- `Chronos::Application` coordinates capture;
-- `Chronos::Application::DeliveryPipeline` owns bounded retry and remote policy;
-- `Chronos::Ports` defines delivery behavior;
-- `Chronos::Adapters` implements Net::HTTP delivery and thread-local context;
-- `Chronos::Integrations::Rack` implements optional automatic Rack capture;
-- `Chronos::Rails` implements the optional Railtie, installer, generator, and public-notification adapters;
-- `Chronos::Internal` owns bounded queueing, workers, and defensive logging.
+O backlog guarda somente eventos já sanitizados/serializados, possui capacidade fixa, vive em memória e é perdido no encerramento. Configuração remota aceita apenas sampling, tipos habilitados, limite menor de payload, fingerprints exatas, intervalo e kill switch; nunca altera host, credenciais, TLS ou executa código. Veja [Retry e backlog](docs/modules/retry-backlog.md), [Sampling](docs/modules/sampling.md) e [Configuração remota](docs/modules/remote-configuration.md).
 
-The core has no dependency on Rails, Rack, Sidekiq, or ActiveSupport. See [Architecture](docs/architecture.md).
+## Configuração por ambiente
 
-## Environment-specific configuration
-
-Configuration values are explicit; the gem never scans the process environment. Read only the variables your application chooses:
+A gem não varre o ambiente. Leia somente variáveis escolhidas pela aplicação:
 
 ```ruby
 Chronos.configure do |config|
@@ -322,102 +266,69 @@ Chronos.configure do |config|
   config.enabled = ENV["CHRONOS_ENABLED"] != "false"
   config.queue_size = 100
   config.workers = 1
-  config.timeout = 5.0
-  config.open_timeout = 2.0
   config.max_retries = 3
-  config.retry_base_interval = 0.5
-  config.retry_max_interval = 30.0
-  config.retry_jitter = 0.25
   config.backlog_size = 100
-  config.circuit_failure_threshold = 5
-  config.circuit_reset_timeout = 30.0
   config.remote_configuration = true
-  config.context_store = :thread_local
-  config.breadcrumb_capacity = 20
-  config.breadcrumb_max_bytes = 2048
   config.apm_enabled = true
-  config.apm_max_groups = 200
-  config.apm_flush_count = 100
   config.external_http_enabled = false
   config.cache_key_mode = :none
   config.dependency_reporting = true
   config.app_version = ENV["APP_VERSION"]
   config.revision = ENV["GIT_SHA"]
   config.deploy_id = ENV["DEPLOY_ID"]
-  config.region = ENV["REGION"]
-  config.instance_id = ENV["INSTANCE_ID"]
 end
 ```
 
-All options are documented in [Configuration](docs/configuration.md).
+Todas as opções, defaults e limites estão em [Configuração](docs/configuration.md).
 
 ## Troubleshooting
 
-Configuration errors are raised during `Chronos.configure`. Capture and delivery errors are contained and optionally reported to the configured logger. Verify credentials, HTTPS certificates, timeouts, and `Chronos.flush` results. See [Troubleshooting](docs/troubleshooting.md).
+Erros de configuração são levantados durante `Chronos.configure`; falhas de captura/entrega são contidas e podem ir ao logger seguro. Confirme TLS, credenciais, timeouts e retorno de `flush`. Consulte [Troubleshooting](docs/troubleshooting.md).
 
 ## Benchmark
 
-Run the version 0.9 benchmarks with:
+O gate estável executa comparação Rack repetível e carga contra endpoint fake:
 
 ```bash
-bundle _1.17.3_ exec ruby benchmarks/capture_exception.rb
-bundle _1.17.3_ exec ruby benchmarks/serialization.rb
-bundle _1.17.3_ exec ruby benchmarks/filtering.rb
-bundle _1.17.3_ exec ruby benchmarks/queue.rb
-bundle _1.17.3_ exec ruby benchmarks/retry_backlog.rb
-bundle _1.17.3_ exec ruby benchmarks/request_overhead.rb
-bundle _1.17.3_ exec ruby benchmarks/rails_notifications.rb
-bundle _1.17.3_ exec ruby benchmarks/sidekiq_middleware.rb
-bundle _1.17.3_ exec ruby benchmarks/apm_aggregation.rb
-bundle _1.17.3_ exec ruby benchmarks/external_http.rb
-bundle _1.17.3_ exec ruby benchmarks/correlation.rb
+ITERATIONS=50000 WARMUP=5000 SAMPLES=7 bundle _1.17.3_ exec ruby benchmarks/comparative.rb
+ITERATIONS=500 bundle _1.17.3_ exec ruby benchmarks/fake_endpoint_load.rb
 ```
 
-Results depend on runtime, hardware, and payload. No performance comparison is claimed until repeatable measurements are published.
+Resultados dependem de runtime e hardware. Não há alegação genérica de superioridade; registre CPU, SO, Ruby, commit, warmup, amostras, mediana e dispersão. Outros benchmarks ficam em `benchmarks/` e estão descritos em [Performance](docs/performance.md).
 
-## Migration from Airbrake
+## Migração do Airbrake
 
-An Airbrake migration guide will be added before the legacy 1.0 release. Version 0.9 does not claim API compatibility or automatic replacement.
+Migre por etapas e mantenha os dois agentes juntos somente durante a validação, evitando duplicidade prolongada. Callbacks e notices não são API-compatíveis e devem ser traduzidos/testados explicitamente. Consulte o [guia de migração do Airbrake](docs/migration-from-airbrake.md).
 
-## Local development
+## Desenvolvimento local
 
-Clone the repository, install Bundler 1.17.3, and run setup:
+Instale Bundler 1.17.3 e as dependências:
 
 ```bash
 gem install bundler -v 1.17.3
 bin/setup
 ```
 
-Open an interactive console:
-
-```bash
-bin/console
-```
-
-Install the current source locally:
-
-```bash
-bundle _1.17.3_ exec rake install
-```
+Use `bin/console` para inspeção e `bundle _1.17.3_ exec rake install` para instalar a fonte localmente. A arquitetura hexagonal está descrita em [Arquitetura](docs/architecture.md).
 
-## Tests
+## Testes
 
-Run the complete suite on the current Ruby:
+Execute suíte e lint no runtime atual:
 
 ```bash
 bundle _1.17.3_ exec rake
 ```
 
-The legacy CI matrix covers Ruby 2.2.10, 2.3.8, 2.4.10, 2.5.9, and 2.6.10. Network integration tests use a local fake HTTP server.
+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.
 
-## Contributing
+## Contribuição
 
-Open an issue before introducing a new public API or dependency. Every public class requires YARD documentation, tests, module documentation, and compatibility evidence. See [CONTRIBUTING.md](CONTRIBUTING.md).
+Abra uma issue antes de adicionar API pública ou dependência. Classes públicas precisam de YARD, testes, documentação de módulo e evidência de compatibilidade. Veja [CONTRIBUTING.md](CONTRIBUTING.md).
 
-## Security
+## Segurança
 
-Never include credentials in event context or logs. Report vulnerabilities privately according to [SECURITY.md](SECURITY.md). Ruby 2.2 through 2.6 are end-of-life; Chronos provides technical compatibility, not runtime security maintenance.
+Nunca inclua credenciais no contexto. Releases usam Trusted Publishing, checksum SHA-256 e SBOM; dependências passam por auditoria. Reporte vulnerabilidades pelo canal privado de [SECURITY.md](SECURITY.md).
 
-## License
+## Licença
 
-Chronos Ruby is distributed under the terms of the MIT License. See [LICENSE.txt](LICENSE.txt).
+Chronos Ruby é distribuída sob a licença MIT. Veja [LICENSE.txt](LICENSE.txt).