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

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b9cf448c12955078e3a714df2d41bcd94d89f840fea406dc6595f72661e8abc2
-  data.tar.gz: 1401d283792e930caa252b21191de3d8fcc02bf5b2936416ed28eec2e319dab3
+  metadata.gz: 34b5d9d1193017931d129dc366922b276d9b85ced0321e78d3f4a5b1a8c13e40
+  data.tar.gz: 72277b74f51825118ce6cb2dda83652f035bbfef3cb56c18b7ee98cc3e6d1d54
 SHA512:
-  metadata.gz: 43f80510ce3d78e6c9b4b571f7d79cb66b8a4fad8f36b66996ea5cc42868c6ec7b1a05ae1556c8442569787f2f350e2884a779e36af649734eced377396c892b
-  data.tar.gz: 30b0f93cfba0ce2fb856b4c65eff6e1ebfa906c8c45ec5c6e287ddc080bc23bd63e4e1a7a4d80a56f40b5001c768719c3b52a2d7e9b08d08b39a2512b476db30
+  metadata.gz: 2c6b44a856bbb8975c6a4dc9aba5d9bcd2cf9a9d44456c19fe373860872491ff310f11a2a1b4c7588306ae2795caf4af8cf008e38c10bcdbe0322fca9a803ece
+  data.tar.gz: c4ff3f4da09810013c0e4d352bb18cd04c0a652c160816465d4b088490d5eea5f722c326ab8a6dcc9806f7b74c050ee0c77e8c6a4c604ddf650cb08fc66a3fd4

data/CHANGELOG.md

@@ -12,6 +12,55 @@ 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
+
+- optional per-instance `Net::HTTP` instrumentation with sanitized host, method, status, duration, timeout and connection-error classification;
+- outbound trace/request header propagation without collecting URLs, Authorization, request bodies, response bodies, or error messages;
+- external HTTP metric aggregation and traced-request `external_http` breakdown;
+- cache operation, duration, hit/miss, backend, namespace, and opt-in project-scoped SHA-256 key identity;
+- bounded dependency inventory containing loaded gem versions, Ruby, optional Rails/web server/database/Sidekiq detection, and configured release;
+- version 0.8 configuration, contracts, tests, executable example, benchmark, module documentation, and ADR-016.
+
+### Changed
+
+- dependency inventory is queued at most once per configured agent instead of being attached to every exception;
+- cache notification fields now use bounded backend/namespace/outcome names and omit raw keys by default;
+- version advanced to `0.8.0.pre.1`.
+
+### Known limitations
+
+- outbound HTTP instrumentation must be enabled and installed on each selected `Net::HTTP` instance;
+- Faraday, HTTP.rb, Excon, and RestClient adapters are not included;
+- cache key hashing is opt-in and low-entropy keys may remain guessable;
+- dependency detection uses already loaded gems and does not open a database connection or inspect lockfiles.
+
 ## [0.7.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.7 adds bounded essential APM aggregation for requests, SQL, and jobs, including histograms, error rates, component breakdown, normalized SQL fingerprints, and local diagnostic signals.
+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
 
-For each exception, version 0.7 can collect:
+Version 0.9 can collect:
 
 - exception class, message, structured backtrace, and chained causes;
 - timestamp, severity, tags, and an optional fingerprint;
@@ -13,12 +13,14 @@ For each exception, version 0.7 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.
 
 ## What is not collected by default
 
-Chronos Ruby does not inspect environment variables, request bodies, cookies, HTTP headers, source code, database contents, or installed gems. Application-supplied fields are recursively sanitized, but applications should still avoid sending unnecessary personal, health, financial, or authentication data.
+Chronos Ruby does not inspect environment variables, request/response bodies, cookies, Authorization headers, source code, database contents, lockfiles, or gem paths. Dependency reporting reads only already loaded gem names and versions once per agent. Application-supplied fields are recursively sanitized, but applications should still avoid sending unnecessary personal, health, financial, or authentication data.
 
 ## Supported Ruby and Rails versions
 
