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

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8475c8f2a946a1c0e512d37b01d9931a47df75c2446c6c898a8d8a795db4aff3
-  data.tar.gz: 533465780682cdbfad58087cae0458c513d7086828350587728b970093be5264
+  metadata.gz: b9cf448c12955078e3a714df2d41bcd94d89f840fea406dc6595f72661e8abc2
+  data.tar.gz: 1401d283792e930caa252b21191de3d8fcc02bf5b2936416ed28eec2e319dab3
 SHA512:
-  metadata.gz: 456b339239a6fdd7b11706e2cd2c4be59dbf11e015354e95f60a7ebffb07305f66df1bdc79a77c7b8f9a776b9ba66325f288af6d954b5027808d1e85d1992097
-  data.tar.gz: 29126344b372211a3940eb7b58a66ae8e10f5769090081a9dfefaedee4001fdc949a03b0511b3492ae783e1ba0d99b24f1adbfba6b9c8775123e1b03f88e6fa2
+  metadata.gz: 43f80510ce3d78e6c9b4b571f7d79cb66b8a4fad8f36b66996ea5cc42868c6ec7b1a05ae1556c8442569787f2f350e2884a779e36af649734eced377396c892b
+  data.tar.gz: 30b0f93cfba0ce2fb856b4c65eff6e1ebfa906c8c45ec5c6e287ddc080bc23bd63e4e1a7a4d80a56f40b5001c768719c3b52a2d7e9b08d08b39a2512b476db30

data/CHANGELOG.md

@@ -6,11 +6,57 @@ All notable changes are documented here. The project follows Semantic Versioning
 
 ### Fixed
 
+- `WorkerPool#flush` no longer returns before a worker marks a just-popped event as active;
 - release publishing now updates RubyGems to a Ruby 2.6-compatible version that supports `GEM_HOST_API_KEY`.
 - Updated the legacy development toolchain to non-vulnerable Rake and RuboCop versions.
 - 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.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
+
+- optional Sidekiq 4/5 client and server middleware loaded through `chronos/sidekiq`;
+- versioned trace/request context propagation beside, never inside, public job arguments;
+- Sidekiq class, queue, JID, retry count, duration, calculable latency, bounded arguments, tags, status, and error telemetry;
+- shared per-job exception deduplication for nested Sidekiq and Active Job capture paths;
+- Sidekiq payload contract, unit/integration tests, executable example, benchmark, module documentation, and ADR-014.
+
+### Changed
+
+- version advanced to `0.6.0.pre.1`;
+- the public facade exposes bounded propagation context for optional process-boundary integrations.
+
+### Known limitations
+
+- Sidekiq 4/5 remains `Best effort` until dedicated real-gem matrix jobs pass;
+- Active Job context propagation, Resque, and Delayed Job remain subsequent version 0.6 increments;
+- Sidekiq argument capture is automatic, though strictly bounded and sanitized.
+
 ## [0.4.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.5 adds legacy Rails 4.2 and 5.2 installation, controller exception deduplication, and allowlisted request, query, job, and cache events to the 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.7 adds bounded essential APM aggregation for requests, SQL, and jobs, including histograms, error rates, component breakdown, normalized SQL fingerprints, and local diagnostic signals.
 
 ## What the gem collects
 
-For each exception, version 0.5 can collect:
+For each exception, version 0.7 can collect:
 
 - exception class, message, structured backtrace, and chained causes;
 - timestamp, severity, tags, and an optional fingerprint;
@@ -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.5.0.pre.1"
+gem "chronos-ruby", "0.7.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.5.0.pre.1", :require => "chronos/rails"
+gem "chronos-ruby", "0.7.0.pre.1", :require => "chronos/rails"
 ```
 
 Generate the initializer with:
@@ -168,11 +168,35 @@ 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
 
-Version 0.5 records bounded Active Job execution telemetry when Active Job is available. It includes the job class, queue, and duration, but excludes job IDs and arguments. Sidekiq-specific integration is not implemented.
+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"
+```
+
+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.
 
 ## Deploy tracking
 
@@ -246,6 +270,9 @@ 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
 end
 ```
 
@@ -257,7 +284,7 @@ Configuration errors are raised during `Chronos.configure`. Capture and delivery
 
 ## Benchmark
 
-Run the version 0.5 benchmarks with:
+Run the version 0.7 benchmarks with:
 
 ```bash
 bundle _1.17.3_ exec ruby benchmarks/capture_exception.rb
