chronos-ruby 0.8.0.pre.1 → 0.9.0.pre.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 44c7cad424497d7998727de5a916594ecc3ce9dfda7580376fe4a754edd9096e
-  data.tar.gz: 3f7a64cbf5b5879e107d7102c1f72cdd2ac4c941e1640a05b6210db79cd948f9
+  metadata.gz: ba6053cbe8155fba7fa99c0adf09db9e0aa38d33314b2355c49f1760233183fe
+  data.tar.gz: 138ee6958622e5e03d24863c553066c6368459fe423731950bcfcc63bfb12e02
 SHA512:
-  metadata.gz: f62fa57bfcfec70f7172afc4c939d905aa9c7d9215960b73fa0c54406568b43b93e41b02ba22eb13b381243e06cf61a087544db00ed97ea4ce5805f84e9901e7
-  data.tar.gz: 3a66ec4e2a85f7f2e79868523fe63a493aeb598aff810dfd21b84a25dd0505e21ee66cac35a7113927a9b4b5a5c5ea2f41d25b89b452b38088c0ef3570f876bf
+  metadata.gz: 58b5255dacdb15e3df4147cceb563e247989fa8cc2e72c23e79166e51c772ffc9ba0e87120c025de5d20cff04be21a7625cafb39d9f47793f82d156bdcb5cf09
+  data.tar.gz: 981f49d6f3d12314278456338e975797c27df3f7d93217eb2a8c9df630faa6081a683159b7694e0963cd7f9fa4ed6fae5f095b697a1ea9ce1c3159f388a5b36d

data/CHANGELOG.md

@@ -12,6 +12,64 @@ All notable changes are documented here. The project follows Semantic Versioning
 - legacy CI now resolves Bundler 1.17.3 through `Gem.bin_path` on RubyGems versions that do not support the `_version_` executable selector.
 - documentation verification now reads source and Markdown files explicitly as UTF-8 on legacy container locales.
 
+## [0.9.0.pre.2] - 2026-07-21
+
+### Added
+
+- bounded startup and runtime exception ignore rules through `config.ignore_rules` and `Chronos.ignore_if`;
+- Active Job trace/request propagation without modifying public arguments, plus adapter, job/provider IDs, attempts, status, and failure telemetry;
+- real-gem Sidekiq 4.2/5.2 Docker compatibility jobs;
+- repeatable Rack comparison and fake-endpoint load gates;
+- corrected `script/test_all` so `pipefail` no longer turns installed Rubies into false skips and an empty matrix fails;
+- Airbrake migration, SemVer, deprecation, protocol stability, security review, and 1.0 readiness documentation.
+
+### Changed
+
+- version advanced to `0.9.0.pre.2` instead of `1.0.0` because the full external legacy matrix has not yet supplied zero-failure evidence;
+- Active Job identifiers are now documented collected fields and propagated context is bounded to trace/request IDs.
+
+### Fixed
+
+- the Sidekiq 5 compatibility smoke now resolves the shared Sidekiq 4/5 fixture inside `examples/` instead of the nonexistent `/app/sidekiq-4` path.
+
+### Security
+
+- local ignore rules are bounded to 100, contain callback failures, and cannot be installed remotely;
+- fake-endpoint load validation rejects payloads containing the secret authentication key;
+- package signing remains deferred until a trusted key lifecycle exists; protected publishing credentials remain required.
+
+### Known limitations
+
+- compatibility stays `Best effort` until all new and existing GitHub Actions matrix jobs pass without skips;
+- end-of-life runtimes and framework dependencies retain their upstream security risk;
+- Active Job adapters that bypass standard serialization/execution hooks need dedicated evidence;
+- comparative results are not a performance claim and must be published with controlled environment metadata.
+
+## [0.9.0.pre.1] - 2026-07-21
+
+### Added
+
+- synchronous `Chronos.notify_deploy` API with bounded environment, revision, version, repository, actor, deploy ID, service, region, and instance fields;
+- fixed bounded release/deploy correlation on every new exception and telemetry envelope;
+- explicit configuration for `revision`, `deploy_id`, `region`, and `instance_id`;
+- automatic deploy IDs and credential removal from common HTTP/SCP repository references;
+- optional idempotent Capistrano post-publish task loaded through `chronos/capistrano`;
+- manual, Kamal-command, and GitHub Actions deployment examples;
+- deploy/correlation contracts, tests, benchmark, module documentation, and ADR-017.
+
+### Changed
+
+- dependency inventory can be refreshed once after a successful deploy notification with the new release;
+- deploy events use their normalized environment/service/release values in the common envelope;
+- version advanced to `0.9.0.pre.1`.
+
+### Known limitations
+
+- `notify_deploy` does not mutate the immutable correlation of an already running agent;
+- Kamal support is command/documentation based rather than a plugin;
+- Capistrano must load its task DSL before the optional Chronos entry point;
+- deployment policy must decide whether a `false` notification result blocks publication.
+
 ## [0.8.0.pre.1] - 2026-07-20
 
 ### Added

