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

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5ad7bc09dd58b0476b65687d0b7c695bdc5e82c898f882fc82ed2e87eb352b79
-  data.tar.gz: 527383d76a4432bc16f48d2a476d7c2398d66f5b891bbe666d1e0ceba9dc9959
+  metadata.gz: b9cf448c12955078e3a714df2d41bcd94d89f840fea406dc6595f72661e8abc2
+  data.tar.gz: 1401d283792e930caa252b21191de3d8fcc02bf5b2936416ed28eec2e319dab3
 SHA512:
-  metadata.gz: 24bf5ed37de64c34a82fd0b98f3e1323cac14c2392fa0d6a01dbcd24d48a69a52100a6127a79b2567314bcf2c464b354fee226ab19bba08ea384bfb3ec8a12f9
-  data.tar.gz: 1696953512893c9d3eecc23d361b35c5434df7dda25e33a1fe6321b5c25ae4d9e03a2a843bd76e9c327130be2cba2a6c7a9766d70a6f068007b24959aa3cfdc0
+  metadata.gz: 43f80510ce3d78e6c9b4b571f7d79cb66b8a4fad8f36b66996ea5cc42868c6ec7b1a05ae1556c8442569787f2f350e2884a779e36af649734eced377396c892b
+  data.tar.gz: 30b0f93cfba0ce2fb856b4c65eff6e1ebfa906c8c45ec5c6e287ddc080bc23bd63e4e1a7a4d80a56f40b5001c768719c3b52a2d7e9b08d08b39a2512b476db30

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.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.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.6 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.6.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.6.0.pre.1", :require => "chronos/rails"
+gem "chronos-ruby", "0.7.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,7 +191,7 @@ 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.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).
@@ -255,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
 ```
 
@@ -266,7 +284,7 @@ Configuration errors are raised during `Chronos.configure`. Capture and delivery
 
 ## Benchmark
 
-Run the version 0.6 benchmarks with:
+Run the version 0.7 benchmarks with:
 
 ```bash
 bundle _1.17.3_ exec ruby benchmarks/capture_exception.rb
@@ -277,13 +295,14 @@ 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.6 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/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.6 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
@@ -19,6 +19,8 @@ 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]
 ```
 
 ## Boundaries
@@ -44,7 +46,9 @@ 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.
 
 ## Failure policy
 

data/docs/compatibility.md

@@ -19,6 +19,8 @@ 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.
+
 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.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.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 |
 |---|---|---|
@@ -32,10 +32,19 @@ 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 |
+| 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, 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.
 
 See [Privacy and LGPD](privacy-lgpd.md) for redaction rules and the payload audit procedure.

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, or calculate query fingerprints. Sidekiq support is a separate optional integration beginning in version 0.6; full Active Job propagation remains a later 0.6 increment.
+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

@@ -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.6.0.pre.1", :require => "chronos/sidekiq"
+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.
@@ -13,7 +13,7 @@ The client middleware adds a top-level `chronos` metadata object to the Sidekiq
 
 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 failed-job telemetry, 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. Chronos does not install an additional global Sidekiq error handler.
+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:
 

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.6 makes no unverified speed claim.
+Performance is a functional requirement, but version 0.7 makes no unverified speed claim.
 
 Current controls:
 
@@ -20,6 +20,7 @@ Current controls:
 - 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.
 
@@ -87,3 +88,15 @@ 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.6 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
 
@@ -15,8 +15,9 @@ Version 0.6 sanitizes exception and framework telemetry before JSON serializatio
 | 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, 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.6 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
 
@@ -26,6 +27,10 @@ Rails subscribers use per-notification allowlists. SQL events retain only the op
 
 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.

data/docs/troubleshooting.md

@@ -32,6 +32,18 @@ Require `chronos/sidekiq` after Sidekiq is available and configure Chronos befor
 
 The bundled middleware does not install a global error handler and uses `notify_once` inside a shared job scope. Check for application-installed Chronos calls or third-party global handlers outside that scope. Keep a single bundled server middleware entry in the Sidekiq chain.
 
+## Request, query, or job events are not sent immediately
+
+This is expected with version 0.7 APM aggregation. Groups drain after `apm_flush_count` observations or during `Chronos.flush`/`Chronos.close`. Inspect `agent.diagnostics[:apm]` when using an explicit agent. Set `apm_enabled = false` only for temporary individual-event diagnostics.
+
+## Query metrics contain no literal values or binds
+
+This is intentional. The normalizer removes common literal forms and never reads binds. Queries differing only by values should share a fingerprint. If an unsupported database dialect leaves a sensitive literal form, stop delivery, add a synthetic privacy fixture, and report the dialect through the security/support process.
+
+## Possible N+1 or deadlock signal is inaccurate
+
+Local detectors emit bounded heuristics, not confirmed diagnoses. Repetition can be legitimate and exception class names can be adapter-specific. Confirm the trace in the SaaS and application logs before changing application behavior.
+
 ## Context appears missing
 
 The legacy context store is thread-local. A new application-created thread does not inherit context. Establish a new `Chronos.with_context` scope inside that thread, and issue manual notification before the scope exits. For Rack capture, supply user and explicit parameters through the documented environment keys.

data/lib/chronos/agent.rb

@@ -67,6 +67,26 @@ module Chronos
       @telemetry.call(event_type, payload, telemetry_context(context))
     end
 
+    def record_event_once(key, event_type, payload = {}, context = {})
+      execution = @context_store.get
+      captured = execution[:__chronos_captured_events] || {}
+      return false if captured[key.to_s]
+
+      captured[key.to_s] = true
+      @context_store.set(execution.merge(:__chronos_captured_events => captured))
+      record_event(event_type, payload, context)
+    rescue StandardError
+      false
+    end
+
+    def apm_integration_options
+      {
+        :enabled => @config.apm_enabled,
+        :slow_query_threshold_ms => @config.apm_slow_query_threshold_ms,
+        :root_directory => @config.root_directory
+      }
+    end
+
     # Returns the correlation subset safe for an integration-owned process boundary.
     def propagation_context
       current = context_hash(@context_store.get)
@@ -104,6 +124,7 @@ module Chronos
     end
 
     def flush(timeout = DEFAULT_FLUSH_TIMEOUT)
+      @telemetry.flush
       @delivery_pipeline.flush(timeout)
     rescue StandardError => error
       @logger.warn("Chronos flush failed: #{error.class}")
@@ -111,6 +132,7 @@ module Chronos
     end
 
     def close(timeout = DEFAULT_FLUSH_TIMEOUT)
+      @telemetry.flush
       @delivery_pipeline.close(timeout)
     rescue StandardError => error
       @logger.warn("Chronos close failed: #{error.class}")
@@ -119,6 +141,7 @@ module Chronos
 
     def diagnostics
       details = @delivery_pipeline.diagnostics
+      details[:apm] = @telemetry.diagnostics
       details[:queue].merge(details)
     end
 
@@ -139,6 +162,8 @@ module Chronos
       merged = deep_merge(context_hash(@context_store.get), context_hash(additional))
       merged.delete(:__chronos_captured_exceptions)
       merged.delete("__chronos_captured_exceptions")
+      merged.delete(:__chronos_captured_events)
+      merged.delete("__chronos_captured_events")
       buffer = merged.delete(:__chronos_breadcrumbs) || merged.delete("__chronos_breadcrumbs")
       if buffer.respond_to?(:to_a)
         merged[:context] = context_hash(merged[:context]).merge("breadcrumbs" => buffer.to_a)