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

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 44c7cad424497d7998727de5a916594ecc3ce9dfda7580376fe4a754edd9096e
-  data.tar.gz: 3f7a64cbf5b5879e107d7102c1f72cdd2ac4c941e1640a05b6210db79cd948f9
+  metadata.gz: 34b5d9d1193017931d129dc366922b276d9b85ced0321e78d3f4a5b1a8c13e40
+  data.tar.gz: 72277b74f51825118ce6cb2dda83652f035bbfef3cb56c18b7ee98cc3e6d1d54
 SHA512:
-  metadata.gz: f62fa57bfcfec70f7172afc4c939d905aa9c7d9215960b73fa0c54406568b43b93e41b02ba22eb13b381243e06cf61a087544db00ed97ea4ce5805f84e9901e7
-  data.tar.gz: 3a66ec4e2a85f7f2e79868523fe63a493aeb598aff810dfd21b84a25dd0505e21ee66cac35a7113927a9b4b5a5c5ea2f41d25b89b452b38088c0ef3570f876bf
+  metadata.gz: 2c6b44a856bbb8975c6a4dc9aba5d9bcd2cf9a9d44456c19fe373860872491ff310f11a2a1b4c7588306ae2795caf4af8cf008e38c10bcdbe0322fca9a803ece
+  data.tar.gz: c4ff3f4da09810013c0e4d352bb18cd04c0a652c160816465d4b088490d5eea5f722c326ab8a6dcc9806f7b74c050ee0c77e8c6a4c604ddf650cb08fc66a3fd4

data/CHANGELOG.md

@@ -12,6 +12,31 @@ 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.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.1"
 ```
 
 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.1", :require => "chronos/rails"
 ```
 
 Generate the initializer with:
@@ -191,7 +193,7 @@ 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.1", :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).
@@ -220,7 +222,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 +312,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 +328,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 +341,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/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/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

@@ -23,6 +23,8 @@ Version `0.7.0.pre.1` keeps the same Ruby/Rails matrix and implements APM aggreg
 
 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 |
@@ -39,7 +43,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,6 +74,11 @@ 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]
@@ -102,3 +111,5 @@ Privacy matcher collections and filters are copied into the immutable runtime sn
 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 |
 |---|---|---|
@@ -45,8 +45,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, gem paths, or lockfile contents. Sidekiq JIDs/arguments, loaded gem names/versions, and deploy fields are documented integration data.
 
 APM dimensions never include user ID, job ID, raw URL, exception message, bind value, or cache key. Normalized routes replace common numeric/UUID segments. Normalized SQL can retain schema, table, and column identifiers; review those identifiers as part of the privacy audit.
 

data/docs/examples/plain-ruby.md

@@ -29,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/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.

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", "0.8.0.pre.1", :require => "chronos/sidekiq"
+gem "chronos-ruby", "0.9.0.pre.1", :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/telemetry-events.md

@@ -1,9 +1,11 @@
 # Framework telemetry events
 
