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

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: db591fb9c6019444d079a5a5c683be8776b68010e3665e4a09656c2bdf568b46
-  data.tar.gz: 601f34cdaa1f9e06e2748a820b4228bad3c354a8c7feb562473d4268dc217117
+  metadata.gz: 8475c8f2a946a1c0e512d37b01d9931a47df75c2446c6c898a8d8a795db4aff3
+  data.tar.gz: 533465780682cdbfad58087cae0458c513d7086828350587728b970093be5264
 SHA512:
-  metadata.gz: 1c4adaeb1222449ba2b7a736f1e28e701d00a1faf3733f42ffa753759854c3deed7a4c9e4c33f2ea997aa9445f057b51641b3829fb49b2012e6668687a1df4b0
-  data.tar.gz: 3809e42fbaed2f3290464cdc7a1e962a70e39fd8c3f7071b6016ee53c53406fca84a250f375e0a46506560c9bdc603f4ceb13721b79b4c6225b28a1e94abdf49
+  metadata.gz: 456b339239a6fdd7b11706e2cd2c4be59dbf11e015354e95f60a7ebffb07305f66df1bdc79a77c7b8f9a776b9ba66325f288af6d954b5027808d1e85d1992097
+  data.tar.gz: 29126344b372211a3940eb7b58a66ae8e10f5769090081a9dfefaedee4001fdc949a03b0511b3492ae783e1ba0d99b24f1adbfba6b9c8775123e1b03f88e6fa2

data/CHANGELOG.md

@@ -11,6 +11,29 @@ 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.4.0.pre.1] - 2026-07-20
+
+### Added
+
+- Rack-protocol middleware for automatic exception capture with propagation of the original failure;
+- request context for method, normalized route, status, duration, request ID, optional user agent, host, path, controller/action, approximate response size, user, and sanitized parameters;
+- selectable context-store port with a thread-local legacy adapter and guaranteed scope cleanup;
+- bounded circular breadcrumbs for custom, log, request, query, external HTTP, cache, and job categories;
+- public `Chronos.with_context` and `Chronos.add_breadcrumb` APIs;
+- Rack context contract, concurrency tests, module documentation, ADR, executable example, and request-overhead benchmark.
+
+### Changed
+
+- manual notifications now inherit the current execution context and breadcrumbs;
+- version advanced to `0.4.0.pre.1`.
+
+### Known limitations
+
+- generic route normalization cannot identify every application-specific dynamic segment;
+- thread-local context does not propagate into application-created threads or fibers;
+- deferred exceptions raised only while enumerating a streaming response body are not captured;
+- Rails-specific installation and route discovery remain planned for version 0.5.
+
 ## [0.3.0.pre.1] - 2026-07-20
 
 ### Added

data/README.md

@@ -1,16 +1,18 @@
 # Chronos Ruby
 
-Chronos Ruby is the framework-independent client for sending Ruby application errors to Chronos. Version 0.3 adds bounded resilience to the privacy-focused legacy foundation: manual exceptions are sanitized before queueing, retried under a finite policy, retained in a fixed-size memory backlog during outages, and controlled by a restricted remote policy.
+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.3 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;
 - application-supplied context, parameters, session, and user fields;
 - Ruby version, engine, platform, process ID, opaque thread ID, and hostname;
 - application version, environment, and service name.
+- Rack method, normalized route, status, duration, request ID, host, query-free path, optional user agent, controller/action, response size, trace ID, and already-parsed parameters when the middleware is used;
+- bounded breadcrumbs explicitly supplied by the application or integration.
 
 See [Data collected](docs/data-collected.md) for the complete field table.
 
@@ -20,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.3 is independent of Rails and does not yet declare support for any Rails integration. 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).
 
@@ -29,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.3.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:
@@ -47,7 +49,19 @@ gem install chronos-ruby --pre
 
 ## Rails installation
 
-Rails automatic integration is not part of version 0.3. A Rails application may use the plain Ruby API, but this does not constitute declared Rails support. Rack and Rails adapters are planned for later legacy releases.
+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
 
@@ -70,7 +84,14 @@ HTTPS verification is enabled by default. HTTP requires explicitly setting `ssl_
 
 ## Automatic capture
 
-Automatic exception capture is not implemented in version 0.3. Applications must call `Chronos.notify` or `Chronos.notify_sync`. Rack, Rails, and worker hooks will be introduced only after their compatibility suites exist.
+Rack applications can capture unhandled exceptions automatically and preserve the application error semantics:
+
+```ruby
+use Chronos::Integrations::Rack::Middleware,
+    :include_user_agent => false
+```
+
+The middleware notifies asynchronously and re-raises the same exception. It never reads the request body, raw query string, cookies, authorization headers, or response body. See [Rack integration and context](docs/modules/rack-context.md).
 
 ## Manual capture
 
@@ -101,15 +122,25 @@ User data is opt-in and must contain only values your application is allowed to
 Chronos.notify(error, :user => {"id" => "customer-42", "role" => "operator"})
 ```
 