@@ -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.7.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.7.0.pre.1", :require => "chronos/rails"
+gem "chronos-ruby", "0.9.0.pre.1", :require => "chronos/rails"
 ```
 
 Generate the initializer with:
@@ -191,16 +193,50 @@ Version `0.6.0.pre.1` adds optional Sidekiq 4/5 middleware:
 
 ```ruby
 gem "sidekiq", "~> 5.0"
-gem "chronos-ruby", "0.7.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).
 
 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.
 
+## External HTTP, cache, and dependencies
+
+Version 0.8 instruments only explicitly selected `Net::HTTP` connection objects, avoiding a global monkey patch:
+
+```ruby
+Chronos.configure do |config|
+  # required connection settings omitted
+  config.external_http_enabled = true
+  config.external_http_trace_headers = true
+end
+
+http = Net::HTTP.new("payments.example.com", 443)
+http.use_ssl = true
+Chronos.instrument_net_http(http)
+```
+
+The wrapper records only sanitized host, method, status, duration, timeout, connection-error flag, and error class. It propagates `X-Chronos-Trace-ID` and `X-Chronos-Request-ID` when available and never reads URL path/query, Authorization, request body, response body, or error message.
+
+Rails cache telemetry omits raw keys by default. Set `cache_key_mode = :sha256` to emit a project-scoped hash; `:none` is the default. Dependency reporting is enabled by default, reads at most 100 already loaded gem specs, and emits one independent `dependencies` event per agent. Set `dependency_reporting = false` to disable it. See [External HTTP](docs/modules/external-http.md), [Cache observability](docs/modules/cache-observability.md), and [Dependency inventory](docs/modules/dependencies.md).
+
 ## Deploy tracking
 
-Deploy notifications are not implemented in version 0.4. `app_version` may be included in exception events 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
 
@@ -273,6 +309,14 @@ Chronos.configure do |config|
   config.apm_enabled = true
   config.apm_max_groups = 200
   config.apm_flush_count = 100
+  config.external_http_enabled = false
+  config.cache_key_mode = :none
+  config.dependency_reporting = true
+  config.app_version = ENV["APP_VERSION"]
+  config.revision = ENV["GIT_SHA"]
+  config.deploy_id = ENV["DEPLOY_ID"]
+  config.region = ENV["REGION"]
+  config.instance_id = ENV["INSTANCE_ID"]
 end
 ```
 
@@ -284,7 +328,7 @@ Configuration errors are raised during `Chronos.configure`. Capture and delivery
 
 ## Benchmark
 
-Run the version 0.7 benchmarks with:
+Run the version 0.9 benchmarks with:
 
 ```bash
 bundle _1.17.3_ exec ruby benchmarks/capture_exception.rb
@@ -296,13 +340,15 @@ bundle _1.17.3_ exec ruby benchmarks/request_overhead.rb
 bundle _1.17.3_ exec ruby benchmarks/rails_notifications.rb
 bundle _1.17.3_ exec ruby benchmarks/sidekiq_middleware.rb
 bundle _1.17.3_ exec ruby benchmarks/apm_aggregation.rb
