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

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5ad7bc09dd58b0476b65687d0b7c695bdc5e82c898f882fc82ed2e87eb352b79
-  data.tar.gz: 527383d76a4432bc16f48d2a476d7c2398d66f5b891bbe666d1e0ceba9dc9959
+  metadata.gz: 44c7cad424497d7998727de5a916594ecc3ce9dfda7580376fe4a754edd9096e
+  data.tar.gz: 3f7a64cbf5b5879e107d7102c1f72cdd2ac4c941e1640a05b6210db79cd948f9
 SHA512:
-  metadata.gz: 24bf5ed37de64c34a82fd0b98f3e1323cac14c2392fa0d6a01dbcd24d48a69a52100a6127a79b2567314bcf2c464b354fee226ab19bba08ea384bfb3ec8a12f9
-  data.tar.gz: 1696953512893c9d3eecc23d361b35c5434df7dda25e33a1fe6321b5c25ae4d9e03a2a843bd76e9c327130be2cba2a6c7a9766d70a6f068007b24959aa3cfdc0
+  metadata.gz: f62fa57bfcfec70f7172afc4c939d905aa9c7d9215960b73fa0c54406568b43b93e41b02ba22eb13b381243e06cf61a087544db00ed97ea4ce5805f84e9901e7
+  data.tar.gz: 3a66ec4e2a85f7f2e79868523fe63a493aeb598aff810dfd21b84a25dd0505e21ee66cac35a7113927a9b4b5a5c5ea2f41d25b89b452b38088c0ef3570f876bf

data/CHANGELOG.md

@@ -12,6 +12,54 @@ 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
+
+- bounded local request, SQL, and job aggregation with count, error rate, duration statistics, histograms, status codes, and component breakdown;
+- `metric_batch` v1 payloads containing at most 50 sanitized metric groups;
+- bounded SQL normalization, fingerprinting, adapter/operation/table/name/cache/role/shard dimensions, and sampled slow-query source;
+- heuristic slow-query, repeated-query, possible N+1, long-transaction, connection-error, and deadlock signals;
+- generic Rack request metrics with Rails/Rack deduplication;
+- APM configuration, diagnostics, contracts, tests, example, benchmark, module documentation, and ADR-015.
+
+### Changed
+
+- request, query, and job observations aggregate by default instead of producing one delivery event each;
+- `Chronos.flush` and `Chronos.close` drain APM aggregates before delivery shutdown;
+- version advanced to `0.7.0.pre.1`.
+
+### Known limitations
+
+- local signals are heuristic and require server-side confirmation;
+- incomplete trace trackers are cleared when aggregates drain;
+- normalized SQL is defensive rather than a complete dialect parser;
+- external HTTP breakdown remains version 0.8 scope.
+
 ## [0.6.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.6 starts legacy worker support with Sidekiq 4/5 middleware, cross-process trace context, bounded job telemetry, and exception deduplication on top of the Rails, Rack, privacy, and resilience foundations from earlier releases.
+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.6 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.6.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.6.0.pre.1", :require => "chronos/rails"
+gem "chronos-ruby", "0.8.0.pre.1", :require => "chronos/rails"
 ```
 
 Generate the initializer with:
@@ -168,7 +168,22 @@ Local exception-specific ignore callbacks are not available in version 0.4. The
 
 ## Performance monitoring
 
-Version 0.5 emits bounded `request`, `query`, `job`, and `cache` events from public Rails notifications. SQL text and binds, cache keys and values, job arguments, mail content and recipients, and request or response bodies are never copied. Aggregation, percentiles, query fingerprints, and external HTTP monitoring are not implemented in this version.
+Version 0.7 aggregates request, query, and job observations into bounded `metric_batch` events. Groups include count, error count/rate, total/min/max/average duration, fixed histogram buckets, status counts, and component breakdown. Percentiles are calculated in the SaaS without retaining every local duration.
+
+SQL comments and literal values are removed before a bounded normalized query and SHA-256 fingerprint are produced. Binds are never read. Slow, repeated, possible N+1, long-transaction, connection-error, and deadlock signals are heuristic and require server-side confirmation. Group count, active trace count, fingerprints per trace, histogram buckets, and batch size all have fixed limits. See [Essential APM aggregation](docs/modules/apm-aggregation.md).
+
+```ruby
+Chronos.configure do |config|
+  # required connection settings omitted
+  config.apm_enabled = true
+  config.apm_max_groups = 200
+  config.apm_flush_count = 100
+  config.apm_batch_size = 50
+  config.apm_max_queries_per_request = 100
+  config.apm_slow_query_threshold_ms = 500.0
+  config.apm_n_plus_one_threshold = 5
+end
+```
 
 ## Sidekiq and Active Job
 
@@ -176,16 +191,36 @@ Version `0.6.0.pre.1` adds optional Sidekiq 4/5 middleware:
 
 ```ruby
 gem "sidekiq", "~> 5.0"
-gem "chronos-ruby", "0.6.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
 
@@ -255,6 +290,12 @@ Chronos.configure do |config|
   config.context_store = :thread_local
   config.breadcrumb_capacity = 20
   config.breadcrumb_max_bytes = 2048
