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

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1ab10ffdc0cff4274241465904b18e4bceb4fa230ea9fddb4b8be419c08e3463
-  data.tar.gz: 2d6d778012088192efed14e0ab64958716c8a6b4c3e697127c52573dc4dcd47b
+  metadata.gz: 8475c8f2a946a1c0e512d37b01d9931a47df75c2446c6c898a8d8a795db4aff3
+  data.tar.gz: 533465780682cdbfad58087cae0458c513d7086828350587728b970093be5264
 SHA512:
-  metadata.gz: a8bb789313b2b7d360b6a8c08e5b5cf731aa1325912be7b560a1869b3d8717e4e779610e92591c1a2c436f5d14cd39e28f1e5db837d954def1db232788284d2d
-  data.tar.gz: 93a311d6905d83dee031a88cb5887854a32e60d26eceb0dc0446a8244c77a2c9fa763089bc5ec5fa25d265cb5881c3775dafe6361b1e84a1c6044aa89df220ee
+  metadata.gz: 456b339239a6fdd7b11706e2cd2c4be59dbf11e015354e95f60a7ebffb07305f66df1bdc79a77c7b8f9a776b9ba66325f288af6d954b5027808d1e85d1992097
+  data.tar.gz: 29126344b372211a3940eb7b58a66ae8e10f5769090081a9dfefaedee4001fdc949a03b0511b3492ae783e1ba0d99b24f1adbfba6b9c8775123e1b03f88e6fa2

data/README.md

@@ -1,10 +1,10 @@
 # Chronos Ruby
 
-Chronos Ruby is the framework-independent client for sending Ruby application errors to Chronos. Version 0.4 adds automatic Rack exception capture, isolated request context, and bounded breadcrumbs to the 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.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.
 
 ## What the gem collects
 
-For each exception, version 0.4 can collect:
+For each exception, version 0.5 can collect:
 
 - exception class, message, structured backtrace, and chained causes;
 - timestamp, severity, tags, and an optional fingerprint;
@@ -22,7 +22,7 @@ Chronos Ruby does not inspect environment variables, request bodies, cookies, HT
 
 ## Supported Ruby and Rails versions
 
-Version 0.x targets Ruby 2.2.10 through Ruby 2.6. Version 0.4 implements the Rack protocol but does not yet declare Rails support. All supported combinations must pass dedicated CI before being listed as supported.
+Version 0.x targets Ruby 2.2.10 through Ruby 2.6. Version 0.5 provides best-effort Rails 4.2 through 5.2 integration through public framework APIs and feature detection. All supported combinations must pass dedicated CI before being listed as supported.
 
 See [Compatibility](docs/compatibility.md).
 
@@ -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.4.0.pre.1"
+gem "chronos-ruby", "0.5.0.pre.1"
 ```
 
 Install with a Bundler version compatible with the application. For the oldest supported runtime:
@@ -49,7 +49,19 @@ gem install chronos-ruby --pre
 
 ## Rails installation
 
-Rails automatic installation is not part of version 0.4. A Rails application may install the Rack middleware manually, but this does not constitute declared Rails support. Railtie and generator support are planned for version 0.5.
+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"
+```
+
+Generate the initializer with:
+
+```bash
+rails generate chronos:install
+```
+
+The Railtie installs the Rack middleware and notification subscribers idempotently. Automatic integration is disabled in test and console by default and can be controlled with `rails_enabled`, `rails_capture_in_test`, `rails_capture_in_console`, and `rails_capture_user_agent`. See [Rails 4.2 and 5.2 integration](docs/modules/rails-legacy.md).
 
 ## Minimum configuration
 
@@ -156,11 +168,11 @@ Local exception-specific ignore callbacks are not available in version 0.4. The
 
 ## Performance monitoring
 
-Request timing events, SQL, cache, job, and external HTTP monitoring are not implemented in version 0.4. Rack exception context is bounded, and HTTP delivery runs outside the caller thread when `Chronos.notify` is used.
+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.
 
 ## Sidekiq and Active Job
 
-Sidekiq and Active Job integrations are not implemented in version 0.4. Calling the manual API from a job is possible, but automatic capture and deduplication are not yet guaranteed.
+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.
 
 ## Deploy tracking
 