data/README.md

@@ -1,10 +1,10 @@
 # Chronos Ruby
 
-Chronos Ruby is the framework-independent client for sending Ruby application errors and bounded telemetry to Chronos. Version 0.8 adds optional per-instance outbound `Net::HTTP` timing, privacy-safe cache identity, and one bounded dependency inventory per agent.
+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.
 
 ## What the gem collects
 
-Version 0.8 can collect:
+Version 0.9 can collect:
 
 - exception class, message, structured backtrace, and chained causes;
 - timestamp, severity, tags, and an optional fingerprint;
@@ -13,6 +13,8 @@ Version 0.8 can collect:
 - 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.
 
 See [Data collected](docs/data-collected.md) for the complete field table.
 
@@ -31,7 +33,7 @@ See [Compatibility](docs/compatibility.md).
 The current public build is a pre-release. Add its exact version to the application's `Gemfile`:
 
 ```ruby
-gem "chronos-ruby", "0.8.0.pre.1"
+gem "chronos-ruby", "0.9.0.pre.2"
 ```
 
 Install with a Bundler version compatible with the application. For the oldest supported runtime:
@@ -52,7 +54,7 @@ gem install chronos-ruby --pre
 Version 0.5 exposes Rails support explicitly, keeping Rails and ActiveSupport out of plain Ruby applications:
 
 ```ruby
-gem "chronos-ruby", "0.8.0.pre.1", :require => "chronos/rails"
+gem "chronos-ruby", "0.9.0.pre.2", :require => "chronos/rails"
 ```
 
 Generate the initializer with:
@@ -164,7 +166,15 @@ Chronos.configure do |config|
 end
 ```
 
-Local exception-specific ignore callbacks are not available in version 0.4. The server may provide a bounded list of exact fingerprints to ignore; it cannot provide regular expressions or executable rules.
+Version `0.9.0.pre.2` adds bounded local rules after configuration:
+
+```ruby
+Chronos.ignore_if do |notice|
+  notice.exception_class == "SomeExpectedError"
+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).
 
 ## Performance monitoring
 
@@ -191,12 +201,12 @@ Version `0.6.0.pre.1` adds optional Sidekiq 4/5 middleware:
 
 ```ruby
 gem "sidekiq", "~> 5.0"
-gem "chronos-ruby", "0.8.0.pre.1", :require => "chronos/sidekiq"
+gem "chronos-ruby", "0.9.0.pre.2", :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).
 
-The Rails subscriber continues to record basic Active Job class, queue, and duration. Full Active Job context propagation plus optional Resque and Delayed Job adapters are subsequent version 0.6 increments.
+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).
 
 ## External HTTP, cache, and dependencies
 
@@ -220,7 +230,21 @@ Rails cache telemetry omits raw keys by default. Set `cache_key_mode = :sha256`
 
 ## Deploy tracking
 
-Deploy notifications are not implemented in version 0.8. `app_version` is included in event service metadata and the once-per-agent dependency inventory for release correlation.
+Version 0.9 sends deployment metadata synchronously and adds a bounded correlation block to every event:
+
+```ruby
+Chronos.notify_deploy(
+  :environment => "production",
+  :revision => ENV["GIT_SHA"],
+  :version => ENV["APP_VERSION"],
+  :repository => "owner/repository",
+  :actor => ENV["DEPLOY_USER"]
+)
+```
+
+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.
+
+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).
 
 ## Asynchronous queue
 
@@ -296,6 +320,11 @@ Chronos.configure do |config|
   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
 ```
 
@@ -307,7 +336,7 @@ Configuration errors are raised during `Chronos.configure`. Capture and delivery
 
 ## Benchmark
 