@@ -267,13 +294,15 @@ bundle _1.17.3_ exec ruby benchmarks/queue.rb
 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
 ```
 
 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.5 does not claim API compatibility or automatic replacement.
+An Airbrake migration guide will be added before the legacy 1.0 release. Version 0.7 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"]},
+          "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/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", "metric_batch"]},
     "occurred_at": {"type": "string"},
     "sent_at": {"type": "string"},
     "project_key": {"type": "string", "minLength": 1},

data/contracts/sidekiq-job-v1.schema.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://chronos.example/schemas/sidekiq-job-v1.schema.json",
+  "title": "Chronos Sidekiq job payload v1",
+  "type": "object",
+  "required": ["kind", "class", "queue", "duration_ms", "status"],
+  "properties": {
+    "kind": {"const": "sidekiq"},
+    "class": {"type": "string"},
+    "queue": {"type": "string"},
+    "jid": {"type": "string"},
+    "duration_ms": {"type": "number", "minimum": 0},
+    "queue_latency_ms": {"type": ["number", "null"], "minimum": 0},
+    "retry_count": {"type": "integer", "minimum": 0},
+    "arguments": {"type": "array", "maxItems": 20},
+    "arguments_truncated": {"type": "boolean"},
+    "tags": {"type": "array", "maxItems": 20},
+    "status": {"enum": ["completed", "failed"]},
+    "error_class": {"type": "string"}
+  }
+}

data/docs/adr/ADR-014-sidekiq-envelope-context.md

@@ -0,0 +1,27 @@
+# ADR-014 — Sidekiq context in the job envelope
+
+## Status
+
+Accepted for version 0.6.
+
+## Context
+
+Sidekiq clients and servers usually run in different processes. Chronos needs correlation without changing the worker's public arguments, opening per-job resources, or allowing nested Active Job and Sidekiq hooks to duplicate the same exception.
+
+## Decision
+
+Use Sidekiq 4/5 public client and server middleware. Store a versioned `chronos` object beside `args`, containing only enqueue time, trace ID, and request ID. Never append metadata to `args`. On the server, establish a job execution context with a shared exception-deduplication map, emit bounded job telemetry, notify failures through `notify_once`, and re-raise the original exception. Do not install a global Sidekiq error handler.
+
+Limit job arguments before the common sanitizer and serializer: 20 top-level arguments, 20 items per collection, depth four, and 512 bytes per string. Sanitization remains mandatory before queueing, retry, backlog, or transport.
+
+## Alternatives
+
+Appending a context argument was rejected because it changes worker arity and application-visible data. A process-global context was rejected because concurrent jobs would leak correlation. A global error handler plus server middleware was rejected because it creates duplicate capture paths. Per-job delivery threads or Redis connections were rejected because lifecycle and resource ownership belong to Sidekiq and the existing bounded agent.
+
+## Positive consequences
+
+Worker signatures remain compatible, cross-process correlation is bounded, nested integrations share deduplication, and Sidekiq retains retry semantics.
+
+## Negative consequences
+
+The Sidekiq envelope grows slightly, only two context identifiers propagate, and automatic argument collection still requires application privacy review.

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/architecture.md

@@ -1,6 +1,6 @@
 # Architecture
 
-Chronos Ruby 0.5 uses hexagonal boundaries so the legacy core remains independent of frameworks and delivery infrastructure.
+Chronos Ruby 0.7 uses hexagonal boundaries so the legacy core remains independent of frameworks and delivery infrastructure.
 
 ```mermaid
 flowchart TB
@@ -16,7 +16,11 @@ flowchart TB
   Context --> ThreadLocal[Adapters / ThreadLocalContextStore]
   Rails[Chronos Rails / Railtie and subscribers] --> Facade
   Rails --> Notifications[ActiveSupport Notifications]