+bundle _1.17.3_ exec ruby benchmarks/external_http.rb
+bundle _1.17.3_ exec ruby benchmarks/correlation.rb
 ```
 
 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.7 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/apm-batch-v1.schema.json

@@ -15,7 +15,7 @@
         "type": "object",
         "required": ["metric_type", "dimensions", "count", "error_count", "error_rate", "duration_ms", "histogram", "breakdown_ms", "signals", "status_codes"],
         "properties": {
-          "metric_type": {"enum": ["request", "query", "job"]},
+          "metric_type": {"enum": ["request", "query", "job", "external_http"]},
           "dimensions": {"type": "object"},
           "count": {"type": "integer", "minimum": 1},
           "error_count": {"type": "integer", "minimum": 0},

data/contracts/dependencies-v1.schema.json

@@ -0,0 +1,38 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://chronos.example/schemas/dependencies-v1.schema.json",
+  "title": "Chronos dependency inventory payload v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["dependencies", "ruby"],
+  "properties": {
+    "dependencies": {
+      "type": "array",
+      "maxItems": 200,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["name", "version"],
+        "properties": {
+          "name": {"type": "string", "maxLength": 128},
+          "version": {"type": "string", "maxLength": 64}
+        }
+      }
+    },
+    "ruby": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["version", "engine", "platform"],
+      "properties": {
+        "version": {"type": "string", "maxLength": 64},
+        "engine": {"type": "string", "maxLength": 64},
+        "platform": {"type": "string", "maxLength": 128}
+      }
+    },
+    "rails": {"type": ["string", "null"], "maxLength": 128},
+    "web_server": {"type": ["string", "null"], "maxLength": 128},
+    "database_adapter": {"type": ["string", "null"], "maxLength": 128},
+    "sidekiq": {"type": ["string", "null"], "maxLength": 128},
+    "release": {"type": ["string", "null"], "maxLength": 128}
+  }
+}

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", "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-016-explicit-observability-integrations.md

@@ -0,0 +1,25 @@
+# ADR-016 — Explicit and privacy-bounded observability integrations
+
+## Status
+
+Accepted for version 0.8.
+
+## Context
+
+Outbound calls, cache behavior, and runtime dependencies materially improve diagnosis, but global HTTP monkey patches and raw cache/dependency data create compatibility, cardinality, and privacy risks in legacy applications.
+
+## Decision
+
+Instrument only explicitly supplied `Net::HTTP` instances with a per-object prepended module. Preserve method, streaming block, response, and exception semantics. Collect only bounded host/outcome/timing fields and propagate only Chronos correlation headers.
+
+Normalize Rails cache notifications through a core value normalizer. Omit raw keys by default and permit only an explicit project-scoped SHA-256 mode. Never inspect values.
+
+Build one bounded dependency event per agent from already loaded gem specs and feature-detected constants. Do not inspect lockfiles or paths, activate dependencies, or open database connections. Route every event through the existing sanitizer, bounded queue, retry, circuit breaker, and backlog pipeline.
+
+## Alternatives
+
+A global `Net::HTTP` patch was rejected because it changes unrelated connections and increases conflict risk. Capturing full URLs, headers, bodies, cache keys, or lockfiles was rejected for privacy and cardinality. Attaching dependencies to every exception was rejected for redundant payload cost. Automatic Faraday and other client adapters were deferred until demand and official middleware boundaries are validated.
+
+## Consequences
+
+Applications choose exactly which HTTP clients are instrumented, native errors remain intact, and memory/data volume stay bounded. The tradeoffs are explicit setup per connection, partial dependency inventories when gems load late, pseudonymous rather than anonymous cache hashes, and no coverage for other HTTP clients in this release.

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.7 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
@@ -21,6 +21,11 @@ flowchart TB
   Application --> Telemetry[Core / TelemetryEvent]
   Telemetry --> APM[Application / ApmAggregator]
   APM --> Metrics[Core / MetricAggregate and SqlNormalizer]
+  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
@@ -50,6 +55,12 @@ Sidekiq client middleware writes a versioned, allowlisted trace/request context
 
 Version 0.7 routes request, query, and job observations through `ApmAggregator`. `SqlNormalizer` removes values before grouping, while `MetricAggregate` owns fixed numerical statistics. Aggregates and per-trace query trackers are bounded and mutex-protected. Threshold or lifecycle drains create `metric_batch` telemetry that passes through the existing sanitizer and delivery pipeline. No APM-specific thread is created.
 
+Version 0.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

@@ -21,6 +21,10 @@ Version `0.6.0.pre.1` uses the public Sidekiq 4/5 middleware signatures and rema
 
 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 |
@@ -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, 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 |
@@ -48,7 +52,7 @@
 | `rails_capture_in_console` | Optional | `false` | Enables automatic integration while Rails console is loaded |
 | `rails_capture_in_test` | Optional | `false` | Enables automatic integration in the Rails test environment |
 | `rails_capture_user_agent` | Optional | `false` | Adds the Rack user agent to request context |
-| `apm_enabled` | Optional | `true` | Aggregates request, query, and job observations into bounded metric batches |
+| `apm_enabled` | Optional | `true` | Aggregates request, query, job, and enabled external HTTP observations into bounded metric batches |
 | `apm_max_groups` | Optional | `200` | Maximum metric groups and active trace trackers retained locally |
 | `apm_flush_count` | Optional | `100` | Aggregate observations accepted before a threshold drain |
 | `apm_batch_size` | Optional | `50` | Metric groups per batch; hard maximum 50 |
@@ -57,6 +61,11 @@
 | `apm_long_transaction_threshold_ms` | Optional | `1000.0` | Transaction-labelled SQL duration that produces a signal |
 | `apm_n_plus_one_threshold` | Optional | `5` | Repeated fingerprint count producing one possible-N+1 signal; minimum 2 |
 | `apm_histogram_buckets` | Optional | Fixed millisecond boundaries | Increasing positive duration boundaries; at most 19 plus `+Inf` |
+| `external_http_enabled` | Optional | `false` | Allows explicit per-instance outbound `Net::HTTP` instrumentation |
+| `external_http_trace_headers` | Optional | `true` | Propagates Chronos trace/request headers on instrumented requests |
+| `cache_key_mode` | Optional | `:none` | `:none` omits keys; `:sha256` emits a project-scoped key hash |
+| `dependency_reporting` | Optional | `true` | Emits one bounded dependency event per configured agent |
+| `dependency_max_items` | Optional | `100` | Loaded gem entries retained in the inventory; range 1–200 |
 
 ```ruby
 Chronos.configure do |config|