-Run the version 0.8 benchmarks with:
+Run the version 0.9 benchmarks with:
 
 ```bash
 bundle _1.17.3_ exec ruby benchmarks/capture_exception.rb
@@ -320,13 +349,14 @@ 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
 ```
 
 Results depend on runtime, hardware, and payload. No performance comparison is claimed until repeatable measurements are published.
 
 ## Migration from Airbrake
 
-An Airbrake migration guide will be added before the legacy 1.0 release. Version 0.8 does not claim API compatibility or automatic replacement.
+An Airbrake migration guide will be added before the legacy 1.0 release. Version 0.9 does not claim API compatibility or automatic replacement.
 
 ## Local development
 

data/SECURITY.md

@@ -7,3 +7,5 @@ Never include live project keys, customer payloads, personal data, or production
 The Chronos 0.x line provides technical compatibility with end-of-life Ruby versions. It cannot provide security maintenance for the Ruby runtime, OpenSSL, operating system, Rails, or other dependencies used by the host application.
 
 Security fixes in the agent will be assessed for backporting to maintained Chronos version lines. No response-time commitment is made before a formal security process is published.
+
+The current prerelease review and residual risks are recorded in [docs/security-review.md](docs/security-review.md). Release publishing uses a protected GitHub environment and a scoped RubyGems key. Package signing is deferred until the project has a trusted certificate issuance, rotation, revocation, and offline-key process; do not add a private signing key to the repository or workflow secrets without that process.

data/contracts/deploy-v1.schema.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://chronos.example/schemas/deploy-v1.schema.json",
+  "title": "Chronos deploy payload v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "deploy_id", "environment", "revision", "version", "repository",
+    "actor", "service", "region", "instance"
+  ],
+  "properties": {
+    "deploy_id": {"type": "string", "minLength": 1, "maxLength": 128},
+    "environment": {"type": "string", "minLength": 1, "maxLength": 128},
+    "revision": {"type": ["string", "null"], "maxLength": 128},
+    "version": {"type": ["string", "null"], "maxLength": 128},
+    "repository": {"type": ["string", "null"], "maxLength": 512},
+    "actor": {"type": ["string", "null"], "maxLength": 128},
+    "service": {"type": ["string", "null"], "maxLength": 128},
+    "region": {"type": ["string", "null"], "maxLength": 128},
+    "instance": {"type": ["string", "null"], "maxLength": 128}
+  },
+  "anyOf": [
+    {"properties": {"revision": {"type": "string", "minLength": 1}}},
+    {"properties": {"version": {"type": "string", "minLength": 1}}}
+  ]
+}

data/contracts/event-v1.schema.json

@@ -20,7 +20,7 @@
   "properties": {
     "schema_version": {"const": "1.0"},
     "event_id": {"type": "string", "minLength": 1},
-    "event_type": {"enum": ["exception", "request", "query", "job", "cache", "external_http", "dependencies", "metric_batch"]},
+    "event_type": {"enum": ["exception", "request", "query", "job", "cache", "external_http", "dependencies", "deploy", "metric_batch"]},
     "occurred_at": {"type": "string"},
     "sent_at": {"type": "string"},
     "project_key": {"type": "string", "minLength": 1},
@@ -34,6 +34,20 @@
         "instance_id": {"type": ["string", "null"]}
       }
     },
+    "correlation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["release", "revision", "deploy_id", "environment", "service", "region", "instance"],
+      "properties": {
+        "release": {"type": ["string", "null"], "maxLength": 128},
+        "revision": {"type": ["string", "null"], "maxLength": 128},
+        "deploy_id": {"type": ["string", "null"], "maxLength": 128},
+        "environment": {"type": ["string", "null"], "maxLength": 128},
+        "service": {"type": ["string", "null"], "maxLength": 128},
+        "region": {"type": ["string", "null"], "maxLength": 128},
+        "instance": {"type": ["string", "null"], "maxLength": 128}
+      }
+    },
     "runtime": {"type": "object"},
     "context": {"type": "object"},
     "payload": {"type": "object"}

data/docs/adr/ADR-017-deploy-events-and-correlation.md