-Version 0.3 sanitizes this context before delivery and before it can enter retry storage. Data minimization remains the application's responsibility.
+Version 0.4 sanitizes this context before delivery and before it can enter retry storage. Data minimization remains the application's responsibility.
 
 ## Breadcrumbs
 
-Breadcrumbs are not implemented in version 0.3.
+Breadcrumbs use a fixed circular buffer scoped to the current execution:
+
+```ruby
+Chronos.add_breadcrumb(
+  :category => "custom",
+  :message => "payment started",
+  :metadata => {"provider" => "example"}
+)
+```
+
+No log, SQL, HTTP, cache, job, request body, or response body payload is collected automatically. Unknown categories become `custom`, and metadata is bounded and sanitized before queueing.
 
 ## Filters and LGPD
 
-Version 0.3 recursively redacts sensitive keys and detects Bearer tokens, JWTs, e-mail addresses, CPF, CNPJ, and valid payment-card candidates in free text. IPv4 addresses are anonymized by default. Applications can add blocklist matchers, hash selected identifiers, or install custom filters:
+Version 0.4 recursively redacts sensitive keys and detects Bearer tokens, JWTs, e-mail addresses, CPF, CNPJ, and valid payment-card candidates in free text. IPv4 addresses are anonymized by default. Applications can add blocklist matchers, hash selected identifiers, or install custom filters:
 
 ```ruby
 Chronos.configure do |config|
@@ -133,19 +164,19 @@ Chronos.configure do |config|
 end
 ```
 
-Local exception-specific ignore callbacks are not available in version 0.3. The server may provide a bounded list of exact fingerprints to ignore; it cannot provide regular expressions or executable rules.
+Local exception-specific ignore callbacks are not available in version 0.4. The server may provide a bounded list of exact fingerprints to ignore; it cannot provide regular expressions or executable rules.
 
 ## Performance monitoring
 
-Request, SQL, cache, job, and external HTTP monitoring are not implemented in version 0.3. The local capture pipeline 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.3. 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
 
-Deploy notifications are not implemented in version 0.3. `app_version` may be included in exception events for release correlation.
+Deploy notifications are not implemented in version 0.4. `app_version` may be included in exception events for release correlation.
 
 ## Asynchronous queue
 
@@ -168,7 +199,7 @@ Use `Chronos.flush(timeout)` to wait for accepted events and `Chronos.close(time
 
 ## Retry and backlog
 
-Version 0.3 retries network errors, HTTP `408`, `429`, and `5xx` responses with exponential backoff, bounded jitter, and a finite attempt count. Other `4xx` responses are permanent and are not retried. A circuit breaker pauses requests after repeated failures, preventing retry storms.
+The resilience layer introduced in version 0.3 retries network errors, HTTP `408`, `429`, and `5xx` responses with exponential backoff, bounded jitter, and a finite attempt count. Other `4xx` responses are permanent and are not retried. A circuit breaker pauses requests after repeated failures, preventing retry storms.
 
 After retries are exhausted, the already sanitized `SerializedEvent` may enter a fixed-capacity memory backlog. The backlog drops new items when full, is lost when the process exits, and never writes to disk. A later successful half-open probe drains backlog items as new events arrive.
 
@@ -182,7 +213,9 @@ The code follows hexagonal boundaries:
 - `Chronos::Application` coordinates capture;
 - `Chronos::Application::DeliveryPipeline` owns bounded retry and remote policy;
 - `Chronos::Ports` defines delivery behavior;
-- `Chronos::Adapters` implements Net::HTTP delivery;
+- `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).
@@ -210,6 +243,9 @@ Chronos.configure do |config|
   config.circuit_failure_threshold = 5
   config.circuit_reset_timeout = 30.0
   config.remote_configuration = true
+  config.context_store = :thread_local
+  config.breadcrumb_capacity = 20
+  config.breadcrumb_max_bytes = 2048
 end
 ```
 
@@ -221,7 +257,7 @@ Configuration errors are raised during `Chronos.configure`. Capture and delivery
 
 ## Benchmark
 
-Run the version 0.3 benchmarks with:
+Run the version 0.5 benchmarks with:
 
 ```bash
 bundle _1.17.3_ exec ruby benchmarks/capture_exception.rb
