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

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b9cf448c12955078e3a714df2d41bcd94d89f840fea406dc6595f72661e8abc2
-  data.tar.gz: 1401d283792e930caa252b21191de3d8fcc02bf5b2936416ed28eec2e319dab3
+  metadata.gz: 44c7cad424497d7998727de5a916594ecc3ce9dfda7580376fe4a754edd9096e
+  data.tar.gz: 3f7a64cbf5b5879e107d7102c1f72cdd2ac4c941e1640a05b6210db79cd948f9
 SHA512:
-  metadata.gz: 43f80510ce3d78e6c9b4b571f7d79cb66b8a4fad8f36b66996ea5cc42868c6ec7b1a05ae1556c8442569787f2f350e2884a779e36af649734eced377396c892b
-  data.tar.gz: 30b0f93cfba0ce2fb856b4c65eff6e1ebfa906c8c45ec5c6e287ddc080bc23bd63e4e1a7a4d80a56f40b5001c768719c3b52a2d7e9b08d08b39a2512b476db30
+  metadata.gz: f62fa57bfcfec70f7172afc4c939d905aa9c7d9215960b73fa0c54406568b43b93e41b02ba22eb13b381243e06cf61a087544db00ed97ea4ce5805f84e9901e7
+  data.tar.gz: 3a66ec4e2a85f7f2e79868523fe63a493aeb598aff810dfd21b84a25dd0505e21ee66cac35a7113927a9b4b5a5c5ea2f41d25b89b452b38088c0ef3570f876bf

data/CHANGELOG.md

@@ -12,6 +12,30 @@ 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.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.8 adds optional per-instance outbound `Net::HTTP` timing, privacy-safe cache identity, and one bounded dependency inventory per agent.
 
 ## What the gem collects
 
-For each exception, version 0.7 can collect:
+Version 0.8 can collect:
 
 - exception class, message, structured backtrace, and chained causes;
 - timestamp, severity, tags, and an optional fingerprint;
@@ -18,7 +18,7 @@ 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 +31,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.8.0.pre.1"
 ```
 
 Install with a Bundler version compatible with the application. For the oldest supported runtime:
@@ -52,7 +52,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.8.0.pre.1", :require => "chronos/rails"
 ```
 
 Generate the initializer with:
@@ -191,16 +191,36 @@ 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.8.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.
+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.
 
 ## Asynchronous queue
 
@@ -273,6 +293,9 @@ 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
 end
 ```
 
@@ -284,7 +307,7 @@ Configuration errors are raised during `Chronos.configure`. Capture and delivery
 
 ## Benchmark
 
-Run the version 0.7 benchmarks with:
+Run the version 0.8 benchmarks with:
 
 ```bash
 bundle _1.17.3_ exec ruby benchmarks/capture_exception.rb
@@ -296,13 +319,14 @@ 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
 ```
 
 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.8 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/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", "metric_batch"]},
     "occurred_at": {"type": "string"},
     "sent_at": {"type": "string"},
     "project_key": {"type": "string", "minLength": 1},

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/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.8 uses hexagonal boundaries so the legacy core remains independent of frameworks and delivery infrastructure.
 
 ```mermaid
 flowchart TB
@@ -21,6 +21,9 @@ 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]
 ```
 
 ## Boundaries
@@ -50,6 +53,8 @@ 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.
+
 ## 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,8 @@ 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.
+
 Status meanings:
 
 - Supported: the complete required compatibility gate passes.

data/docs/configuration.md

@@ -39,7 +39,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, 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 +48,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 +57,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|
@@ -84,6 +89,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
 ```
 

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.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.
 
 | Data | Default | Source |
 |---|---|---|
@@ -34,14 +34,19 @@ 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` |
 
-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, 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.
 
 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,10 @@ 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
+```
+
+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.

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,5 @@ 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).

data/docs/modules/dependencies.md