@@ -0,0 +1,25 @@
+# ADR-017 — Synchronous deploy events and immutable release correlation
+
+## Status
+
+Accepted for version 0.9.
+
+## Context
+
+The SaaS needs stable release dimensions to compare error and performance behavior before and after deployments. Deployment tools are short-lived processes, while application telemetry is long-lived and concurrent. Implicit Git, lockfile, or environment discovery would make behavior surprising and could expose credentials.
+
+## Decision
+
+Add a versioned `deploy` telemetry payload delivered synchronously through the existing transport policy. Require an environment and either revision or version, generate a deploy ID when omitted, bound every field, and remove credentials from common repository URL forms.
+
+Emit a `correlation` object on every new v1 envelope with release, revision, deploy ID, environment, service, region, and instance. Keep the schema property optional so payloads from earlier 0.x clients remain valid. Populate it from the immutable configuration snapshot for application events and from normalized deploy fields for deploy events. Do not mutate a running agent's correlation after notification.
+
+Refresh the bounded dependency inventory after a successful deploy notification. Integrate Capistrano through its task DSL without a runtime dependency. Support Kamal by documented command and GitHub Actions through an example workflow.
+
+## Alternatives
+
+Reading Git state, all environment variables, or deployment manifests automatically was rejected for determinism and privacy. Asynchronous-only deploy delivery was rejected because short-lived commands can exit before queue drain. Mutating global release state after `notify_deploy` was rejected because concurrent events could receive mixed correlation. Adding direct dependencies on Capistrano, Kamal, or GitHub SDKs was rejected for the legacy compatibility line.
+
+## Consequences
+
+Every event has a stable bounded correlation shape and deploy commands receive an explicit success result. Applications must pass release metadata into each newly started process. Integration setup remains explicit, and delivery failure policy stays under the deployment pipeline's control.

data/docs/adr/ADR-018-pre-1.0-hardening.md

@@ -0,0 +1,9 @@
+# ADR-018: Pre-1.0 hardening gates
+
+## 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.
+
+## 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.

data/docs/architecture.md

@@ -1,6 +1,6 @@
 # Architecture
 
-Chronos Ruby 0.8 uses hexagonal boundaries so the legacy core remains independent of frameworks and delivery infrastructure.
+Chronos Ruby 0.9 uses hexagonal boundaries so the legacy core remains independent of frameworks and delivery infrastructure.
 
 ```mermaid
 flowchart TB
@@ -24,6 +24,8 @@ flowchart TB
   NetHTTP[Explicit Net::HTTP instance wrapper] --> Facade
   Rails --> Cache[Core / CacheNormalizer]
   Application --> Dependencies[Application / DependencyReporter]
+  Deploy[Manual, Capistrano, Kamal command, GitHub workflow] --> Facade
+  Core --> Correlation[Core / DeployNormalizer and CorrelationContext]
 ```
 
 ## Boundaries
@@ -55,6 +57,10 @@ Version 0.7 routes request, query, and job observations through `ApmAggregator`.
 
 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.
 
+Version 0.9 routes explicit deploy attributes through `DeployNormalizer`, synchronous `CaptureTelemetry`, the common sanitizer, and `DeliveryPipeline`. `CorrelationContext` supplies the same fixed seven-field shape to exception and telemetry serializers. Deploy event overrides apply only while serializing that event; the agent configuration remains immutable for concurrent application capture. A successful deployment resets the dependency reporter once and flushes the refreshed inventory.
+
+Capistrano remains an optional integration task with no runtime dependency. Kamal and GitHub Actions call the same manual Ruby command rather than adding SDKs or transport paths.
+
 ## Failure policy
 
 Explicit invalid configuration raises `Chronos::ConfigurationError`. Capture, serialization, logger, worker, retry, circuit, TLS, network, HTTP, and remote-policy failures do not escape into the host application. They produce `false`, a classified transport result, a bounded state transition, or a bounded logger diagnostic.

data/docs/compatibility.md

@@ -13,16 +13,21 @@ Chronos Ruby 0.x is the legacy line. Technical compatibility does not make an en
 
 | Ruby | Sidekiq integration | Status | Evidence |
 |---|---|---|---|
-| 2.2.10–2.6 | Sidekiq 4 / 5 | Best effort | Middleware unit/integration contracts; dedicated real-gem matrix pending |
+| 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 |
 
 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.
 
-Version `0.6.0.pre.1` uses the public Sidekiq 4/5 middleware signatures and remains `Best effort` until dedicated jobs exercise both real gem versions across their valid Ruby combinations.
+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.
+
+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.
 
 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.
 
 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.
 
+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.
+
 Status meanings:
 
 - Supported: the complete required compatibility gate passes.

data/docs/configuration.md

@@ -8,8 +8,12 @@
 | `project_key` | Yes when enabled | `nil` | Secret authentication key sent only as an HTTP header |
 | `host` | Yes when enabled | `nil` | Absolute Chronos HTTP endpoint; HTTPS is required by default |
 | `environment` | Recommended | `production` | Application environment |