+  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]
 ```
 
 ## Boundaries
@@ -28,6 +32,7 @@ flowchart TB
 - Internal contains private concurrency and diagnostic mechanisms.
 - Integrations contain optional framework entry points and never enter the domain boundary.
 - `Chronos::Rails` contains the optional Railtie, installer, generator, and public-notification adapters.
+- `Chronos::Integrations::Sidekiq` contains optional Sidekiq 4/5 middleware and bounded job normalization.
 
 The `Chronos` module is a thin facade. Rails, Rack, ActiveSupport, Sidekiq, and job libraries must not be required by the core.
 
@@ -41,6 +46,10 @@ 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 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.
+
 ## 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

@@ -11,8 +11,16 @@ Chronos Ruby 0.x is the legacy line. Technical compatibility does not make an en
 | 2.6.10 | Rails 5.2 | Best effort | Core CI and feature-detection contract; dedicated app gate incomplete |
 | 2.7 and newer | None in 0.x | Unsupported | Belongs to transitional or modern lines |
 
+| Ruby | Sidekiq integration | Status | Evidence |
+|---|---|---|---|
+| 2.2.10–2.6 | Sidekiq 4 / 5 | Best effort | Middleware unit/integration contracts; dedicated real-gem matrix pending |
+
 Version 0.5 includes Rails 4.2 and 5.2 applications plus a dedicated matrix, but this document conservatively keeps the combinations at `Best effort` until all release-gate evidence, including fake-server payload validation, is green. Rails 5.0 uses the same feature-detected public APIs but does not yet have its own example application.
 
+Version `0.6.0.pre.1` uses the public Sidekiq 4/5 middleware signatures and remains `Best effort` until dedicated jobs exercise both real gem versions across their valid Ruby combinations.
+
+Version `0.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.
+
 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, 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,15 @@
 | `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_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` |
 
 ```ruby
 Chronos.configure do |config|
@@ -67,6 +76,14 @@ 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
 end
 ```
 

data/docs/data-collected.md

@@ -1,6 +1,6 @@
 # Data collected
 
-Version 0.5 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.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.
 
 | Data | Default | Source |
 |---|---|---|
@@ -27,9 +27,23 @@ Version 0.5 emits exception, request, query, job, and cache events. All fields p
 | SQL operation name, cached flag, duration | Collected; SQL text omitted | `sql.active_record` |
 | Mailer/action and duration | Collected; message content omitted | `deliver.action_mailer` |
 | Active Job class, queue, duration | Collected when available; arguments omitted | `perform.active_job` |
+| Sidekiq class, queue, JID, retry count, duration, status, error class | Collected with optional middleware | Sidekiq job envelope and local clock |
+| Sidekiq queue latency | Collected when enqueue time is available | Sidekiq or Chronos envelope timestamp |
+| Sidekiq arguments | Collected, sanitized, and bounded | First 20 job arguments; collections/depth/strings limited |
+| 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 |
+| 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 |
+| 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 |
 
-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, job IDs/arguments, or installed gems in version 0.5.
+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.
+
+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/modules/apm-aggregation.md

@@ -0,0 +1,57 @@
+# 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.
+
+## 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.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.
+
+## 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/configuration.md

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

data/docs/modules/rails-legacy.md

@@ -57,4 +57,4 @@ The repository contains independent applications under `examples/rails-4.2` and
 
 ## Limits
 
-Version 0.5 emits individual bounded timings. It does not aggregate APM metrics, capture SQL text, calculate query fingerprints, or provide Sidekiq integration. Those belong to later versions in the development order.
+Version 0.7 aggregates controller, SQL, and job timings into bounded APM batches. SQL literals and binds remain excluded while a bounded normalized query and fingerprint are produced. Sidekiq support remains a separate optional integration; full Active Job propagation remains a later legacy increment.

data/docs/modules/sidekiq-legacy.md

@@ -0,0 +1,23 @@
+# Sidekiq 4/5 legacy integration
+
+Version `0.6.0.pre.1` starts the legacy jobs line with optional Sidekiq 4 and 5 client and server middleware. Load it after declaring Sidekiq:
+
+```ruby
+gem "sidekiq", "~> 5.0"
+gem "chronos-ruby", "0.7.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.
+
+The client middleware adds a top-level `chronos` metadata object to the Sidekiq envelope. It never changes the public `args` array. Only `trace_id` and `request_id` propagate, with schema version and enqueue time. The server scopes that context for the worker, measures duration and calculable queue latency, and emits one `job` event.
+
+Collected Sidekiq fields are worker class, queue, JID, retry count, duration, queue latency, status, error class, bounded tags, and bounded arguments. At most 20 top-level arguments, 20 values per nested collection, four levels, and 512 bytes per string are traversed. Arguments then pass through the standard sensitive-key/content sanitizer before queueing. Limits reduce exposure and resource use but do not make unnecessary personal data safe to collect.
+
+On failure, the server middleware records a failed-job observation, invokes `notify_once`, and re-raises the identical exception so Sidekiq retains ownership of retries and failure handlers. A shared execution marker prevents a nested Active Job hook and the Sidekiq middleware from sending the same exception twice. Version 0.7 aggregates the job observation; the exception retains sanitized bounded arguments. Chronos does not install an additional global Sidekiq error handler.
+
+Known limitations for this first 0.6 prerelease:
+
+- the compatibility contract uses Sidekiq 4/5 public middleware signatures; dedicated real Sidekiq matrix jobs must pass before status becomes `Supported`;
+- Active Job propagation, Resque, and Delayed Job are subsequent 0.6 increments;
+- argument collection is automatic in this prerelease; applications should avoid placing secrets or unnecessary personal data in job arguments;
+- context propagation is limited to trace and request identifiers.

data/docs/modules/telemetry-events.md

@@ -6,4 +6,4 @@ Telemetry has the same `schema_version`, event ID, timestamps, project, environm
 
 `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.5 intentionally sends individual framework events. Aggregation, percentiles, slow-query analysis, and transaction breakdowns remain part of version 0.7.