@@ -203,6 +215,7 @@ The code follows hexagonal boundaries:
 - `Chronos::Ports` defines delivery behavior;
 - `Chronos::Adapters` implements Net::HTTP delivery and thread-local context;
 - `Chronos::Integrations::Rack` implements optional automatic Rack capture;
+- `Chronos::Rails` implements the optional Railtie, installer, generator, and public-notification adapters;
 - `Chronos::Internal` owns bounded queueing, workers, and defensive logging.
 
 The core has no dependency on Rails, Rack, Sidekiq, or ActiveSupport. See [Architecture](docs/architecture.md).
@@ -244,7 +257,7 @@ Configuration errors are raised during `Chronos.configure`. Capture and delivery
 
 ## Benchmark
 
-Run the version 0.4 benchmarks with:
+Run the version 0.5 benchmarks with:
 
 ```bash
 bundle _1.17.3_ exec ruby benchmarks/capture_exception.rb
@@ -253,13 +266,14 @@ bundle _1.17.3_ exec ruby benchmarks/filtering.rb
 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
 ```
 
 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.4 does not claim API compatibility or automatic replacement.
+An Airbrake migration guide will be added before the legacy 1.0 release. Version 0.5 does not claim API compatibility or automatic replacement.
 
 ## Local development
 

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"]},
+    "event_type": {"enum": ["exception", "request", "query", "job", "cache"]},
     "occurred_at": {"type": "string"},
     "sent_at": {"type": "string"},
     "project_key": {"type": "string", "minLength": 1},
@@ -36,16 +36,30 @@
     },
     "runtime": {"type": "object"},
     "context": {"type": "object"},
-    "payload": {
-      "type": "object",
-      "required": ["exception", "severity"],
-      "properties": {
-        "exception": {
-          "type": "object",
-          "required": ["class", "message", "backtrace", "causes"]
-        },
-        "severity": {"type": "string"}
+    "payload": {"type": "object"}
+  },
+  "allOf": [
+    {
+      "if": {
+        "required": ["event_type"],
+        "properties": {
+          "event_type": {"const": "exception"}
+        }
+      },
+      "then": {
+        "properties": {
+          "payload": {
+            "required": ["exception", "severity"],
+            "properties": {
+              "exception": {
+                "type": "object",
+                "required": ["class", "message", "backtrace", "causes"]
+              },
+              "severity": {"type": "string"}
+            }
+          }
+        }
       }
     }
-  }
+  ]
 }

data/docs/adr/ADR-013-legacy-rails-notifications.md

@@ -0,0 +1,27 @@
+# ADR-013 — Legacy Rails integration through public notifications
+
+## Status
+
+Accepted for version 0.5.
+
+## Context
+
+Rails 4.2 and 5.2 predate Zeitwerk as a universal loader and expose different optional components. Automatic capture must not couple the Ruby core to Rails, duplicate middleware or subscribers during reload, or collect high-risk framework payloads.
+
+## Decision
+
+Load Rails integration explicitly through `chronos/rails`. Use a small Railtie initializer after application configuration, an idempotent installer, and public `ActiveSupport::Notifications.subscribe` callbacks. Detect constants and methods before using optional components. Emit request, query, job, and cache envelopes through the same sanitization and delivery pipeline as exceptions.
+
+Allowlist metadata per notification. Never copy SQL text, binds, cache keys, mail bodies, job arguments, request bodies, response bodies, cookies, or authorization headers. Deduplicate controller and Rack exception hooks within request context.
+
+## Alternatives
+
+ActiveSupport method patching and controller monkey patches were rejected because public notifications cover the required lifecycle with less version risk. Modeling timings as exception breadcrumbs was rejected because successful requests and SQL need independently deliverable metrics. Requiring Rails from the core was rejected because plain Ruby applications must remain framework-independent.
+
+## Positive consequences
+
+The core remains independent, installation is reload-safe, optional components degrade cleanly, and Rails telemetry retains existing privacy and outage boundaries.
+
+## Negative consequences
+
+Legacy notification payloads are less uniform than modern tracing APIs. Individual events add delivery volume until aggregation arrives in version 0.7. Synthetic Rails 4.2 controller exceptions may not retain the original exception class when only the public tuple is available.