-| `app_version` | Optional | `nil` | Release or revision identifier |
+| `app_version` | Optional | `nil` | Application release/version identifier |
 | `service_name` | Recommended | `nil` | Logical service name |
+| `revision` | Optional | `nil` | Source revision correlated with every event; maximum 128 bytes |
+| `deploy_id` | Optional | `nil` | Deployment identifier correlated with every event; maximum 128 bytes |
+| `region` | Optional | `nil` | Deployment region correlated with every event; maximum 128 bytes |
+| `instance_id` | Optional | `nil` | Explicit instance correlation; otherwise runtime hostname is used |
 | `root_directory` | Optional | `Dir.pwd` | Used to identify application backtrace frames |
 | `logger` | Optional | `nil` | Logger receiving bounded internal diagnostics |
 | `timeout` | Optional | `5.0` | HTTP read timeout in seconds |
@@ -28,6 +32,8 @@
 | `allowlist_keys` | Optional | `[]` | Explicit key-name exceptions; content detection still runs |
 | `hash_keys` | Optional | `[]` | Scalar identifier keys replaced by scoped SHA-256 values |
 | `filters` | Optional | `[]` | Callable application-specific privacy filters |
+| `ignore_rules` | Optional | `[]` | Callable local exception rules evaluated before serialization |
+| `max_ignore_rules` | Optional | `20` | Maximum retained local rules; range 1–100 |
 | `anonymize_ip` | Recommended | `true` | Replaces the final octet of supplied IPv4 addresses |
 | `max_retries` | Optional | `3` | Maximum retry attempts after the first delivery failure |
 | `retry_base_interval` | Optional | `0.5` | Initial exponential-backoff delay in seconds |
@@ -39,7 +45,7 @@
 | `remote_configuration` | Optional | `true` | Accepts only the documented bounded remote policy fields |
 | `remote_config_max_bytes` | Optional | `4096` | Maximum remote policy response-header bytes |
 | `sampling_rate` | Optional | `1.0` | Local upper bound for event sampling |
-| `enabled_event_types` | Optional | exception, request, query, job, cache, external_http, dependencies, metric_batch | Local allowlist for supported event envelopes |
+| `enabled_event_types` | Optional | exception, request, query, job, cache, external_http, dependencies, deploy, metric_batch | Local allowlist for supported event envelopes |
 | `max_remote_send_interval` | Optional | `60.0` | Local upper bound for remotely requested send spacing |
 | `context_store` | Optional | `:thread_local` | `:thread_local` or an object implementing `get`, `set`, `clear`, and `with_context` |
 | `breadcrumb_capacity` | Optional | `20` | Positive count of newest breadcrumbs retained per execution |
@@ -70,10 +76,17 @@ Chronos.configure do |config|
   config.host = ENV["CHRONOS_HOST"]
   config.environment = ENV["APP_ENV"] || "production"
   config.service_name = "billing"
+  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"]
   config.queue_size = 100
   config.workers = 1
   config.blocklist_keys += [:medical_record, /bank_account/i]
   config.hash_keys += [:customer_id]
+  config.ignore_rules << proc { |notice| notice.exception_class == "SomeExpectedError" }
+  config.max_ignore_rules = 20
   config.max_retries = 3
   config.backlog_size = 100
   config.circuit_failure_threshold = 5