+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).

data/docs/performance.md

@@ -1,6 +1,6 @@
 # Performance
 
-Performance is a functional requirement, but version 0.5 makes no unverified speed claim.
+Performance is a functional requirement, but version 0.7 makes no unverified speed claim.
 
 Current controls:
 
@@ -19,6 +19,8 @@ Current controls:
 - request context and breadcrumbs have fixed structural and byte limits;
 - Rack middleware never consumes request or response bodies.
 - 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.
 
 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.
 
@@ -76,3 +78,25 @@ ITERATIONS=100000 bundle _1.17.3_ exec ruby benchmarks/request_overhead.rb
 ```
 
 A local diagnostic run on 2026-07-20 used Ruby 2.2.10 on macOS arm64 and 10,000 successful Rack-protocol calls. The direct application calls took 0.013272 seconds and middleware calls took 0.539758 seconds, for an estimated 52.649 microseconds of middleware work per request. The fixture uses no network, error capture, or response-body enumeration. This is a single development measurement, not a production latency claim; controlled warmup, median, and dispersion remain required before publishing a performance claim.
+
+## Version 0.6 Sidekiq middleware benchmark
+
+Run:
+
+```bash
+ITERATIONS=100000 bundle _1.17.3_ exec ruby benchmarks/sidekiq_middleware.rb
+```
+
+The benchmark executes client context injection and successful server normalization with a no-op notifier. It includes bounded argument handling and clock reads, but excludes Sidekiq/Redis, serialization, queueing, and network delivery. Record a controlled result before making a performance claim.
+
+## Version 0.7 APM aggregation benchmark
+
+Run:
+
+```bash
+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.

data/docs/privacy-lgpd.md

@@ -1,6 +1,6 @@
 # Privacy and LGPD
 
-Version 0.5 sanitizes exception and framework telemetry 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.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.
 
 ## Default policy
 
@@ -13,14 +13,24 @@ Version 0.5 sanitizes exception and framework telemetry before JSON serializatio
 | Payment-card candidates that pass the Luhn check | Replaced with `[FILTERED_CARD]` |
 | IPv4 addresses | Last octet replaced with `0` |
 | Unknown Ruby objects | Represented by class name without calling application serialization |
-| Request/response bodies, raw query strings, cookies, authorization headers, raw SQL/binds, cache values, mail bodies, job arguments, environment variables | Never collected automatically in version 0.5 |
+| 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 |
 
-The retry backlog exists only in process memory, accepts only `SerializedEvent`, has a fixed capacity, and disappears on process exit. Version 0.5 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.7 does not persist telemetry to disk.
 
 ## Rails telemetry
 
 Rails subscribers use per-notification allowlists. SQL events retain only the operation name, cached flag, and duration; cache events omit key and value; mailer events omit addresses and content; Active Job events omit job ID and arguments; view identifiers are reduced to basenames. Controller parameters are sanitized by the normal payload pipeline before queueing.
 
+## Sidekiq jobs
+
+The optional Sidekiq middleware is the only version 0.6 integration that automatically reads job arguments. It traverses at most 20 top-level arguments, 20 items per nested collection, four levels, and 512 bytes per string. These structural limits run before the common key and content sanitizer. Trace propagation contains only trace and request identifiers. Do not place credentials or unnecessary personal, health, or financial data in job arguments; configure application-specific blocklist keys and audit representative synthetic payloads before enabling production delivery.
+
+## APM dimensions
+
+Metric groups deliberately exclude user IDs, JIDs, raw URLs, request parameters, bind values, exception messages, and cache keys. SQL normalization removes common literal forms and comments before fingerprinting, but retains bounded database identifiers and cannot parse every dialect. Do not encode personal or secret values in schema, table, column, SQL keyword, or operation names. Slow-query source contains a bounded file/line frame under the configured application root, not source-code contents.
+
 ## Rack context and breadcrumbs
 
 The Rack middleware copies only bounded operational fields and parameter hashes that another component already parsed. It does not read `rack.input` or copy `QUERY_STRING`. User context is opt-in through `chronos.user`, and user agent collection is disabled unless the middleware option enables it.