@@ -229,13 +265,15 @@ bundle _1.17.3_ exec ruby benchmarks/serialization.rb
 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.3 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/contracts/rack-context-v1.schema.json

@@ -0,0 +1,43 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://chronos.example/schemas/rack-context-v1.schema.json",
+  "title": "Chronos Rack exception context v1",
+  "type": "object",
+  "additionalProperties": true,
+  "required": ["request", "trace_id", "breadcrumbs"],
+  "properties": {
+    "trace_id": {"type": "string", "minLength": 1},
+    "request": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["method", "route", "status", "duration_ms", "request_id", "host", "path"],
+      "properties": {
+        "method": {"type": "string"},
+        "route": {"type": "string"},
+        "status": {"type": "integer"},
+        "duration_ms": {"type": "number", "minimum": 0},
+        "request_id": {"type": ["string", "null"]},
+        "user_agent": {"type": ["string", "null"]},
+        "host": {"type": "string"},
+        "path": {"type": "string"},
+        "controller": {"type": ["string", "null"]},
+        "action": {"type": ["string", "null"]},
+        "response_size": {"type": ["integer", "null"], "minimum": 0}
+      }
+    },
+    "breadcrumbs": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["category", "message", "metadata", "timestamp"],
+        "properties": {
+          "category": {"enum": ["custom", "log", "request", "query", "external_http", "cache", "job"]},
+          "message": {"type": "string"},
+          "metadata": {"type": "object"},
+          "timestamp": {"type": "string"}
+        }
+      }
+    }
+  }
+}

data/docs/adr/ADR-012-rack-context-isolation.md

@@ -0,0 +1,27 @@
+# ADR-012 — Rack capture with selectable execution context
+
+## Status
+
+Accepted for version 0.4.
+
+## Context
+
+Automatic Rack capture needs request-scoped state, but the legacy line cannot rely on modern fiber-local APIs. Loading the plain Ruby gem must not force Rack into applications that do not use it. Request and response bodies also carry disproportionate privacy and performance risk.
+
+## Decision
+
+Implement a Rack-protocol middleware without a runtime Rack dependency. Catch failures from the downstream application call, notify asynchronously, and re-raise the same exception. Never read `rack.input`, raw query strings, cookies, authorization headers, or response body enumeration. Use already-parsed parameter hashes only.
+
+Define a `ContextStore` port and use a selectable thread-local adapter by default. Restore nested scopes in `ensure`. Keep breadcrumbs in a fixed circular per-execution buffer and sanitize them with the rest of the event before queueing.
+
+## Alternatives
+
+Requiring Rack from the core was rejected because it would add dependency and resolution risk to plain Ruby legacy applications. Global or process-wide context was rejected because concurrent requests would leak data. Automatic body parsing and body proxies were deferred because they change I/O behavior and complicate streaming lifecycle ownership.
+
+## Positive consequences
+
+Plain Ruby loading remains dependency-free, concurrent request context is isolated, middleware failure semantics are preserved, and diagnostic memory is bounded.
+
+## Negative consequences
+
+Thread-local context does not propagate to application-created threads or fibers. Generic route normalization is less precise than router-specific integration. Exceptions raised only during deferred response-body enumeration are outside version 0.4 capture.

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.3 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
@@ -11,22 +11,36 @@ flowchart TB
   Application --> Delivery[Application / DeliveryPipeline]
   Delivery --> Internal[Internal / BoundedQueue, WorkerPool, and MemoryBacklog]
   Internal --> Ports
+  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
 
 - Domain/Core owns immutable event values and Ruby normalization.
 - Application owns use-case ordering and failure containment.
-- Ports define behavior expected from infrastructure.
-- Adapters contain Net::HTTP and TLS behavior.
+- Ports define behavior expected from transport and execution-context infrastructure.
+- 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.
 
+## Rack capture flow
+
+The Rack middleware establishes a context-store scope, adds a bounded request breadcrumb, and calls the downstream application. An unhandled exception is enriched with request duration and status, captured through the normal notice pipeline, then re-raised unchanged. The context-store adapter restores or clears its value in `ensure`. The middleware implements the Rack protocol without requiring the Rack library.
+
 ## Capture flow
 
 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 | None in 0.3 | Best effort | Dedicated legacy core CI job |