@@ -97,8 +110,10 @@ Chronos.configure do |config|
 end
 ```
 
-Privacy matcher collections and filters are copied into the immutable runtime snapshot. Matchers must be String, Symbol, or Regexp values, and every custom filter must respond to `call`.
+Privacy matcher collections, filters, and startup ignore rules are copied into the immutable runtime snapshot. Matchers must be String, Symbol, or Regexp values, and every filter/rule must respond to `call`. Runtime rules added through `Chronos.ignore_if` cannot exceed `max_ignore_rules`.
 
 The gem never reads all environment variables automatically. The host application decides which values to pass. See [Privacy and LGPD](privacy-lgpd.md) before adding application context.
 
 Remote configuration can only reduce collection within local bounds. It cannot increase `max_payload_size` or `sampling_rate`, enable an unsupported or locally disabled event type, change the endpoint, replace credentials, disable TLS verification, or install executable matching rules.
+
+Release correlation values are copied into the immutable snapshot. Calling `Chronos.notify_deploy` reports a deployment but does not mutate those values for concurrent application events; configure each deployed process with its own release identity.

data/docs/data-collected.md

@@ -1,6 +1,6 @@
 # Data collected
 
-Version 0.8 emits exceptions, cache telemetry, one dependency inventory, and aggregated request/query/job/external-HTTP metric batches. All fields pass through the privacy sanitizer and bounded safe serializer before queueing, retry storage, or delivery.
+Version 0.9 emits exceptions, cache telemetry, dependency/deploy events, and aggregated request/query/job/external-HTTP metric batches. All fields pass through the privacy sanitizer and bounded safe serializer before queueing, retry storage, or delivery.
 
 | Data | Default | Source |
 |---|---|---|
@@ -26,7 +26,8 @@ Version 0.8 emits exceptions, cache telemetry, one dependency inventory, and agg
 | View template basename and duration | Collected with Rails integration | `render_template.action_view` |
 | SQL operation name, cached flag, duration | Collected; SQL text omitted | `sql.active_record` |
 | Mailer/action and duration | Collected; message content omitted | `deliver.action_mailer` |
-| Active Job class, queue, duration | Collected when available; arguments omitted | `perform.active_job` |
+| Active Job adapter, job/provider IDs, class, queue, attempts, duration, status, error class | Collected when available; arguments omitted | serialization and `perform.active_job` |
+| Active Job trace/request IDs | Propagated in a bounded namespaced field | Current Chronos context |
 | Sidekiq class, queue, JID, retry count, duration, status, error class | Collected with optional middleware | Sidekiq job envelope and local clock |
 | Sidekiq queue latency | Collected when enqueue time is available | Sidekiq or Chronos envelope timestamp |
 | Sidekiq arguments | Collected, sanitized, and bounded | First 20 job arguments; collections/depth/strings limited |
@@ -45,8 +46,10 @@ Version 0.8 emits exceptions, cache telemetry, one dependency inventory, and agg
 | Cache key hash | Disabled by default | Project-scoped SHA-256 when `cache_key_mode = :sha256` |
 | Loaded gem names/versions and Ruby runtime | Once per agent by default; bounded | `Gem.loaded_specs` and Ruby constants |
 | Rails, web server, database adapter, Sidekiq, release | Included when safely detectable/configured | Loaded constants/specs and `app_version` |
+| Event release, revision, deploy ID, environment, service, region, instance | Present as bounded correlation; values optional | Explicit immutable configuration or normalized deploy payload |
+| Deploy environment, revision, version, repository, actor, deploy ID, service, region, instance | Explicit synchronous deploy API | Application/deployment integration arguments |
 
-The gem never collects request bodies, response bodies, raw query strings, cookies, HTTP authorization headers, environment variables in bulk, source code, raw SQL, SQL bind values, database rows, raw cache keys/values, mail bodies/recipients, gem paths, or lockfile contents. Sidekiq JIDs/arguments and bounded loaded gem names/versions are documented integration fields.
+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.
 
 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

@@ -0,0 +1,7 @@
+# Deprecation policy
+
+After `1.0.0`, a public API scheduled for removal remains available for at least one minor release and normally six months. The warning, replacement, first deprecated version, and earliest removal version must be documented in the changelog and migration material.
+
+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.

data/docs/examples/plain-ruby.md

@@ -29,4 +29,10 @@ For network-free per-instance outbound HTTP instrumentation, run:
 bundle _1.17.3_ exec ruby examples/plain-ruby/external_http.rb
 ```
 
-The examples demonstrate final event construction, key redaction, e-mail and Bearer-token detection, application-specific blocklisting, identifier hashing, and the bounded external HTTP payload without opening a socket.
+For a network-free deploy event with complete release correlation, run:
+
+```bash
+bundle _1.17.3_ exec ruby examples/plain-ruby/deploy_tracking.rb
+```
+
+The examples demonstrate final event construction, privacy filtering, bounded external HTTP fields, and deploy correlation without opening a socket.

data/docs/migration-from-airbrake.md