data/docs/architecture.md

@@ -1,6 +1,6 @@
 # Architecture
 
-Chronos Ruby 0.4 uses hexagonal boundaries so the legacy core remains independent of frameworks and delivery infrastructure.
+Chronos Ruby 0.5 uses hexagonal boundaries so the legacy core remains independent of frameworks and delivery infrastructure.
 
 ```mermaid
 flowchart TB
@@ -14,6 +14,9 @@ flowchart TB
   Rack[Integrations / Rack middleware] --> Facade
   Facade --> Context[Ports / ContextStore]
   Context --> ThreadLocal[Adapters / ThreadLocalContextStore]
+  Rails[Chronos Rails / Railtie and subscribers] --> Facade
+  Rails --> Notifications[ActiveSupport Notifications]
+  Application --> Telemetry[Core / TelemetryEvent]
 ```
 
 ## Boundaries
@@ -24,6 +27,7 @@ flowchart TB
 - Adapters contain Net::HTTP, TLS, and thread-local context behavior.
 - 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.
 
 The `Chronos` module is a thin facade. Rails, Rack, ActiveSupport, Sidekiq, and job libraries must not be required by the core.
 
@@ -35,6 +39,8 @@ The Rack middleware establishes a context-store scope, adds a bounded request br
 
 An exception becomes an immutable notice. `Sanitizer` removes sensitive values before `SafeSerializer` creates a bounded JSON envelope. Asynchronous capture inserts only that sanitized serialized event into the queue. A fixed worker sends it through `DeliveryPipeline`, which applies finite retry, a circuit breaker, and a fixed memory backlog. Synchronous capture bypasses the queue but uses the same privacy and resilience boundaries.
 
+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.
+
 ## 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

@@ -4,14 +4,14 @@ Chronos Ruby 0.x is the legacy line. Technical compatibility does not make an en
 
 | Ruby | Rails integration | Status | Evidence |
 |---|---|---|---|
-| 2.2.10 | Rack protocol in 0.4; no Rails | Best effort | Dedicated legacy core CI and Rack contract tests |
-| 2.3.8 | Rack protocol in 0.4; no Rails | Best effort | Dedicated legacy core CI and Rack contract tests |
-| 2.4.10 | Rack protocol in 0.4; no Rails | Best effort | Dedicated legacy core CI and Rack contract tests |
-| 2.5.9 | Rack protocol in 0.4; no Rails | Best effort | Dedicated legacy core CI and Rack contract tests |
-| 2.6.10 | Rack protocol in 0.4; no Rails | Best effort | Dedicated legacy core CI and Rack contract tests |
+| 2.2.10 | Rails 4.2 | Best effort | Core CI, Rails 4.2 example, dedicated smoke gate |
+| 2.3.8 | Rails 4.2 / 5.0 | Best effort | Core CI and feature-detection contract; dedicated app gate incomplete |
+| 2.4.10 | Rails 4.2 / 5.0 | Best effort | Core CI and feature-detection contract; dedicated app gate incomplete |
+| 2.5.9 | Rails 5.2 | Best effort | Core CI, Rails 5.2 example, dedicated smoke gate |
+| 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 |
 
-No Rails version is declared supported by version 0.4. The middleware is tested against the Rack protocol shape without adding a Rack runtime dependency. Rails support requires a real example application, Railtie integration tests, and a successful dedicated matrix job.
+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.
 
 Status meanings:
 

data/docs/configuration.md

@@ -38,12 +38,16 @@
 | `circuit_reset_timeout` | Optional | `30.0` | Seconds before one half-open delivery probe |
 | `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 exception sampling |
-| `enabled_event_types` | Optional | `["exception"]` | Local event-type allowlist; only exception exists in version 0.4 |
+| `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 |
 | `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 |
 | `breadcrumb_max_bytes` | Optional | `2048` | Maximum bytes per normalized breadcrumb; minimum `128` |
+| `rails_enabled` | Optional | `true` | Enables automatic Rails middleware and subscribers |
+| `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 |
 
 ```ruby
 Chronos.configure do |config|
@@ -61,6 +65,8 @@ Chronos.configure do |config|
   config.circuit_failure_threshold = 5
   config.context_store = :thread_local
   config.breadcrumb_capacity = 20
+  config.rails_capture_in_test = false
+  config.rails_capture_in_console = false
 end
 ```
 