-| 2.3.8 | None in 0.3 | Best effort | Dedicated legacy core CI job |
-| 2.4.10 | None in 0.3 | Best effort | Dedicated legacy core CI job |
-| 2.5.9 | None in 0.3 | Best effort | Dedicated legacy core CI job |
-| 2.6.10 | None in 0.3 | Best effort | Dedicated legacy core CI job |
+| 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.3. Rails applications may call the plain Ruby API manually. Rails support requires a real example application, framework 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,9 +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.3 |
+| `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|
@@ -56,6 +63,10 @@ Chronos.configure do |config|
   config.max_retries = 3
   config.backlog_size = 100
   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.3 emits only manually submitted exception events. 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 |
 |---|---|---|
@@ -15,8 +15,21 @@ Version 0.3 emits only manually submitted exception events. All fields pass thro
 | Context, parameters, session, user | Optional and sanitized | Explicit capture arguments |
 | Tags and fingerprint | Optional and sanitized | Explicit capture arguments |
 | IPv4 address in supplied text | Anonymized | Explicit capture arguments |
+| Rack method, normalized route, status, duration, request ID, host, query-free path, trace ID | Collected with Rack middleware | Rack environment and local clock |
+| Rack user agent | Disabled by default | `HTTP_USER_AGENT` when middleware option is enabled |
+| Rack controller/action | Collected when already supplied | Explicit Chronos or Action Dispatch environment values |
+| 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, cookies, HTTP authorization headers, environment variables in bulk, source code, SQL bind values, database rows, or installed gems in version 0.3.
+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/rack-context.md

@@ -0,0 +1,59 @@
+# Rack integration, execution context, and breadcrumbs
+
+Version 0.4 adds automatic capture through `Chronos::Integrations::Rack::Middleware`. The integration implements the Rack protocol directly and does not require Rack when `chronos-ruby` is loaded. Add the middleware after configuring Chronos:
+
+```ruby
+use Chronos::Integrations::Rack::Middleware,
+    :include_user_agent => false
+```
+
+## Capture behavior
+
+The middleware catches an exception raised by the downstream application, submits it asynchronously, and re-raises the same exception object. A notification or logger failure cannot replace the application failure. An `ensure` boundary clears request context in every outcome.
+
+Captured request fields are method, normalized route, status, duration in milliseconds, request ID, optional user agent, host, query-free path, controller/action when already supplied, approximate response size from `Content-Length`, a generated or supplied trace ID, already-parsed parameters, and application-supplied user context. The final event serializer sanitizes every field before queueing.
+
+The middleware never reads `rack.input`, copies `QUERY_STRING`, parses a body, enumerates a response body, or reads cookies and authorization headers. Parameters are collected only from already-materialized hashes at `rack.request.query_hash`, `action_dispatch.request.query_parameters`, `action_dispatch.request.path_parameters`, or the explicit `chronos.parameters` key. User context is opt-in through `chronos.user`.
+
+Without an explicit `chronos.route` or `action_dispatch.route_uri_pattern`, numeric and UUID path segments are replaced with `:id`. This is a conservative cardinality guard, not a complete router-aware normalizer.
+
+## Context store
+
+`Chronos::Ports::ContextStore` defines `get`, `set`, `clear`, and `with_context`. The legacy default, `Chronos::Adapters::ThreadLocalContextStore`, isolates each thread and restores nested scopes in `ensure`. It deliberately does not propagate state into newly created threads or fibers.
+
+A custom strategy can be selected at configuration time if it implements the complete port:
+
+```ruby
+Chronos.configure do |config|
+  # credentials omitted
+  config.context_store = MyContextStore.new
+end
+```
+
+Application code can add scoped values. Manual notifications issued inside the block inherit them:
+
+```ruby
+Chronos.with_context(:user => {"id" => "customer-42"}) do
+  Chronos.notify(error)
+end
+```
+
+## Breadcrumbs
+
+`Chronos.add_breadcrumb` records an explicit marker in the current execution buffer:
+
+```ruby
+Chronos.add_breadcrumb(
+  :category => "custom",
+  :message => "payment authorization started",
+  :metadata => {"provider" => "example"}
+)
+```
+
+Allowed categories are `custom`, `log`, `request`, `query`, `external_http`, `cache`, and `job`; an unknown value becomes `custom`. No log, SQL, body, cache, job, or external HTTP payload is captured automatically in 0.4. Metadata exists only when the application or a later integration explicitly supplies it.
+
+The default circular buffer keeps the newest 20 entries. Each breadcrumb is normalized to JSON primitives with bounded depth, collections, strings, nodes, and serialized bytes. The entire exception payload still passes through the privacy sanitizer before it can enter the queue or retry backlog.
+
+## Concurrency and limitations
+
+Concurrent Rack threads receive distinct user, parameter, breadcrumb, and trace values. Context does not cross threads automatically, so applications that start their own thread must establish a new scope explicitly. Version 0.4 captures exceptions raised during the initial Rack application call; deferred failures raised only while a server enumerates a streaming response body are not intercepted.

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.