@@ -0,0 +1,18 @@
+# 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.
+
+| Airbrake concept | Chronos equivalent |
+|---|---|
+| `Airbrake.configure` credentials/host | `Chronos.configure` with `project_id`, `project_key`, and `host` |
+| `Airbrake.notify(error, params)` | `Chronos.notify(error, :parameters => params)` |
+| `Airbrake.notify_sync` | `Chronos.notify_sync` |
+| ignore/filter callbacks | `Chronos.ignore_if` and `config.filters` |
+| deploy notification | `Chronos.notify_deploy` |
+| Rack/Rails integration | `require "chronos/rails"` or Chronos Rack middleware |
+
+Start with `error_notifications`, Rails capture, and APM enabled in one non-production environment. Configure the same application version and environment used by the old notifier. Compare exception count, class, sanitized context, deploy correlation, request/job metrics, and retry diagnostics. Never copy an Airbrake project key into Chronos.
+
+Chronos callbacks receive a normalized immutable `Chronos::Core::Notice`, not an Airbrake notice. Filters operate on each sanitized key/value pair. Translate callback logic explicitly and add tests; do not assume callback argument compatibility. Chronos intentionally omits request/response bodies, raw SQL, binds, cookies, authorization headers, mail content, and raw cache keys.
+
+Before removing Airbrake, exercise a synchronous notification, an asynchronous notification followed by `Chronos.flush`, a Rails/Rack failure, a background job failure, and an unavailable endpoint. Confirm that the bounded queue/backlog behavior is acceptable. Roll back by disabling Chronos or restoring the previous dependency; no application exception semantics are changed by the agent.

data/docs/modules/active-job.md

@@ -0,0 +1,7 @@
+# Active Job legacy integration
+
+When `ActiveJob::Base` is available, the Rails installer prepends public serialization/execution hooks. Enqueue serialization adds a namespaced `chronos_context` field with schema version plus at most the trace and request identifiers; each identifier is limited to 128 bytes. Public job arguments are unchanged. Deserialization restores this context only around `perform_now`.
+
+The `perform.active_job` subscriber records adapter, job ID, provider job ID, class, queue, execution count, duration, status, and error class. Arguments are omitted. A supplied exception is reported once with bounded job context. The integration never changes retry, acknowledgement, adapter, or original exception behavior.
+
+This metadata can identify a workflow or tenant in some applications. Review retention and identifier generation under the project's privacy policy.

data/docs/modules/configuration.md

@@ -11,3 +11,5 @@ Tests in `spec/unit/configuration_spec.rb` verify required fields, HTTPS default
 Version 0.7 adds bounded APM capacities, thresholds, and histogram boundaries. Invalid zero/negative capacities, batches above 50, N+1 thresholds below two, and non-increasing histogram boundaries are rejected before agent construction. See [Essential APM aggregation](apm-aggregation.md).
 
 Version 0.8 adds Boolean HTTP/dependency switches, `:none`/`:sha256` cache-key policy, and a dependency limit from 1 to 200. Invalid values are rejected before instrumentation or collection starts. See [External HTTP](external-http.md), [Cache observability](cache-observability.md), and [Dependency inventory](dependencies.md).
+
+Version 0.9 adds optional `revision`, `deploy_id`, `region`, and `instance_id` strings, each limited to 128 bytes. Together with the existing release/environment/service options they form immutable event correlation. See [Deploy tracking and release correlation](deploy-tracking.md).

data/docs/modules/dependencies.md

@@ -1,6 +1,6 @@
 # Dependency inventory
 
-Version `0.8.0.pre.1` emits a separate `dependencies` event at most once per configured agent. It is queued before the first capture or during explicit flush/close and is never attached to each exception.
+Version `0.9.0.pre.1` emits a separate `dependencies` event at most once per configured agent and once again after a successful deploy notification. It is queued before the first capture or during explicit flush/close and is never attached to each exception.
 
 The inventory contains Ruby version/engine/platform, bounded names and versions from already loaded gem specs, the configured `app_version` release identifier, and Rails, Sidekiq, web server, or database adapter labels when safely detectable. The agent does not parse `Gemfile.lock`, activate missing gems, inspect gem paths/source, scan environment variables, open a database connection, or collect dependency configuration.
 