@@ -0,0 +1,18 @@
+# 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.
+
+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 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.

data/docs/modules/external-http.md

@@ -0,0 +1,27 @@
+# External HTTP instrumentation
+
+Version `0.8.0.pre.1` provides an optional `Net::HTTP` wrapper loaded through `chronos/net_http`. It is disabled by default and prepended only to a connection object explicitly passed to `Chronos.instrument_net_http`; the `Net::HTTP` class and unrelated instances are unchanged.
+
+```ruby
+require "net/http"
+require "chronos"
+
+Chronos.configure do |config|
+  # 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)
+response = http.request(Net::HTTP::Get.new("/health"))
+```
+
+The event contains a bounded lowercase host, uppercase method, response status, monotonic duration, timeout flag, connection-error flag, and error class. A request made inside a Chronos context receives `X-Chronos-Trace-ID` and `X-Chronos-Request-ID` unless the application already set those headers. Disable propagation with `external_http_trace_headers = false`.
+
+The wrapper never reads or records the path, query string, Authorization, other request headers, request body, response headers/body, or exception message. The native streaming block is forwarded and the identical HTTP exception is re-raised. Telemetry failures are contained.
+
+Successful and failed calls become bounded `external_http` APM groups keyed only by host and method. A call carrying a trace ID contributes its duration to the enclosing request's `external_http` breakdown. Faraday, HTTP.rb, Excon, and RestClient are outside this release.
+
+Installation is idempotent per object. A `false` result means collection is disabled, the object is incompatible or already instrumented, or installation was contained after an internal error.

data/docs/modules/rails-legacy.md

@@ -29,7 +29,7 @@ The public `ActiveSupport::Notifications.subscribe` API is used for:
 | `sql.active_record` | `query` | operation name, cached flag, and duration |
 | `deliver.action_mailer` | `job` with `kind=mailer` | mailer, action, and duration |
 | `perform.active_job` | `job` | job class, queue, and duration, when Active Job is available |
-| cache read/write/hit notifications | `cache` | operation, store, hit flag, and duration |
+| cache read/write/hit notifications | `cache` | operation, backend, namespace, hit/miss, duration, and optional scoped key hash |
 
 Raw SQL, binds, cache keys, mail recipients and bodies, job IDs and arguments, request/response bodies, cookies, and authorization headers are not copied. Template identifiers are reduced to their basename. Every event passes through `Sanitizer`, `SafeSerializer`, the bounded queue, retry policy, circuit breaker, and memory backlog.
 

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.7.0.pre.1", :require => "chronos/sidekiq"
+gem "chronos-ruby", "0.8.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,9 @@
 # Framework telemetry events
 
-`Chronos::Core::TelemetryEvent` and `Chronos::Core::TelemetrySerializer` extend the v1 envelope to `request`, `query`, `job`, and `cache` events. These values exist so framework adapters do not model operational timings as fake exceptions.
+`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.
 
 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.7 aggregates request, query, and job observations into `metric_batch` events by default. Cache remains an individual event while contributing to an existing traced request breakdown. Set `apm_enabled = false` only when individual legacy telemetry is required for diagnostics. Percentiles remain server-side; see [Essential APM aggregation](apm-aggregation.md).
+Version 0.8 aggregates request, query, job, and enabled external HTTP observations into `metric_batch` events by default. Cache remains an individual event while contributing to an existing traced request breakdown. Dependencies use one separate event per agent. Set `apm_enabled = false` only when individual legacy telemetry is required for diagnostics. Percentiles remain server-side; see [Essential APM aggregation](apm-aggregation.md).

data/docs/performance.md

@@ -1,6 +1,6 @@
 # Performance
 
-Performance is a functional requirement, but version 0.7 makes no unverified speed claim.
+Performance is a functional requirement, but version 0.8 makes no unverified speed claim.
 
 Current controls:
 
@@ -21,6 +21,9 @@ Current controls:
 - Rails subscribers copy only small allowlisted field sets and never copy raw SQL or job arguments.
 - Sidekiq middleware creates no per-job thread or connection and bounds arguments, collections, nesting, strings, and tags before telemetry capture.
 - APM group, trace, query-fingerprint, histogram, and batch counts are fixed; no APM timer thread is created.
+- 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.
 
 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.
 
@@ -100,3 +103,15 @@ ITERATIONS=100000 bundle _1.17.3_ exec ruby benchmarks/apm_aggregation.rb
 The fixture repeatedly updates one SQL metric group and one trace-local fingerprint. It excludes ActiveSupport dispatch, serialization, queueing, and network delivery. The benchmark must report one retained group; memory must remain bounded by configuration. Record runtime, hardware, warmup, median, and dispersion before publishing a performance claim.
 
 A local diagnostic run on 2026-07-20 used Ruby 2.2.10 on macOS arm64 and 10,000 observations. It retained one group and measured approximately 34.972 microseconds per observation. This single run has no controlled warmup, median, or dispersion and is not a production performance claim.
+
+## Version 0.8 external HTTP benchmark
+
+Run:
+
+```bash
+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.