data/docs/data-collected.md

@@ -1,6 +1,6 @@
 # Data collected
 
-Version 0.4 emits exception events submitted manually or captured by the optional Rack middleware. All fields pass through the privacy sanitizer and bounded safe serializer before queueing, retry storage, or delivery.
+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.
 
 | Data | Default | Source |
 |---|---|---|
@@ -21,8 +21,15 @@ Version 0.4 emits exception events submitted manually or captured by the optiona
 | Rack parameters | Collected only when already parsed | Explicit, Rack, or Action Dispatch parameter hashes |
 | Response size | `Content-Length` when present | Rack response headers |
 | Breadcrumbs | Explicit and bounded | Application and Chronos integration |
+| Rails controller/action, status, method, query-free path, normalized route, duration | Collected with Rails integration | `process_action.action_controller` |
+| Sanitized Rails parameters | Collected with Rails integration | Public controller notification payload |
+| View template basename and duration | Collected with Rails integration | `render_template.action_view` |
+| 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` |
+| 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, SQL bind values, database rows, or installed gems in version 0.4.
+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 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/rails-legacy.md

@@ -0,0 +1,60 @@
+# Rails 4.2 and 5.2 legacy integration
+
+Version 0.5 adds an explicit Rails entry point:
+
+```ruby
+require "chronos/rails"
+```
+
+`Chronos::Rails::Railtie` registers one initializer after `load_config_initializers`. It requires no Zeitwerk and delegates to an idempotent installer. The installer uses feature detection, installs `Chronos::Integrations::Rack::Middleware` once per application, and registers notification subscribers once per `ActiveSupport::Notifications` bus.
+
+## Installation generator
+
+Run:
+
+```bash
+rails generate chronos:install
+```
+
+The generator creates `config/initializers/chronos.rb`. The template reads only explicitly named `CHRONOS_*` variables, uses `Rails.env`, adopts `Rails.logger` when available, and disables automatic integration in test and console by default. It invokes the idempotent installer as a fallback for applications that disabled Bundler auto-require, so the Railtie and initializer paths cannot create duplicate hooks. It never scans all environment variables or modifies routes and application classes.
+
+## Captured integrations
+
+The public `ActiveSupport::Notifications.subscribe` API is used for:
+
+| Notification | Chronos event | Allowlisted data |
+|---|---|---|
+| `process_action.action_controller` | `request` | controller, action, status, method, query-free path, normalized route, duration, sanitized parameters |
+| `render_template.action_view` | `request` with `kind=view` | template basename and duration |
+| `sql.active_record` | `query` | operation name, cached flag, and duration |
+| `deliver.action_mailer` | `job` with `kind=mailer` | mailer, action, and duration |
+| `perform.active_job` | `job` | job class, queue, and duration, when Active Job is available |
+| cache read/write/hit notifications | `cache` | operation, store, hit flag, and duration |
+
+Raw SQL, binds, cache keys, mail recipients and bodies, job IDs and arguments, request/response bodies, cookies, and authorization headers are not copied. Template identifiers are reduced to their basename. Every event passes through `Sanitizer`, `SafeSerializer`, the bounded queue, retry policy, circuit breaker, and memory backlog.
+
+## Controller exceptions and deduplication
+
+When `process_action.action_controller` exposes `exception_object`, the original exception is captured. Rails versions that expose only the public exception tuple produce a bounded synthetic `RuntimeError` containing the supplied message. A request-scoped deduplicator prevents the same error from being reported again by the Rack middleware. The host application continues to receive its original exception semantics.
+
+## Configuration
+
+```ruby
+Chronos.configure do |config|
+  # connection settings omitted
+  config.rails_enabled = true
+  config.rails_capture_in_test = false
+  config.rails_capture_in_console = false
+  config.rails_capture_user_agent = false
+end
+```
+
+Setting `rails_enabled = false` prevents middleware and subscribers from being installed. Test and console switches affect only automatic Rails integration; explicit manual Chronos calls retain their normal configuration behavior.
+
+## Compatibility evidence
+
+The repository contains independent applications under `examples/rails-4.2` and `examples/rails-5.2`. Their smoke scripts execute a successful request, controller exception, SQL query, view, cache access, inline Active Job, Action Mailer, flush, and shutdown. The dedicated legacy Rails workflow is the release gate; a framework/runtime pair must not be labeled `Supported` until that job and fake-server payload validation pass.
+
+## 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.

data/docs/modules/telemetry-events.md

@@ -0,0 +1,9 @@
+# Framework telemetry events
+
+`Chronos::Core::TelemetryEvent` and `Chronos::Core::TelemetrySerializer` extend the v1 envelope to `request`, `query`, `job`, and `cache` events. These values exist so framework adapters do not model operational timings as fake exceptions.
+
+Telemetry has the same `schema_version`, event ID, timestamps, project, environment, service, runtime, context, sanitization, payload-size limit, idempotency header, asynchronous queue, retry, circuit breaker, and memory backlog used by exception events. Unsupported types are rejected locally.
+
+`Chronos.record_event` is the narrow integration entry point. Application code should prefer documented higher-level APIs; its payload is allowlisted by each bundled integration and then sanitized. Remote configuration can reduce or disable any locally enabled telemetry type but cannot enable a type excluded by local configuration.
+
+Version 0.5 intentionally sends individual framework events. Aggregation, percentiles, slow-query analysis, and transaction breakdowns remain part of version 0.7.

data/docs/performance.md

@@ -1,6 +1,6 @@
 # Performance
 
-Performance is a functional requirement, but version 0.4 makes no unverified speed claim.
+Performance is a functional requirement, but version 0.5 makes no unverified speed claim.
 
 Current controls:
 
@@ -15,11 +15,24 @@ Current controls:
 - retry count, delay, jitter, and `Retry-After` are capped;
 - the circuit breaker suppresses requests during sustained failure;
 - retry backlog capacity is fixed and may be disabled;
-- shutdown and flush have caller-controlled timeouts.
+- shutdown and flush have caller-controlled timeouts;
 - 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.
 
-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, and `benchmarks/request_overhead.rb` compares a successful direct Rack-protocol call with the middleware path.
+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.
+
+## Version 0.5 Rails subscriber benchmark
+
+Run:
+
+```bash
+ITERATIONS=100000 bundle _1.17.3_ exec ruby benchmarks/rails_notifications.rb
+```
+
+This synthetic benchmark invokes the SQL notification normalizer with a no-op notifier. It verifies that raw SQL and binds are not copied and measures local allowlist normalization only; it does not include Rails dispatch, serialization, queueing, or network delivery.
+
+A local diagnostic run on 2026-07-20 used Ruby 2.2.10 on macOS arm64 and 10,000 iterations. It completed in 0.041232 seconds, or approximately 4.123 microseconds per normalization. This single run has no warmup, median, or dispersion and is not a production performance claim.
 
 ## Version 0.2 development measurement
 

data/docs/privacy-lgpd.md

@@ -1,6 +1,6 @@
 # Privacy and LGPD
 
-Version 0.4 sanitizes every exception event 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.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.
 
 ## Default policy
 
@@ -13,9 +13,13 @@ Version 0.4 sanitizes every exception event before JSON serialization, queueing,
 | 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, SQL binds, environment variables | Never collected automatically in version 0.4 |
+| 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 |
 
-The retry backlog exists only in process memory, accepts only `SerializedEvent`, has a fixed capacity, and disappears on process exit. Version 0.4 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.5 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.
 
 ## Rack context and breadcrumbs
 

data/docs/troubleshooting.md

@@ -14,7 +14,15 @@ Check DNS, TLS certificates, credentials, HTTP status, proxy configuration, and
 
 ## Rack exception is not captured
 
-Confirm that `Chronos.configure` runs before the middleware handles requests and that the middleware wraps the application component that raises. Version 0.4 captures exceptions raised by the initial downstream Rack call; an exception raised later while a server enumerates a streaming response body is outside this release. The original exception is always re-raised, so the server log should still show it.
+Confirm that `Chronos.configure` runs before the middleware handles requests and that the middleware wraps the application component that raises. Version 0.5 captures exceptions raised by the initial downstream Rack call; an exception raised later while a server enumerates a streaming response body is outside this release. The original exception is always re-raised, so the server log should still show it.
+
+## Rails middleware or telemetry is missing
+
+Require `chronos/rails` from the generated initializer and confirm it runs before requests. Automatic integration is disabled by default in Rails test and console; set `rails_capture_in_test` or `rails_capture_in_console` explicitly when validating those environments. `rails_enabled = false` disables all automatic Rails hooks. Active Job is subscribed only when its constant is available during installation.
+
+## Rails telemetry contains no SQL or cache key
+
+This is intentional. Version 0.5 records SQL operation name/duration and cache operation/store/hit status without raw statements, binds, keys, or values. These omissions are privacy and cardinality boundaries, not capture failures.
 
 ## Context appears missing
 

data/lib/chronos/agent.rb

@@ -36,7 +36,7 @@ module Chronos
         @logger,
         pipeline_options
       )
-      @capture = options[:capture] || Application::CaptureException.new(config, @delivery_pipeline, @logger)
+      initialize_capture(options)
     end
 
     def notify(exception, context = {})
@@ -63,6 +63,31 @@ module Chronos
       false
     end
 
+    def record_event(event_type, payload = {}, context = {})
+      @telemetry.call(event_type, payload, telemetry_context(context))
+    end
+
+    def notify_once(exception, context = {})
+      execution = @context_store.get
+      captured = execution[:__chronos_captured_exceptions] || {}
+      keys = [[:object, exception.object_id], [:message, exception.message.to_s]]
+      return false if keys.any? { |key| captured[key] }
+
+      keys.each { |key| captured[key] = true }
+      @context_store.set(execution.merge(:__chronos_captured_exceptions => captured))
+      notify(exception, context)
+    rescue StandardError
+      false
+    end
+
+    def rails_integration_options(environment = nil, console = false)
+      current_environment = (environment || @config.environment).to_s
+      enabled = @config.rails_enabled
+      enabled = false if console && !@config.rails_capture_in_console
+      enabled = false if current_environment == "test" && !@config.rails_capture_in_test
+      {:enabled => enabled, :include_user_agent => @config.rails_capture_user_agent}
+    end
+
     def flush(timeout = DEFAULT_FLUSH_TIMEOUT)
       @delivery_pipeline.flush(timeout)
     rescue StandardError => error
@@ -84,6 +109,11 @@ module Chronos
 
     private
 
+    def initialize_capture(options)
+      @capture = options[:capture] || Application::CaptureException.new(@config, @delivery_pipeline, @logger)
+      @telemetry = options[:telemetry] || Application::CaptureTelemetry.new(@config, @delivery_pipeline, @logger)
+    end
+
     def build_context_store(strategy)
       return Adapters::ThreadLocalContextStore.new if strategy == :thread_local
 
@@ -92,6 +122,8 @@ module Chronos
 
     def context_for_capture(additional)
       merged = deep_merge(context_hash(@context_store.get), context_hash(additional))
+      merged.delete(:__chronos_captured_exceptions)
+      merged.delete("__chronos_captured_exceptions")
       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)
@@ -101,6 +133,16 @@ module Chronos
       context_hash(additional)
     end
 
+    def telemetry_context(additional)
+      merged = context_for_capture(additional)
+      context = context_hash(merged.delete(:context) || merged.delete("context"))
+      parameters = merged.delete(:parameters) || merged.delete("parameters")
+      user = merged.delete(:user) || merged.delete("user")
+      context["parameters"] = parameters if parameters.is_a?(Hash) && !parameters.empty?
+      context["user"] = user if user.is_a?(Hash) && !user.empty?
+      context.merge(merged)
+    end
+
     def deep_merge(left, right)
       left.merge(right) do |_key, old_value, new_value|
         old_value.is_a?(Hash) && new_value.is_a?(Hash) ? deep_merge(old_value, new_value) : new_value

data/lib/chronos/application/capture_telemetry.rb

@@ -0,0 +1,37 @@
+module Chronos
+  module Application
+    # Coordinates bounded non-exception telemetry capture.
+    #
+    # @responsibility Build, sanitize, serialize, and enqueue integration events.
+    # @motivation Keep Rails notification policy outside transport and domain objects.
+    # @limits It handles request, query, job, and cache events only.
+    # @collaborators TelemetryEvent, TelemetrySerializer, and DeliveryPipeline.
+    # @thread_safety Calls own event state and may execute concurrently.
+    # @compatibility Ruby 2.2.10 through Ruby 2.6; independent of Rails.
+    # @example
+    #   capture.call("query", {"duration_ms" => 3.2})
+    # @errors Internal StandardError failures are contained and logged.
+    # @performance Local normalization is bounded before asynchronous queue insertion.
+    class CaptureTelemetry
+      def initialize(config, delivery_pipeline, logger = nil, options = {})
+        @config = config
+        @delivery_pipeline = delivery_pipeline
+        @logger = logger || Internal::SafeLogger.new(config.logger)
+        @serializer = options[:serializer] || Core::TelemetrySerializer.new(
+          config, nil, :max_payload_size => proc { @delivery_pipeline.max_payload_size }
+        )
+      end
+
+      def call(event_type, payload = {}, context = {})
+        return false unless @config.enabled_for_environment?
+        return false unless @delivery_pipeline.capture_allowed?(event_type)
+
+        event = Core::TelemetryEvent.new(event_type, payload, context)
+        @delivery_pipeline.enqueue(@serializer.call(event))
+      rescue StandardError => error
+        @logger.warn("Chronos telemetry capture failed: #{error.class}")
+        false
+      end
+    end
+  end
+end

data/lib/chronos/application/remote_configuration.rb

@@ -13,7 +13,7 @@ module Chronos
     # @errors Invalid documents are ignored and return false.
     # @performance Validation is bounded by configured document and list limits.
     class RemoteConfiguration
-      SUPPORTED_EVENT_TYPES = ["exception"].freeze
+      SUPPORTED_EVENT_TYPES = ["exception", "request", "query", "job", "cache"].freeze
       MAX_IGNORED_FINGERPRINTS = 100
       MAX_FINGERPRINT_BYTES = 256
       MIN_PAYLOAD_SIZE = 256

data/lib/chronos/configuration/snapshot.rb

@@ -0,0 +1,53 @@
+module Chronos
+  # Immutable configuration shared by all runtime components.
+  #
+  # @responsibility Expose validated settings without mutable containers.
+  # @motivation Keep capture behavior stable while multiple threads run.
+  # @limits It cannot be edited after creation.
+  # @collaborators Configuration and runtime services.
+  # @thread_safety Safe to share between threads after construction.
+  # @compatibility Ruby 2.2.10 through Ruby 2.6.
+  # @example
+  #   snapshot.enabled_for_environment? #=> true
+  # @errors Construction occurs only after Configuration validation.
+  # @performance Deep freezing is paid once during configuration.
+  Configuration::Snapshot = Class.new do
+    attr_reader(*Configuration::ATTRIBUTES)
+
+    def initialize(values)
+      Configuration::ATTRIBUTES.each do |attribute|
+        value = values[attribute]
+        deep_freeze(value)
+        instance_variable_set("@#{attribute}", value)
+      end
+      freeze
+    end
+
+    def enabled_for_environment?
+      enabled && !ignored_environments.map(&:to_s).include?(environment.to_s)
+    end
+
+    private # rubocop:disable Layout/AccessModifierIndentation
+
+    def deep_freeze(value)
+      return value if value.respond_to?(:call) || context_store?(value)
+
+      case value
+      when Hash
+        value.each do |key, child|
+          deep_freeze(key)
+          deep_freeze(child)
+        end
+      when Array
+        value.each { |child| deep_freeze(child) }
+      end
+      value.freeze
+    end
+
+    def context_store?(value)
+      Configuration::CONTEXT_STORE_METHODS.all? { |method_name| value.respond_to?(method_name) }
+    rescue StandardError
+      false
+    end
+  end
+end