@@ -15,4 +15,4 @@ end
 Chronos.report_dependencies
 ```
 
-`dependency_max_items` accepts 1–200 and defaults to 100. Entries are sorted by name before truncation so repeated boots are stable. Set `dependency_reporting = false` when inventory collection is unnecessary or prohibited. Because collection is once-only, gems loaded after the first event appear only after a new agent configuration or process boot.
+`dependency_max_items` accepts 1–200 and defaults to 100. Entries are sorted by name after bounded selection. Set `dependency_reporting = false` when inventory collection is unnecessary or prohibited. A successful `notify_deploy` resets the once-only guard and uses the deploy version for the refreshed inventory; otherwise gems loaded after the first event appear only after a new agent configuration or process boot.

data/docs/modules/deploy-tracking.md

@@ -0,0 +1,86 @@
+# Deploy tracking and release correlation
+
+Version `0.9.0.pre.1` adds synchronous deploy notifications and a bounded correlation block to every exception and telemetry envelope. The SaaS can compare errors and performance before and after a release using release, revision, deploy ID, environment, service, region, and instance.
+
+## Public API
+
+Configure the agent, then provide deploy metadata explicitly:
+
+```ruby
+Chronos.notify_deploy(
+  :environment => "production",
+  :revision => ENV["GIT_SHA"],
+  :version => ENV["APP_VERSION"],
+  :repository => "owner/repository",
+  :actor => ENV["DEPLOY_USER"],
+  :deploy_id => ENV["DEPLOY_ID"],
+  :service => "billing",
+  :region => "sa-east-1",
+  :instance => "web-1"
+)
+```
+
+Environment is required, and either revision or version must be present. A UUID deploy ID is generated when none is supplied. The call uses synchronous delivery, bypasses ordinary event sampling, then refreshes the bounded dependency inventory for the new release and flushes it before returning. Local/remote event disabling and the kill switch still apply. It returns `false` instead of leaking configuration, normalization, serialization, or transport failures.
+
+Fields are limited to 128 bytes, except repository at 512 bytes. HTTP and SCP-style repository credentials are stripped before serialization. The shared sanitizer still filters explicit actor/repository content. Do not send access tokens, e-mail addresses, or unnecessary personal data.
+
+## Correlation on application events
+
+Set the values that identify the currently running release during normal application configuration:
+
+```ruby
+Chronos.configure do |config|
+  # project and endpoint settings omitted
+  config.app_version = ENV["APP_VERSION"]
+  config.revision = ENV["GIT_SHA"]
+  config.deploy_id = ENV["DEPLOY_ID"]
+  config.environment = ENV["APP_ENV"] || "production"
+  config.service_name = "billing"
+  config.region = ENV["REGION"]
+  config.instance_id = ENV["INSTANCE_ID"]
+end
+```
+
+The gem never reads these variables itself. The host application chooses each source. Configuration snapshots are immutable, so `notify_deploy` does not mutate correlation for an already running process; newly deployed processes must start with their own release values.
+
+## Capistrano
+
+Require the optional entry point after Capistrano loads:
+
+```ruby
+require "chronos/capistrano"
+
+set :chronos_version, ENV["APP_VERSION"]
+set :chronos_actor, ENV["DEPLOY_USER"]
+set :chronos_deploy_id, ENV["DEPLOY_ID"]
+set :chronos_service, "billing"
+set :chronos_region, ENV["DEPLOY_REGION"]
+```
+
+It registers `chronos:notify_deploy` after `deploy:published`, once per DSL object. Revision, stage, and repository use the public Capistrano variables `current_revision`, `stage`, and `repo_url`; all Chronos-specific values are optional and explicit. The integration adds no Capistrano runtime dependency.
+
+## Manual, Kamal, and GitHub Actions
+
+[`examples/deploy/notify.rb`](../../examples/deploy/notify.rb) is the shared command. It requires project credentials/host and deploy environment, reads only named variables, notifies synchronously, closes the agent, and exits nonzero on failure.
+
+For Kamal, pass the variables to the deployed container or command environment and execute after publication:
+
+```bash
+kamal app exec --reuse "bundle exec ruby examples/deploy/notify.rb"
+```
+
+Adapt the command to the application's Kamal hook lifecycle and secret-management policy. The repository also provides a non-active [GitHub Actions workflow example](../../examples/deploy/github-actions.yml) using read-only repository permission and secret-scoped Chronos credentials.
+
+For a network-free payload demonstration:
+
+```bash
+bundle _1.17.3_ exec ruby examples/plain-ruby/deploy_tracking.rb
+```
+
+## Limitations
+
+- delivery is process-local and uses the existing finite retry/circuit/backlog policy;
+- an unsuccessful synchronous delivery returns `false`; deployment policy decides whether that blocks publication;
+- Capistrano auto-registration requires its task DSL to be loaded first;
+- Kamal integration is command/documentation based, not a Kamal plugin;
+- repository and actor are explicit metadata and remain subject to application privacy review.