@@ -65,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]
@@ -84,6 +98,11 @@ Chronos.configure do |config|
   config.apm_slow_query_threshold_ms = 500.0
   config.apm_long_transaction_threshold_ms = 1000.0
   config.apm_n_plus_one_threshold = 5
+  config.external_http_enabled = false
+  config.external_http_trace_headers = true
+  config.cache_key_mode = :none
+  config.dependency_reporting = true
+  config.dependency_max_items = 100
 end
 ```
 
@@ -92,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.7 emits exceptions, individual cache telemetry, and aggregated request/query/job 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 |
 |---|---|---|
@@ -34,14 +34,21 @@ Version 0.7 emits exceptions, individual cache telemetry, and aggregated request
 | Sidekiq trace/request IDs | Propagated when present; trace generated otherwise | Chronos job-envelope metadata |
 | APM counts, error counts/rates, duration total/min/max/average | Aggregated by default | Request, query, and job observations |
 | Fixed duration histogram and status counts | Aggregated by default | Local bounded counters |
-| Component breakdown | database/view/cache/queue/application when observable | Trace-local bounded totals |
+| Component breakdown | database/view/external_http/cache/queue/application when observable | Trace-local bounded totals |
 | Normalized SQL and SHA-256 fingerprint | Collected without comments, literals, or binds | `sql.active_record` payload |
 | SQL adapter, operation, inferred table, AR name, cache flag, role/shard | Collected when exposed | Public notification payload and connection feature detection |
 | Slow SQL source frame | Collected only for threshold-selected slow queries | Bounded application call frame |
 | APM diagnostic signals | Heuristic counters | Local threshold and repetition detection |
-| Cache operation, store, hit flag, duration | Collected; key/value omitted | ActiveSupport cache notifications |
+| External HTTP host, method, status, duration, timeout, connection-error flag, error class | Disabled by default; per-instance opt-in | Instrumented `Net::HTTP` object |
+| Chronos trace/request headers | Propagated when available | Current execution context |
+| Cache operation, backend, namespace, hit/miss, duration | Collected; key/value omitted | ActiveSupport cache notifications |
+| 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, cache keys/values, mail bodies/recipients, or installed gems. Sidekiq JIDs and bounded arguments are the explicit version 0.6 exception to the earlier job-ID/argument exclusion.
+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

@@ -23,4 +23,16 @@ For a network-free outage and bounded-backlog example, run:
 bundle _1.17.3_ exec ruby examples/plain-ruby/resilient_delivery.rb
 ```
 