+  config.apm_enabled = true
+  config.apm_max_groups = 200
+  config.apm_flush_count = 100
+  config.external_http_enabled = false
+  config.cache_key_mode = :none
+  config.dependency_reporting = true
 end
 ```
 
@@ -266,7 +307,7 @@ Configuration errors are raised during `Chronos.configure`. Capture and delivery
 
 ## Benchmark
 
-Run the version 0.6 benchmarks with:
+Run the version 0.8 benchmarks with:
 
 ```bash
 bundle _1.17.3_ exec ruby benchmarks/capture_exception.rb
@@ -277,13 +318,15 @@ bundle _1.17.3_ exec ruby benchmarks/retry_backlog.rb
 bundle _1.17.3_ exec ruby benchmarks/request_overhead.rb
 bundle _1.17.3_ exec ruby benchmarks/rails_notifications.rb
 bundle _1.17.3_ exec ruby benchmarks/sidekiq_middleware.rb
+bundle _1.17.3_ exec ruby benchmarks/apm_aggregation.rb
+bundle _1.17.3_ exec ruby benchmarks/external_http.rb
 ```
 
 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.6 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

@@ -0,0 +1,35 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://chronos.example/schemas/apm-batch-v1.schema.json",
+  "title": "Chronos APM metric batch payload v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["metrics", "dropped_groups"],
+  "properties": {
+    "dropped_groups": {"type": "integer", "minimum": 0},
+    "metrics": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 50,
+      "items": {
+        "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", "external_http"]},
+          "dimensions": {"type": "object"},
+          "count": {"type": "integer", "minimum": 1},
+          "error_count": {"type": "integer", "minimum": 0},
+          "error_rate": {"type": "number", "minimum": 0, "maximum": 1},
+          "duration_ms": {
+            "type": "object",
+            "required": ["total", "min", "max", "average"]
+          },
+          "histogram": {"type": "array", "maxItems": 20},
+          "breakdown_ms": {"type": "object"},
+          "signals": {"type": "object"},
+          "status_codes": {"type": "object"}
+        }
+      }
+    }
+  }
+}

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"]},
+    "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-015-bounded-apm-aggregation.md

@@ -0,0 +1,27 @@
+# ADR-015 — Bounded local APM aggregation
+
+## Status
+
+Accepted for version 0.7.
+
+## Context
+
+Sending every request, SQL query, and job as an independent event increases network overhead. Retaining every observation for client-side percentiles or unbounded N+1 analysis would transfer that cost to application memory.
+
+## Decision
+
+Aggregate request, query, and job observations by bounded low-cardinality dimensions. Store only counters, error counters, duration sum/min/max, fixed histogram buckets, component totals, status counters, and heuristic signal counters. Calculate averages locally and percentiles in the SaaS.
+
+Use a fixed group limit, fixed query-fingerprint limit per trace, fixed batch size, and no new timer thread. Drain on observation threshold, explicit flush, and close. Clear incomplete trace trackers during drain. Normalize SQL comments and literal values before fingerprinting and never read binds. Use a `metric_batch` event through the existing sanitization, queue, retry, circuit breaker, and backlog pipeline.
+
+## Alternatives
+
+One event per observation was rejected as the default because delivery overhead scales directly with traffic. Retaining raw duration arrays was rejected because memory would scale with traffic. Client-side percentiles, SQL parsing dependencies, and background flush threads were rejected for the legacy line. Full SQL and bind capture was rejected for privacy and cardinality.
+
+## Positive consequences
+
+Delivery volume is reduced, memory remains bounded, request breakdown is available, SQL values are excluded, and the SaaS receives stable histograms suitable for percentile calculation.
+
+## Negative consequences
+
+Process crashes can lose undrained aggregates, incomplete trackers are discarded on drain, local signals are heuristic, and a defensive SQL normalizer cannot understand every database dialect.

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.6 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
@@ -19,6 +19,11 @@ flowchart TB
   Sidekiq[Integrations / Sidekiq client and server middleware] --> Facade
   Sidekiq --> Envelope[Versioned job-envelope context]
   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
@@ -44,7 +49,11 @@ An exception becomes an immutable notice. `Sanitizer` removes sensitive values b
 
 Rails timings become immutable `TelemetryEvent` values. `CaptureTelemetry` applies the remote/local event policy, `TelemetrySerializer` sanitizes the allowlisted payload, and the resulting `SerializedEvent` enters the same delivery pipeline. Rails classes are loaded only through `chronos/rails`; the core never requires Rails or ActiveSupport.
 
-Sidekiq client middleware writes a versioned, allowlisted trace/request context beside the job's public arguments. Server middleware restores a job scope, limits arguments and tags, emits one job telemetry event, and routes a failure through the existing notice pipeline before re-raising it. Sidekiq retains queue, retry, thread, and connection lifecycle ownership.
+Sidekiq client middleware writes a versioned, allowlisted trace/request context beside the job's public arguments. Server middleware restores a job scope, limits arguments and tags, emits a job observation, and routes a failure through the existing notice pipeline before re-raising it. Sidekiq retains queue, retry, thread, and connection lifecycle ownership.
+
+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
 

data/docs/compatibility.md

@@ -19,6 +19,10 @@ Version 0.5 includes Rails 4.2 and 5.2 applications plus a dedicated matrix, but
 
 Version `0.6.0.pre.1` uses the public Sidekiq 4/5 middleware signatures and remains `Best effort` until dedicated jobs exercise both real gem versions across their valid Ruby combinations.
 
+Version `0.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 | 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,6 +48,20 @@
 | `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, 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 |
+| `apm_max_queries_per_request` | Optional | `100` | Query fingerprints tracked per trace for repetition signals |
+| `apm_slow_query_threshold_ms` | Optional | `500.0` | Query duration that produces a slow-query signal and sampled source |
+| `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|
@@ -67,6 +81,19 @@ Chronos.configure do |config|
   config.breadcrumb_capacity = 20
   config.rails_capture_in_test = false
   config.rails_capture_in_console = false