-`Chronos::Core::TelemetryEvent` and `Chronos::Core::TelemetrySerializer` extend the v1 envelope to `request`, `query`, `job`, `cache`, `external_http`, `dependencies`, and `metric_batch` events. These values exist so integrations do not model operational telemetry as fake exceptions.
+`Chronos::Core::TelemetryEvent` and `Chronos::Core::TelemetrySerializer` extend the v1 envelope to `request`, `query`, `job`, `cache`, `external_http`, `dependencies`, `deploy`, and `metric_batch` events. These values exist so integrations do not model operational telemetry as fake exceptions.
 
 Telemetry has the same `schema_version`, event ID, timestamps, project, environment, service, runtime, context, sanitization, payload-size limit, idempotency header, asynchronous queue, retry, circuit breaker, and memory backlog used by exception events. Unsupported types are rejected locally.
 
 `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.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 0.8 makes no unverified speed claim.
+Performance is a functional requirement, but version 0.9 makes no unverified speed claim.
 
 Current controls:
 
@@ -24,6 +24,8 @@ Current controls:
 - 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.
+- event correlation copies exactly seven strings with a 128-byte bound each;
+- deploy notification uses the existing synchronous delivery path and creates no timer or worker type.
 
 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.
 
@@ -115,3 +117,15 @@ ITERATIONS=100000 bundle _1.17.3_ exec ruby benchmarks/external_http.rb
 The fixture compares a no-op Net::HTTP-compatible object with the per-instance wrapper. It includes trace-header injection, bounded outcome capture, and clock reads, but excludes DNS, sockets, TLS, serialization, queueing, and network delivery. Record a controlled result before making a performance claim.
 
 A local diagnostic run on 2026-07-20 used Ruby 2.2.10 on macOS arm64 and 10,000 calls. It measured approximately 15.155 microseconds of wrapper overhead per call. This single run has no controlled warmup, median, or dispersion and is not a production performance claim.
+
+## Version 0.9 correlation benchmark
+
+Run:
+
+```bash
+ITERATIONS=100000 bundle _1.17.3_ exec ruby benchmarks/correlation.rb
+```
+
+The fixture builds the seven-field frozen correlation hash from an immutable configuration. It excludes notice/event construction, sanitization, JSON, queueing, retry, and network delivery. Record a controlled result before making a performance claim.
+
+A local diagnostic run on 2026-07-21 used Ruby 2.2.10 on macOS arm64 and 10,000 correlations. It measured approximately 20.490 microseconds per correlation. This single run has no controlled warmup, median, or dispersion and is not a production performance claim.

data/docs/privacy-lgpd.md

@@ -1,6 +1,6 @@
 # Privacy and LGPD
 
-Version 0.8 sanitizes exception, framework telemetry, dependency inventory, and APM metric batches before JSON serialization, queueing, retry backlog, or transport. This reduces accidental exposure, but the host application remains responsible for lawful purpose, minimization, access control, retention, and responses to data-subject requests.
+Version 0.9 sanitizes exception, framework telemetry, dependency/deploy inventory, correlation, and APM metric batches before JSON serialization, queueing, retry backlog, or transport. This reduces accidental exposure, but the host application remains responsible for lawful purpose, minimization, access control, retention, and responses to data-subject requests.
 
 ## Default policy
 
@@ -19,8 +19,17 @@ Version 0.8 sanitizes exception, framework telemetry, dependency inventory, and
 | 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 |
+| Deploy correlation | Explicit bounded operational identifiers; no automatic Git or environment scan |
+| Repository | Credentials removed from common HTTP/SCP forms; query/fragment omitted for parsed URLs |
+| Actor | Explicit and sanitized; omit it when personal identity is unnecessary |
 
-The retry backlog exists only in process memory, accepts only `SerializedEvent`, has a fixed capacity, and disappears on process exit. Version 0.8 does not persist telemetry to disk.
+The retry backlog exists only in process memory, accepts only `SerializedEvent`, has a fixed capacity, and disappears on process exit. Version 0.9 does not persist telemetry to disk.
+
+## Deploy metadata
+
+Release, revision, deploy ID, environment, service, region, and instance are operational identifiers but can become personal or sensitive when applications encode customer, tenant, employee, or infrastructure-secret values in them. Use opaque bounded identifiers. Repository should be an owner/name identifier rather than a credential-bearing clone URL. Actor is optional; prefer a service account label when individual identity is unnecessary.
+
+The deploy normalizer removes user information from standard HTTP(S) repository URLs and usernames from SCP-style Git references. This is defensive, not a substitute for secret management. Never pass access tokens in any deploy field. All values still traverse the common sanitizer before transport.
 
 ## External services, cache, and dependencies
 

data/docs/troubleshooting.md

@@ -36,6 +36,18 @@ Set `external_http_trace_headers = false` before configuring the agent, or do no
 
 The event is emitted once per agent and contains only gems loaded at collection time, capped by `dependency_max_items`. It does not parse the lockfile or activate optional frameworks. Call `Chronos.report_dependencies` after application boot if the first event can occur before all integrations load, or set `dependency_reporting = false` to disable collection.
 
+## `Chronos.notify_deploy` returns false
+
+Confirm Chronos is configured/enabled, environment is present, and at least revision or version is non-empty. Check credentials, TLS, proxy, timeout, retry/circuit state, and endpoint response. The call is synchronous and deliberately returns the delivery result. Repository credentials are removed and do not help authenticate with Chronos.
+
+## Events have empty or stale release correlation
+
+Set `app_version`, `revision`, `deploy_id`, `environment`, `service_name`, `region`, and `instance_id` before `Chronos.configure` creates its snapshot. `notify_deploy` does not mutate a running agent because that would mix release identities across concurrent events. Restart/configure each deployed process with the new values.
+
+## Capistrano task is missing
+
+Require `chronos/capistrano` after the Capistrano/Rake task DSL is loaded. The installer registers once per DSL and hooks `chronos:notify_deploy` after `deploy:published`. Confirm the base Chronos configuration runs in the task process and the expected `stage`, `current_revision`, `repo_url`, and `chronos_*` variables exist.
+
 ## Sidekiq telemetry is missing
 
 Require `chronos/sidekiq` after Sidekiq is available and configure Chronos before jobs run. The entry point uses Sidekiq's public client/server middleware configuration and remains optional. Requiring only `chronos` or `chronos/rails` does not load Sidekiq. A job already enqueued before client middleware installation may lack propagated trace context, but server timing and failure capture can still run.

data/lib/chronos/agent.rb

@@ -37,7 +37,7 @@ module Chronos
         pipeline_options
       )
       initialize_capture(options)
-      @dependency_reporter = options[:dependency_reporter] || Application::DependencyReporter.new(config)
+      initialize_observability(options)
     end
 
     def notify(exception, context = {})
@@ -67,6 +67,8 @@ module Chronos
     end
 
     def record_event(event_type, payload = {}, context = {})
+      return false if event_type.to_s == "deploy"
+
       report_dependencies unless event_type.to_s == "dependencies"
       @telemetry.call(event_type, payload, telemetry_context(context))
     end
@@ -81,6 +83,18 @@ module Chronos
       false
     end
 
+    def notify_deploy(attributes = {}, timeout = DEFAULT_FLUSH_TIMEOUT)
+      payload = @deploy_normalizer.call(attributes)
+      return false unless @telemetry.call_sync("deploy", payload, {})
+
+      @dependency_reporter.reset(payload["version"]) if @dependency_reporter.respond_to?(:reset)
+      report_dependencies
+      flush(timeout)
+    rescue StandardError => error
+      @logger.warn("Chronos deploy notification failed: #{error.class}")
+      false
+    end
+
     def record_event_once(key, event_type, payload = {}, context = {})
       execution = @context_store.get
       captured = execution[:__chronos_captured_events] || {}
@@ -176,6 +190,11 @@ module Chronos
       @telemetry = options[:telemetry] || Application::CaptureTelemetry.new(@config, @delivery_pipeline, @logger)
     end
 
+    def initialize_observability(options)
+      @dependency_reporter = options[:dependency_reporter] || Application::DependencyReporter.new(@config)
+      @deploy_normalizer = options[:deploy_normalizer] || Core::DeployNormalizer.new(@config)
+    end
+
     def build_context_store(strategy)
       return Adapters::ThreadLocalContextStore.new if strategy == :thread_local
 

data/lib/chronos/application/capture_telemetry.rb

@@ -40,6 +40,17 @@ module Chronos
         false
       end
 
+      def call_sync(event_type, payload = {}, context = {})
+        return false unless @config.enabled_for_environment?
+        return false unless synchronous_capture_allowed?(event_type)
+
+        event = Core::TelemetryEvent.new(event_type, payload, context)
+        @delivery_pipeline.deliver_sync(@serializer.call(event))
+      rescue StandardError => error
+        @logger.warn("Chronos synchronous telemetry capture failed: #{error.class}")
+        false
+      end
+
       def flush
         enqueue_batches(@aggregator.flush)
       rescue StandardError => error
@@ -55,6 +66,12 @@ module Chronos
 
       private
 
+      def synchronous_capture_allowed?(event_type)
+        return @delivery_pipeline.event_enabled?(event_type) if event_type.to_s == "deploy"
+
+        @delivery_pipeline.capture_allowed?(event_type)
+      end
+
       def aggregate_type?(event_type)
         ApmAggregator::METRIC_TYPES.include?(event_type.to_s)
       end

data/lib/chronos/application/dependency_reporter.rb

@@ -19,6 +19,17 @@ module Chronos
         @constants = options[:constants] || {}
         @mutex = Mutex.new
         @reported = false
+        @release_override = nil
+      end
+
+      def reset(release = nil)
+        @mutex.synchronize do
+          @release_override = bounded(release, 128)
+          @reported = false
+        end
+        true
+      rescue StandardError
+        false
       end
 
       def call
@@ -45,7 +56,7 @@ module Chronos
           "web_server" => detected("web_server") { web_server },
           "database_adapter" => detected("database_adapter") { database_adapter },
           "sidekiq" => detected("sidekiq") { sidekiq_version },
-          "release" => bounded(@config.app_version.to_s, 128)
+          "release" => @release_override || bounded(@config.app_version.to_s, 128)
         }
         payload.delete_if do |key, value|
           !["dependencies", "ruby"].include?(key) && value.to_s.empty?

data/lib/chronos/application/remote_configuration.rb

@@ -14,7 +14,7 @@ module Chronos
     # @performance Validation is bounded by configured document and list limits.
     class RemoteConfiguration
       SUPPORTED_EVENT_TYPES = %w(
-        exception request query job cache external_http dependencies metric_batch
+        exception request query job cache external_http dependencies deploy metric_batch
       ).freeze
       MAX_IGNORED_FINGERPRINTS = 100
       MAX_FINGERPRINT_BYTES = 256

data/lib/chronos/capistrano.rb

@@ -0,0 +1,4 @@
+require "chronos"
+require "chronos/integrations/capistrano"
+
+Chronos::Integrations::Capistrano.install(self) if respond_to?(:namespace, true) && respond_to?(:after, true)

data/lib/chronos/configuration/apm_validation.rb

@@ -65,9 +65,20 @@ module Chronos
         unless dependency_max_items.is_a?(Integer) && dependency_max_items >= 1 && dependency_max_items <= 200
           errors << "dependency_max_items must be between 1 and 200"
         end
+        correlation_attributes.each do |name, value|
+          errors << "#{name} must be a String with at most 128 bytes" unless bounded_optional_string?(value, 128)
+        end
         errors
       end
 
+      def correlation_attributes
+        {:revision => revision, :deploy_id => deploy_id, :region => region, :instance_id => instance_id}
+      end
+
+      def bounded_optional_string?(value, limit)
+        value.nil? || (value.is_a?(String) && value.bytesize <= limit)
+      end
+
       def boolean?(value)
         [true, false].include?(value)
       end

data/lib/chronos/configuration.rb

@@ -32,7 +32,8 @@ module Chronos
 
     ATTRIBUTES = [
       :project_id, :project_key, :host, :environment, :app_version,
-      :service_name, :root_directory, :logger, :timeout, :open_timeout,
+      :service_name, :revision, :deploy_id, :region, :instance_id,
+      :root_directory, :logger, :timeout, :open_timeout,
       :queue_size, :workers, :enabled, :error_notifications,
       :ignored_environments, :proxy, :ssl_verify, :user_agent,
       :max_payload_size, :gzip, :blocklist_keys, :allowlist_keys,
@@ -59,6 +60,7 @@ module Chronos
       initialize_rails_defaults
       initialize_apm_defaults
       initialize_observability_defaults
+      initialize_correlation_defaults
     end
 
     def snapshot
@@ -120,6 +122,13 @@ module Chronos
       @breadcrumb_max_bytes = 2048
     end
 
+    def initialize_correlation_defaults
+      @revision = nil
+      @deploy_id = nil
+      @region = nil
+      @instance_id = nil
+    end
+
     def initialize_rails_defaults
       @rails_enabled = true
       @rails_capture_in_console = false
@@ -167,7 +176,7 @@ module Chronos
       @remote_config_max_bytes = 4096
       @sampling_rate = 1.0
       @enabled_event_types = [
-        "exception", "request", "query", "job", "cache", "external_http", "dependencies", "metric_batch"
+        "exception", "request", "query", "job", "cache", "external_http", "dependencies", "deploy", "metric_batch"
       ]
       @max_remote_send_interval = 60.0
     end

data/lib/chronos/core/correlation_context.rb

@@ -0,0 +1,65 @@
+module Chronos
+  module Core
+    # Builds the bounded release/deploy correlation shared by every event envelope.
+    #
+    # @responsibility Normalize release, revision, deploy, environment, service, region, and instance.
+    # @motivation Give the SaaS stable before/after-deploy dimensions without integration-specific fields.
+    # @limits Values come only from explicit configuration or caller overrides; no environment is scanned.
+    # @collaborators PayloadSerializer, TelemetrySerializer, and Configuration::Snapshot.
+    # @thread_safety Instances hold immutable configuration and calls allocate independent frozen hashes.
+    # @compatibility Ruby 2.2.10 through Ruby 2.6.
+    # @example
+    #   CorrelationContext.new(config).call("revision" => "abc123")
+    # @errors Unreadable optional values become nil and do not escape.
+    # @performance Seven strings are copied with a fixed 128-byte maximum each.
+    class CorrelationContext
+      FIELDS = %w(release revision deploy_id environment service region instance).freeze
+
+      def initialize(config)
+        @config = config
+      end
+
+      def call(overrides = {})
+        values = defaults.merge(string_hash(overrides))
+        result = FIELDS.each_with_object({}) do |name, correlation|
+          correlation[name.freeze] = bounded(values[name], 128)
+        end
+        result.each_value { |value| value.freeze if value }
+        result.freeze
+      rescue StandardError
+        FIELDS.each_with_object({}) { |name, fallback| fallback[name] = nil }.freeze
+      end
+
+      private
+
+      def defaults
+        {
+          "release" => @config.app_version, "revision" => @config.revision,
+          "deploy_id" => @config.deploy_id, "environment" => @config.environment,
+          "service" => @config.service_name, "region" => @config.region,
+          "instance" => @config.instance_id
+        }
+      end
+
+      def string_hash(value)
+        return {} unless value.is_a?(Hash)
+
+        value.each_with_object({}) do |(key, child), result|
+          result[key.to_s] = child if key.is_a?(String) || key.is_a?(Symbol)
+        end
+      end
+
+      def bounded(value, limit)
+        return nil if value.nil?
+        return nil unless value.is_a?(String) || value.is_a?(Symbol) || value.is_a?(Numeric)
+
+        text = value.to_s
+        text = text.scrub("?") if text.respond_to?(:scrub)
+        text = text.byteslice(0, limit) if text.bytesize > limit
+        text
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/chronos/core/deploy_normalizer.rb

@@ -0,0 +1,102 @@
+require "securerandom"
+require "uri"
+
+module Chronos
+  module Core
+    # Normalizes explicit deployment metadata into the versioned deploy payload.
+    #
+    # @responsibility Validate required deploy identity and bound every public API field.
+    # @motivation Deployment commands need predictable safe input independent of frameworks.
+    # @limits It does not inspect Git, environment variables, credentials, or deployment systems.
+    # @collaborators Chronos.notify_deploy, CorrelationContext, and Configuration::Snapshot.
+    # @thread_safety Stateless apart from immutable configuration and an injected ID generator.
+    # @compatibility Ruby 2.2.10 through Ruby 2.6.
+    # @example
+    #   DeployNormalizer.new(config).call(:revision => "abc", :version => "1.2.3")
+    # @errors Missing environment or both revision/version raise ArgumentError for the agent to contain.
+    # @performance Constant work over nine bounded scalar fields.
+    class DeployNormalizer
+      def initialize(config, options = {})
+        @config = config
+        @id_generator = options[:id_generator] || proc { SecureRandom.uuid }
+      end
+
+      def call(attributes = {})
+        values = string_hash(attributes)
+        payload = {
+          "deploy_id" => deploy_id(values["deploy_id"] || @config.deploy_id),
+          "environment" => bounded(values["environment"] || @config.environment, 128),
+          "revision" => bounded(values["revision"] || @config.revision, 128),
+          "version" => bounded(values["version"] || @config.app_version, 128),
+          "repository" => repository(values["repository"]),
+          "actor" => bounded(values["actor"], 128),
+          "service" => bounded(values["service"] || @config.service_name, 128),
+          "region" => bounded(values["region"] || @config.region, 128),
+          "instance" => bounded(values["instance"] || @config.instance_id, 128)
+        }
+        validate!(payload)
+        payload
+      end
+
+      private
+
+      def validate!(payload)
+        raise ArgumentError, "deploy environment is required" if payload["environment"].to_s.empty?
+        return unless payload["revision"].to_s.empty? && payload["version"].to_s.empty?
+
+        raise ArgumentError, "deploy revision or version is required"
+      end
+
+      def generated_id
+        value = bounded(@id_generator.call, 128)
+        raise ArgumentError, "deploy ID is required" if value.to_s.empty?
+
+        value
+      end
+
+      def deploy_id(value)
+        normalized = bounded(value, 128)
+        normalized.to_s.empty? ? generated_id : normalized
+      end
+
+      def repository(value)
+        text = bounded(value, 512)
+        return nil if text.nil?
+
+        scp = text.match(/\A[^@]+@([^:]+):(.+)\z/)
+        return bounded("#{scp[1]}/#{scp[2]}", 512) if scp
+
+        uri = URI.parse(text)
+        return bounded("#{uri.host}#{uri.path}", 512) if uri.host
+        return bounded(uri.path, 512) unless uri.path.to_s.empty?
+
+        nil
+      rescue StandardError
+        nil
+      end
+
+      def string_hash(value)
+        raise ArgumentError, "deploy attributes must be a Hash" unless value.is_a?(Hash)
+
+        value.each_with_object({}) do |(key, child), result|
+          result[key.to_s] = child if key.is_a?(String) || key.is_a?(Symbol)
+        end
+      end
+
+      def bounded(value, limit)
+        return nil if value.nil?
+        return nil unless scalar?(value)
+
+        text = value.to_s
+        text = text.scrub("?") if text.respond_to?(:scrub)
+        text.bytesize > limit ? text.byteslice(0, limit) : text
+      rescue StandardError
+        nil
+      end
+
+      def scalar?(value)
+        value.is_a?(String) || value.is_a?(Symbol) || value.is_a?(Numeric)
+      end
+    end
+  end
+end

data/lib/chronos/core/payload_serializer.rb

@@ -44,6 +44,7 @@ module Chronos
         @sanitizer = options[:sanitizer] || Sanitizer.new(config)
         @safe_serializer = options[:safe_serializer] || SafeSerializer.new
         @max_payload_size = options[:max_payload_size] || proc { @config.max_payload_size }
+        @correlation = options[:correlation] || CorrelationContext.new(config)
       end
 
       def call(notice)
@@ -70,8 +71,10 @@ module Chronos
           "service" => {
             "name" => @config.service_name,
             "version" => @config.app_version,
-            "instance_id" => notice.host
+            "instance_id" => @config.instance_id || notice.host
           },
+          "correlation" => @correlation.call("environment" => notice.environment,
+                                             "instance" => @config.instance_id || notice.host),
           "runtime" => notice.runtime,
           "context" => notice.context,
           "payload" => payload(notice)

data/lib/chronos/core/telemetry_event.rb

@@ -16,7 +16,7 @@ module Chronos
     # @errors Unsupported types raise ArgumentError during construction.
     # @performance Construction is linear in supplied context and payload size.
     class TelemetryEvent
-      TYPES = %w(request query job cache external_http dependencies metric_batch).freeze
+      TYPES = %w(request query job cache external_http dependencies deploy metric_batch).freeze
 
       attr_reader :event_id, :event_type, :timestamp, :context, :payload
 
@@ -68,6 +68,7 @@ module Chronos
         @safe_serializer = options[:safe_serializer] || SafeSerializer.new
         @max_payload_size = options[:max_payload_size] || proc { @config.max_payload_size }
         @runtime_info = RuntimeInfo.new
+        @correlation = options[:correlation] || CorrelationContext.new(config)
       end
 
       def call(event)
@@ -89,13 +90,39 @@ module Chronos
           "schema_version" => "1.0", "event_id" => event.event_id,
           "event_type" => event.event_type, "occurred_at" => event.timestamp,
           "sent_at" => @clock.call.utc.iso8601(6), "project_key" => @config.project_id,
-          "environment" => @config.environment,
-          "service" => {"name" => @config.service_name, "version" => @config.app_version,
-                        "instance_id" => runtime[:host]},
+          "environment" => event_environment(event),
+          "service" => event_service(event, runtime),
+          "correlation" => event_correlation(event, runtime),
           "runtime" => runtime[:runtime], "context" => event.context, "payload" => event.payload
         }
       end
 
+      def event_environment(event)
+        event.event_type == "deploy" ? event.payload["environment"] : @config.environment
+      end
+
+      def event_service(event, runtime)
+        deploy = event.event_type == "deploy" ? event.payload : {}
+        {
+          "name" => deploy["service"] || @config.service_name,
+          "version" => deploy["version"] || @config.app_version,
+          "instance_id" => deploy["instance"] || @config.instance_id || runtime[:host]
+        }
+      end
+
+      def event_correlation(event, runtime)
+        overrides = {"instance" => @config.instance_id || runtime[:host]}
+        if event.event_type == "deploy"
+          overrides.merge!(
+            "release" => event.payload["version"], "revision" => event.payload["revision"],
+            "deploy_id" => event.payload["deploy_id"], "environment" => event.payload["environment"],
+            "service" => event.payload["service"], "region" => event.payload["region"],
+            "instance" => event.payload["instance"]
+          )
+        end
+        @correlation.call(overrides)
+      end
+
       def compact_envelope(envelope)
         envelope["context"] = {"_truncated" => true}
         envelope["payload"] = {"_truncated" => true}

data/lib/chronos/integrations/capistrano.rb

@@ -0,0 +1,61 @@
+module Chronos
+  module Integrations
+    # Optional Capistrano task installer using only the public task DSL.
+    #
+    # @responsibility Register one post-publish task that delegates explicit values to notify_deploy.
+    # @motivation Legacy deployments need release reporting without a Capistrano runtime dependency.
+    # @limits Values are read only from configured Capistrano variables; Git and ENV are not inspected.
+    # @collaborators Capistrano/Rake DSL and the Chronos public facade.
+    # @thread_safety Installation is idempotent per DSL object before task execution.
+    # @compatibility Capistrano task DSLs available to supported Ruby 2.2.10 through Ruby 2.6 apps.
+    # @example
+    #   require "chronos/capistrano"
+    # @errors Missing DSL methods return false; notification failures are contained by Chronos.
+    # @performance Adds one task and one after hook; no background worker is created.
+    module Capistrano
+      INSTALLED_KEY = :@__chronos_capistrano_installed
+
+      class << self
+        def install(dsl)
+          return false if dsl.instance_variable_get(INSTALLED_KEY)
+          return false unless compatible?(dsl)
+
+          dsl.send(:namespace, :chronos) do
+            dsl.send(:desc, "Notify Chronos about the published deployment") if dsl.respond_to?(:desc, true)
+            dsl.send(:task, :notify_deploy) { notify(dsl) }
+          end
+          dsl.send(:after, "deploy:published", "chronos:notify_deploy")
+          dsl.instance_variable_set(INSTALLED_KEY, true)
+          true
+        rescue StandardError
+          false
+        end
+
+        def notify(dsl)
+          Chronos.notify_deploy(
+            :environment => value(dsl, :stage).to_s,
+            :revision => value(dsl, :current_revision) || value(dsl, :branch),
+            :version => value(dsl, :chronos_version) || value(dsl, :release_name),
+            :repository => value(dsl, :repo_url), :actor => value(dsl, :chronos_actor),
+            :deploy_id => value(dsl, :chronos_deploy_id), :service => value(dsl, :chronos_service),
+            :region => value(dsl, :chronos_region), :instance => value(dsl, :chronos_instance)
+          )
+        rescue StandardError
+          false
+        end
+
+        private
+
+        def compatible?(dsl)
+          [:namespace, :task, :after, :fetch].all? { |name| dsl.respond_to?(name, true) }
+        end
+
+        def value(dsl, name)
+          dsl.send(:fetch, name, nil)
+        rescue StandardError
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/chronos/observability_facade.rb

@@ -1,7 +1,7 @@
 module Chronos
-  # Public entry points for optional version 0.8 observability integrations.
+  # Public entry points for optional observability and deployment integrations.
   #
-  # @responsibility Delegate dependency, cache, and outbound HTTP integration calls to the agent.
+  # @responsibility Delegate dependency, cache, outbound HTTP, and deploy calls to the agent.
   # @motivation Keep the main public facade small while preserving one stable Chronos namespace.
   # @limits It installs only explicitly supplied Net::HTTP connections and never enables features.
   # @collaborators Chronos::Agent and Chronos::Integrations::NetHttp.
@@ -19,6 +19,13 @@ module Chronos
       false
     end
 
+    def notify_deploy(attributes = {}, timeout = Agent::DEFAULT_FLUSH_TIMEOUT)
+      agent = current_agent
+      agent ? agent.notify_deploy(attributes, timeout) : false
+    rescue StandardError
+      false
+    end
+
     def external_http_integration_options
       agent = current_agent
       agent ? agent.external_http_integration_options : {:enabled => false}

data/lib/chronos/version.rb

@@ -1,4 +1,4 @@
 module Chronos
   # Current version of the legacy Chronos Ruby agent.
-  VERSION = "0.8.0.pre.1".freeze
+  VERSION = "0.9.0.pre.1".freeze
 end

data/lib/chronos.rb

@@ -14,6 +14,8 @@ require "chronos/core/notice_builder"
 require "chronos/core/sensitive_value_filter"
 require "chronos/core/sanitizer"
 require "chronos/core/safe_serializer"
+require "chronos/core/correlation_context"
+require "chronos/core/deploy_normalizer"
 require "chronos/core/payload_serializer"
 require "chronos/core/telemetry_event"
 require "chronos/core/sql_normalizer"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: chronos-ruby
 version: !ruby/object:Gem::Version
-  version: 0.8.0.pre.1
+  version: 0.9.0.pre.1
 platform: ruby
 authors:
 - Antonio Jefferson
@@ -88,6 +88,7 @@ files:
 - SECURITY.md
 - contracts/apm-batch-v1.schema.json
 - contracts/dependencies-v1.schema.json
+- contracts/deploy-v1.schema.json
 - contracts/event-v1.schema.json
 - contracts/rack-context-v1.schema.json
 - contracts/sidekiq-job-v1.schema.json
@@ -103,6 +104,7 @@ files:
 - docs/adr/ADR-014-sidekiq-envelope-context.md
 - docs/adr/ADR-015-bounded-apm-aggregation.md
 - docs/adr/ADR-016-explicit-observability-integrations.md
+- docs/adr/ADR-017-deploy-events-and-correlation.md
 - docs/architecture.md
 - docs/compatibility.md
 - docs/configuration.md
@@ -113,6 +115,7 @@ files:
 - docs/modules/cache-observability.md
 - docs/modules/configuration.md
 - docs/modules/dependencies.md
+- docs/modules/deploy-tracking.md
 - docs/modules/external-http.md
 - docs/modules/notice-pipeline.md
 - docs/modules/rack-context.md
@@ -142,6 +145,7 @@ files:
 - lib/chronos/application/dependency_reporter.rb
 - lib/chronos/application/remote_configuration.rb
 - lib/chronos/application/retry_policy.rb
+- lib/chronos/capistrano.rb
 - lib/chronos/configuration.rb
 - lib/chronos/configuration/apm_validation.rb
 - lib/chronos/configuration/snapshot.rb
@@ -150,6 +154,8 @@ files:
 - lib/chronos/core/backtrace_parser.rb
 - lib/chronos/core/breadcrumb.rb
 - lib/chronos/core/cache_normalizer.rb
+- lib/chronos/core/correlation_context.rb
+- lib/chronos/core/deploy_normalizer.rb
 - lib/chronos/core/exception_cause_collector.rb
 - lib/chronos/core/metric_aggregate.rb
 - lib/chronos/core/notice.rb
@@ -163,6 +169,7 @@ files:
 - lib/chronos/core/telemetry_event.rb
 - lib/chronos/errors.rb
 - lib/chronos/integrations.rb
+- lib/chronos/integrations/capistrano.rb
 - lib/chronos/integrations/job_payload.rb
 - lib/chronos/integrations/net_http.rb
 - lib/chronos/integrations/rack.rb