-The example builds the final event locally and demonstrates key redaction, e-mail and Bearer-token detection, application-specific blocklisting, and identifier hashing.
+For network-free per-instance outbound HTTP instrumentation, run:
+
+```bash
+bundle _1.17.3_ exec ruby examples/plain-ruby/external_http.rb
+```
+
+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/apm-aggregation.md

@@ -1,6 +1,6 @@
 # Essential APM aggregation
 
-Version `0.7.0.pre.1` aggregates request, SQL, and job observations locally before delivery. The agent emits versioned `metric_batch` envelopes containing at most 50 metric groups instead of one event per observation. Aggregates drain when `apm_flush_count` observations are reached and whenever `Chronos.flush` or `Chronos.close` runs. No timer or additional APM thread is created.
+Version `0.8.0.pre.1` aggregates request, SQL, job, and explicitly instrumented external HTTP observations locally before delivery. The agent emits versioned `metric_batch` envelopes containing at most 50 metric groups instead of one event per observation. Aggregates drain when `apm_flush_count` observations are reached and whenever `Chronos.flush` or `Chronos.close` runs. No timer or additional APM thread is created.
 
 ## Request metrics
 
@@ -35,7 +35,7 @@ New groups beyond capacity are dropped and counted in `dropped_groups`. Existing
 
 ## Breakdown
 
-The contract supports `database`, `view`, `external_http`, `cache`, `queue`, `application`, and `unknown`. Version 0.7 fills database/view/cache within a traced request, queue/application for jobs, and residual application time for requests. External HTTP instrumentation begins in version 0.8.
+The contract supports `database`, `view`, `external_http`, `cache`, `queue`, `application`, and `unknown`. Version 0.8 fills external HTTP time for explicitly instrumented calls inside a traced request, in addition to database/view/cache, queue/application for jobs, and residual application request time.
 
 ## Configuration
 

data/docs/modules/cache-observability.md

@@ -0,0 +1,16 @@
+# Cache observability
+
+Rails ActiveSupport cache notifications produce individual bounded `cache` events containing operation, duration, hit/miss outcome, backend, and namespace. When a trace is active, duration also contributes to the request's cache breakdown.
+
+Raw cache keys and values are never delivered. The default `cache_key_mode = :none` omits key identity entirely. Applications that need correlation can opt into a project-scoped SHA-256 value:
+
+```ruby
+Chronos.configure do |config|
+  # connection settings omitted
+  config.cache_key_mode = :sha256
+end
+```
+
+Hashing accepts at most 2,048 bytes of key text and emits a fixed 64-character hexadecimal value. It is pseudonymization rather than anonymization: an attacker who can guess a low-entropy key may reproduce candidate hashes when project scope is known. Do not encode credentials or unnecessary personal data in cache keys.
+
+The normalizer never calls cache read/write APIs, inspects cached values, or retains keys. Unsupported or incomplete notification payloads become an `unknown` outcome without raising into Rails.

data/docs/modules/configuration.md

@@ -9,3 +9,7 @@ Risks include accidentally logging credentials and changing settings while event
 Tests in `spec/unit/configuration_spec.rb` verify required fields, HTTPS defaults, immutable containers, disabled operation, and bounded numeric settings.
 
 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

@@ -0,0 +1,18 @@
+# Dependency inventory
+
+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.
+
+```ruby
+Chronos.configure do |config|
+  # connection settings omitted
+  config.dependency_reporting = true
+  config.dependency_max_items = 100
+end
+
+# Optional after application boot, before the first regular event:
+Chronos.report_dependencies
+```
+
+`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.