data/docs/privacy-lgpd.md

@@ -1,6 +1,6 @@
 # Privacy and LGPD
 
-Version 0.7 sanitizes exception, framework telemetry, 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.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.
 
 ## Default policy
 
@@ -16,8 +16,17 @@ Version 0.7 sanitizes exception, framework telemetry, and APM metric batches bef
 | Request/response bodies, raw query strings, cookies, authorization headers, raw SQL/binds, cache values, mail bodies, environment variables | Never collected automatically |
 | Sidekiq arguments | Collected automatically, limited before sanitization, then redacted by the common policy |
 | SQL | Comments, quoted/numeric/boolean/null literals removed; binds never read; bounded identifiers remain |
+| 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 |
 
-The retry backlog exists only in process memory, accepts only `SerializedEvent`, has a fixed capacity, and disappears on process exit. Version 0.7 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.8 does not persist telemetry to disk.
+
+## External services, cache, and dependencies
+
+Outbound HTTP instrumentation is disabled by default and installed per connection. Trace headers reveal correlation identifiers to the selected destination; enable propagation only for destinations permitted to receive them. The wrapper does not inspect any other header or URL component.
+
+Raw cache keys can contain user or business data and are never delivered. Optional hashing is pseudonymization, not anonymization: predictable low-entropy keys can still be guessed. Dependency reporting is a separate once-per-agent event, never copied into exceptions, and can be disabled. It reads loaded gem name/version pairs only, with no filesystem path, source, configuration, or complete lockfile.
 
 ## Rails telemetry
 

data/docs/troubleshooting.md

@@ -22,7 +22,19 @@ Require `chronos/rails` from the generated initializer and confirm it runs befor
 
 ## Rails telemetry contains no SQL or cache key
 
-This is intentional. Version 0.5 records SQL operation name/duration and cache operation/store/hit status without raw statements, binds, keys, or values. These omissions are privacy and cardinality boundaries, not capture failures.
+This is intentional. Chronos records bounded SQL and cache operational metadata without raw statements, binds, keys, or values. Set `cache_key_mode = :sha256` before configuration only when a stable pseudonymous key identity is required.
+
+## External HTTP telemetry is missing
+
+Set `external_http_enabled = true`, then call `Chronos.instrument_net_http(http)` for each `Net::HTTP` instance after Chronos is configured. Existing and future objects are not patched globally. The method returns `false` when disabled, already installed, incompatible, or unconfigured.
+
+## Trace headers should not reach a destination
+
+Set `external_http_trace_headers = false` before configuring the agent, or do not instrument that connection. Chronos preserves an application-supplied Chronos header instead of overwriting it.
+
+## Dependency inventory is missing or incomplete
+
+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.
 
 ## Sidekiq telemetry is missing