+  config.apm_enabled = true
+  config.apm_max_groups = 200
+  config.apm_flush_count = 100
+  config.apm_batch_size = 50
+  config.apm_max_queries_per_request = 100
+  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.6 emits exception, request, query, job, and cache events. 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 |
 |---|---|---|
@@ -32,9 +32,23 @@ Version 0.6 emits exception, request, query, job, and cache events. All fields p
 | Sidekiq arguments | Collected, sanitized, and bounded | First 20 job arguments; collections/depth/strings limited |
 | Sidekiq tags | Collected and bounded | Job payload or public worker options |
 | Sidekiq trace/request IDs | Propagated when present; trace generated otherwise | Chronos job-envelope metadata |
-| Cache operation, store, hit flag, duration | Collected; key/value omitted | ActiveSupport cache notifications |
+| 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/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 |
+| 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.
 
 The secret `project_key` is an authentication header and is excluded from the JSON payload and logger diagnostics. The envelope field named `project_key` contains the public `project_id` required by the current v1 server contract.
 

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

@@ -0,0 +1,57 @@
+# Essential APM aggregation
+
+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
+
+Request groups use normalized route and HTTP method. Status codes are counted inside the group so error rate can be calculated without making status part of an unbounded key. Each metric contains count, error count/rate, total, minimum, maximum, average, fixed histogram buckets, and component breakdown. Percentiles remain server-side because retaining every duration locally would violate the memory boundary.
+
+Rack records request metrics for non-Rails applications. Rails controller notifications and Rack share `record_event_once`, so the same request is counted only once. Controller notification data wins when available because its route is more precise.
+
+## SQL metrics and signals
+
+`Chronos::Core::SqlNormalizer` removes block/line comments, quoted literal values, numeric values, booleans, nulls, and repeated `IN` values before producing a SHA-256 fingerprint. Binds are never read. Query dimensions can contain adapter, operation, inferred table, bounded normalized query, fingerprint, Active Record operation name, cache flag, connection role/shard, and a bounded source frame for slow sampled queries.
+
+Local signals are intentionally heuristic:
+
+- `slow_query` when duration reaches `apm_slow_query_threshold_ms`;
+- `repeated_query` after the same fingerprint appears again in one trace;
+- `possible_n_plus_one` once when the configured repetition threshold is reached;
+- `long_transaction` for transaction-labelled SQL over its threshold;
+- `connection_error` and `deadlock` from bounded exception class names.
+
+The SaaS must confirm and correlate these signals. They are not proof of an N+1, deadlock, or application defect.
+
+## Bounded state
+
+- at most `apm_max_groups` metric groups;
+- at most `apm_max_groups` active trace trackers;
+- at most `apm_max_queries_per_request` fingerprints per trace;
+- at most 19 configured histogram boundaries plus `+Inf`;
+- at most `apm_batch_size` groups per payload, with a hard maximum of 50;
+- trackers are removed when their request completes and all remaining trackers are cleared on aggregate drain.
+
+New groups beyond capacity are dropped and counted in `dropped_groups`. Existing groups continue accumulating. The state is process-local and is lost on restart.
+
+## Breakdown
+
+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
+
+```ruby
+Chronos.configure do |config|
+  # connection settings omitted
+  config.apm_enabled = true
+  config.apm_max_groups = 200
+  config.apm_flush_count = 100
+  config.apm_batch_size = 50
+  config.apm_max_queries_per_request = 100
+  config.apm_slow_query_threshold_ms = 500.0
+  config.apm_long_transaction_threshold_ms = 1000.0
+  config.apm_n_plus_one_threshold = 5
+  config.apm_histogram_buckets = [5.0, 10.0, 25.0, 50.0, 100.0, 250.0, 500.0, 1000.0]
+end
+```
+
+Setting `apm_enabled = false` restores individual request/query/job telemetry for compatibility diagnostics. Cache events remain individual in 0.7 while also contributing to an existing request breakdown.

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

@@ -7,3 +7,7 @@ This module is separate from capture because configuration errors should be foun
 Risks include accidentally logging credentials and changing settings while events run. The snapshot prevents mutation, while logger and transport code never interpolate `project_key`.
 
 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.