chronos-ruby 0.8.0.pre.1 → 0.9.0.pre.2

data/docs/modules/ignore-rules.md

@@ -0,0 +1,11 @@
+# Bounded local ignore rules
+
+Configure startup rules with `config.ignore_rules` or add a rule to the active agent with `Chronos.ignore_if`. A rule receives an immutable normalized notice and must return exactly `true` to discard it before serialization, queueing, retry, or network work.
+
+```ruby
+Chronos.ignore_if do |notice|
+  notice.exception_class == "SomeExpectedError"
+end
+```
+
+At most `max_ignore_rules` rules are retained (default 20, hard maximum 100). Registration returns `false` when Chronos is not configured, the object is not callable, or the limit is full. A rule failure is contained and treated as no match. Rules run in the capture caller and therefore must be fast, thread-safe, and free of I/O. Remote configuration cannot add executable rules.

data/docs/modules/rails-legacy.md

@@ -28,10 +28,10 @@ The public `ActiveSupport::Notifications.subscribe` API is used for:
 | `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 |
+| `perform.active_job` | `job` | adapter, job/provider IDs, class, queue, attempts, duration, status, and error class |
 | cache read/write/hit notifications | `cache` | operation, backend, namespace, hit/miss, duration, and optional scoped key hash |
 
-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.
+Raw SQL, binds, cache keys, mail recipients and bodies, job arguments, request/response bodies, cookies, and authorization headers are not copied. Documented Active Job IDs are collected, while public job arguments remain unchanged and omitted. 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
 
@@ -57,4 +57,4 @@ The repository contains independent applications under `examples/rails-4.2` and
 
 ## Limits
 
-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.
+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. Version `0.9.0.pre.2` provides bounded Active Job trace/request propagation through a namespaced serialized field; adapters that replace the standard Active Job serialization/execution hooks require separate compatibility evidence.

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.8.0.pre.1", :require => "chronos/sidekiq"
+gem "chronos-ruby", "0.9.0.pre.2", :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.

data/docs/modules/telemetry-events.md

@@ -1,9 +1,11 @@
 # Framework telemetry events
 
-`Chronos::Core::TelemetryEvent` and `Chronos::Core::TelemetrySerializer` extend the v1 envelope to `request`, `query`, `job`, `cache`, `external_http`, `dependencies`, and `metric_batch` events. These values exist so integrations do not model operational telemetry as fake exceptions.
+`Chronos::Core::TelemetryEvent` and `Chronos::Core::TelemetrySerializer` extend the v1 envelope to `request`, `query`, `job`, `cache`, `external_http`, `dependencies`, `deploy`, and `metric_batch` events. These values exist so integrations do not model operational telemetry 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.8 aggregates request, query, job, and enabled external HTTP observations into `metric_batch` events by default. Cache remains an individual event while contributing to an existing traced request breakdown. Dependencies use one separate event per agent. Set `apm_enabled = false` only when individual legacy telemetry is required for diagnostics. Percentiles remain server-side; see [Essential APM aggregation](apm-aggregation.md).
+
+Version 0.9 delivers deploy telemetry synchronously because deployment commands are short-lived. Every telemetry and exception envelope contains the fixed correlation fields documented in [Deploy tracking and release correlation](deploy-tracking.md).

data/docs/performance.md

@@ -1,6 +1,6 @@
 # Performance
 
-Performance is a functional requirement, but version 0.8 makes no unverified speed claim.
+Performance is a functional requirement, but version 0.9 makes no unverified speed claim.
 
 Current controls:
 
@@ -24,9 +24,22 @@ Current controls:
 - outbound HTTP instrumentation uses two clock reads and bounded metadata without body/header traversal;
 - cache normalization is bounded and SHA-256 runs only when explicitly enabled;
 - dependency inventory runs at most once per agent and is capped at 200 loaded specs.
+- event correlation copies exactly seven strings with a 128-byte bound each;
+- deploy notification uses the existing synchronous delivery path and creates no timer or worker type.
 
 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.9.0.pre.2 release gates
+
+`benchmarks/comparative.rb` compares the same successful Rack fixture without and with Chronos instrumentation. It performs configurable warmup, at least three samples, and reports median plus median absolute deviation. `benchmarks/fake_endpoint_load.rb` sends asynchronous exception events to a local TCP endpoint, verifies the v1 schema marker, ensures the secret key is absent from every payload, and fails on loss, rejection, invalid payload, or timeout.
+
+```bash
+ITERATIONS=50000 WARMUP=5000 SAMPLES=7 bundle exec ruby benchmarks/comparative.rb
+ITERATIONS=500 bundle exec ruby benchmarks/fake_endpoint_load.rb
+```
+
+Results are environment-specific evidence, not a general speed claim. Record CPU, OS, Ruby, gem commit, and environment variables with any published result. Airbrake comparison remains optional and must use a legally compatible, equivalent sanitized payload on the same supported runtime.
+
 ## Version 0.5 Rails subscriber benchmark
 
 Run:
@@ -115,3 +128,15 @@ ITERATIONS=100000 bundle _1.17.3_ exec ruby benchmarks/external_http.rb
 The fixture compares a no-op Net::HTTP-compatible object with the per-instance wrapper. It includes trace-header injection, bounded outcome capture, and clock reads, but excludes DNS, sockets, TLS, serialization, queueing, and network delivery. Record a controlled result before making a performance claim.
 
 A local diagnostic run on 2026-07-20 used Ruby 2.2.10 on macOS arm64 and 10,000 calls. It measured approximately 15.155 microseconds of wrapper overhead per call. This single run has no controlled warmup, median, or dispersion and is not a production performance claim.
+
+## Version 0.9 correlation benchmark
+
+Run:
+
+```bash
+ITERATIONS=100000 bundle _1.17.3_ exec ruby benchmarks/correlation.rb
+```
+
+The fixture builds the seven-field frozen correlation hash from an immutable configuration. It excludes notice/event construction, sanitization, JSON, queueing, retry, and network delivery. Record a controlled result before making a performance claim.
+
+A local diagnostic run on 2026-07-21 used Ruby 2.2.10 on macOS arm64 and 10,000 correlations. It measured approximately 20.490 microseconds per correlation. 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.8 sanitizes exception, framework telemetry, dependency inventory, 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.
+Version 0.9 sanitizes exception, framework telemetry, dependency/deploy inventory, correlation, 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
 
@@ -19,8 +19,17 @@ Version 0.8 sanitizes exception, framework telemetry, dependency inventory, and
 | External HTTP | Host/method/status/timing only; URL path/query, Authorization, bodies, headers, and error messages omitted |
 | Cache key | Omitted by default; optional project-scoped SHA-256 hash; cache value never read |
 | Dependencies | Bounded loaded gem names/versions and detected runtime labels; paths and lockfiles omitted |
+| Deploy correlation | Explicit bounded operational identifiers; no automatic Git or environment scan |
+| Repository | Credentials removed from common HTTP/SCP forms; query/fragment omitted for parsed URLs |
+| Actor | Explicit and sanitized; omit it when personal identity is unnecessary |
 
-The retry backlog exists only in process memory, accepts only `SerializedEvent`, has a fixed capacity, and disappears on process exit. Version 0.8 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.9 does not persist telemetry to disk.
+
+## Deploy metadata
+
+Release, revision, deploy ID, environment, service, region, and instance are operational identifiers but can become personal or sensitive when applications encode customer, tenant, employee, or infrastructure-secret values in them. Use opaque bounded identifiers. Repository should be an owner/name identifier rather than a credential-bearing clone URL. Actor is optional; prefer a service account label when individual identity is unnecessary.
+
+The deploy normalizer removes user information from standard HTTP(S) repository URLs and usernames from SCP-style Git references. This is defensive, not a substitute for secret management. Never pass access tokens in any deploy field. All values still traverse the common sanitizer before transport.
 
 ## External services, cache, and dependencies
 

data/docs/protocol-v1.md

@@ -0,0 +1,5 @@
+# Protocol v1 stability
+
+The schemas under `contracts/` are the source of truth for protocol v1. Version `0.9.0.pre.2` keeps `schema_version: "1.0"` and treats every required field, enum value, privacy exclusion, and maximum as a compatibility contract.
+
+Compatible changes may add optional bounded fields or new event types accepted by the server. Removing or renaming a field, changing its type/meaning, weakening a bound, or making an optional field required needs a new protocol major schema. Authentication remains outside the JSON payload. Contract tests and `script/verify_docs` must pass before a release.

data/docs/release-1.0-readiness.md

@@ -0,0 +1,18 @@
+# Version 1.0 readiness
+
+Version `0.9.0.pre.2` is a hardening release, not the stable release. The local suite, lint, documentation verifier, build, load test, and comparative benchmark are required evidence. The release can advance to `1.0.0` only after the GitHub Actions matrix is green for every declared legacy Ruby/framework/job combination.
+
+| Gate | State in pre.2 |
+|---|---|
+| Ruby pure, Rack, Rails 4.2/5.2 | Implemented; external legacy matrix must pass |
+| Sidekiq 4/5 real gems | Dedicated Docker matrix added; must pass |
+| Active Job metadata/error/context | Implemented and contract-tested |
+| filters, bounded ignore rules, context, breadcrumbs | Implemented and documented |
+| request/SQL/job APM, deploy, retry/backlog, remote configuration | Implemented and contract-tested |
+| payload fixture privacy | Contract-tested |
+| public API/options/protocol review | Documented; final review required |
+| Airbrake migration, SemVer, deprecation, security review | Added in pre.2 |
+| fake endpoint load and repeatable comparison | Executable gates added |
+| package signing | Not currently feasible; protected secret plus checksum is the interim control |
+
+Do not change compatibility status from `Best effort` or create a `v1.0.0` tag until all external jobs and the dependency audit pass without skips.

data/docs/security-review.md

@@ -0,0 +1,16 @@
+# Security review for 0.9.0.pre.2
+
+Review date: 2026-07-21. Scope: capture, serialization, transport, remote configuration, framework/job integrations, release workflow, examples, and fixtures.
+
+Verified by contracts and implementation review:
+
+- the secret project key is sent only in an authentication header and never in the event body;
+- sanitization and payload limits run before queueing, retry, backlog, or transport;
+- queue, workers, retries, delays, circuit state, backlog, breadcrumbs, APM groups, dependencies, ignore rules, and propagated identifiers are bounded;
+- TLS verification is default and plain HTTP requires explicit `ssl_verify = false`;
+- remote configuration is size-limited, allowlisted, and cannot replace credentials/host or install executable rules;
+- integrations contain agent failures and do not collect bodies, authorization, raw SQL/binds, mail content, or raw cache keys;
+- Active Job propagation uses a namespaced v1 field containing only bounded trace/request identifiers and does not alter job arguments;
+- fixture privacy is enforced by contract tests and dependency advisories are checked by the security workflow.
+
+Residual risks: supported Ruby/Rails versions are end-of-life; in-memory backlog is lost at exit; application filters/ignore rules execute application code; project identifiers and documented job IDs may be personal data in some deployments; package signing is not enabled because no trusted certificate/key lifecycle exists. Release artifacts should use protected environments and published SHA-256 checksums until signing can be operated safely.

data/docs/semver.md

@@ -0,0 +1,11 @@
+# Semantic Versioning policy
+
+Chronos follows Semantic Versioning for the gem API and the independently versioned event protocol.
+
+- Before `1.0.0`, incompatible changes may occur only in a documented prerelease and must appear in the changelog and migration notes.
+- From `1.0.0`, patch releases contain compatible fixes, minor releases add compatible capability, and major releases may remove or change public behavior.
+- Public API includes documented `Chronos` methods, configuration options, supported require paths, integration entry points, and documented return/error behavior.
+- Internal constants and files explicitly described as internal are not public API.
+- The JSON `schema_version` is independent of the gem version. Additive optional v1 fields are compatible; removing, renaming, or changing required v1 fields requires a new protocol major version.
+
+A release is not promoted to stable while its supported matrix or mandatory release gates are incomplete.

data/docs/troubleshooting.md

@@ -36,6 +36,18 @@ Set `external_http_trace_headers = false` before configuring the agent, or do no
 
 The event is emitted once per agent and contains only gems loaded at collection time, capped by `dependency_max_items`. It does not parse the lockfile or activate optional frameworks. Call `Chronos.report_dependencies` after application boot if the first event can occur before all integrations load, or set `dependency_reporting = false` to disable collection.
 
+## `Chronos.notify_deploy` returns false
+
+Confirm Chronos is configured/enabled, environment is present, and at least revision or version is non-empty. Check credentials, TLS, proxy, timeout, retry/circuit state, and endpoint response. The call is synchronous and deliberately returns the delivery result. Repository credentials are removed and do not help authenticate with Chronos.
+
+## Events have empty or stale release correlation
+
+Set `app_version`, `revision`, `deploy_id`, `environment`, `service_name`, `region`, and `instance_id` before `Chronos.configure` creates its snapshot. `notify_deploy` does not mutate a running agent because that would mix release identities across concurrent events. Restart/configure each deployed process with the new values.
+
+## Capistrano task is missing
+
+Require `chronos/capistrano` after the Capistrano/Rake task DSL is loaded. The installer registers once per DSL and hooks `chronos:notify_deploy` after `deploy:published`. Confirm the base Chronos configuration runs in the task process and the expected `stage`, `current_revision`, `repo_url`, and `chronos_*` variables exist.
+
 ## Sidekiq telemetry is missing
 
 Require `chronos/sidekiq` after Sidekiq is available and configure Chronos before jobs run. The entry point uses Sidekiq's public client/server middleware configuration and remains optional. Requiring only `chronos` or `chronos/rails` does not load Sidekiq. A job already enqueued before client middleware installation may lack propagated trace context, but server timing and failure capture can still run.

data/lib/chronos/agent.rb

@@ -37,7 +37,7 @@ module Chronos
         pipeline_options
       )
       initialize_capture(options)
-      @dependency_reporter = options[:dependency_reporter] || Application::DependencyReporter.new(config)
+      initialize_observability(options)
     end
 
     def notify(exception, context = {})
@@ -50,6 +50,10 @@ module Chronos
       @capture.call_sync(exception, context_for_capture(context))
     end
 
+    def ignore_if(&block)
+      @ignore_policy.add(&block)
+    end
+
     def with_context(context = {}, &block)
       @context_store.with_context(context, &block)
     end
@@ -67,6 +71,8 @@ module Chronos
     end
 
     def record_event(event_type, payload = {}, context = {})
+      return false if event_type.to_s == "deploy"
+
       report_dependencies unless event_type.to_s == "dependencies"
       @telemetry.call(event_type, payload, telemetry_context(context))
     end
@@ -81,6 +87,18 @@ module Chronos
       false
     end
 
+    def notify_deploy(attributes = {}, timeout = DEFAULT_FLUSH_TIMEOUT)
+      payload = @deploy_normalizer.call(attributes)
+      return false unless @telemetry.call_sync("deploy", payload, {})
+
+      @dependency_reporter.reset(payload["version"]) if @dependency_reporter.respond_to?(:reset)
+      report_dependencies
+      flush(timeout)
+    rescue StandardError => error
+      @logger.warn("Chronos deploy notification failed: #{error.class}")
+      false
+    end
+
     def record_event_once(key, event_type, payload = {}, context = {})
       execution = @context_store.get
       captured = execution[:__chronos_captured_events] || {}
@@ -172,10 +190,20 @@ module Chronos
     private
 
     def initialize_capture(options)
-      @capture = options[:capture] || Application::CaptureException.new(@config, @delivery_pipeline, @logger)
+      @ignore_policy = options[:ignore_policy] || Application::IgnorePolicy.new(
+        @config.ignore_rules, @config.max_ignore_rules, @logger
+      )
+      @capture = options[:capture] || Application::CaptureException.new(
+        @config, @delivery_pipeline, @logger, :ignore_policy => @ignore_policy
+      )
       @telemetry = options[:telemetry] || Application::CaptureTelemetry.new(@config, @delivery_pipeline, @logger)
     end
 
+    def initialize_observability(options)
+      @dependency_reporter = options[:dependency_reporter] || Application::DependencyReporter.new(@config)
+      @deploy_normalizer = options[:deploy_normalizer] || Core::DeployNormalizer.new(@config)
+    end
+
     def build_context_store(strategy)
       return Adapters::ThreadLocalContextStore.new if strategy == :thread_local
 

data/lib/chronos/application/capture_exception.rb

@@ -18,6 +18,7 @@ module Chronos
         @delivery_pipeline = delivery_pipeline
         @logger = logger || Internal::SafeLogger.new(config.logger)
         @notice_builder = options[:notice_builder] || Core::NoticeBuilder.new(config)
+        @ignore_policy = options[:ignore_policy]
         @serializer = options[:serializer] || Core::PayloadSerializer.new(
           config,
           nil,
@@ -29,6 +30,7 @@ module Chronos
         return false unless capture_enabled?
 
         notice = build_notice(exception, context)
+        return false if ignored?(notice)
         return false unless @delivery_pipeline.capture_allowed?("exception", notice.fingerprint)
 
         @delivery_pipeline.enqueue(@serializer.call(notice))
@@ -41,6 +43,7 @@ module Chronos
         return false unless capture_enabled?
 
         notice = build_notice(exception, context)
+        return false if ignored?(notice)
         return false unless @delivery_pipeline.capture_allowed?("exception", notice.fingerprint)
 
         @delivery_pipeline.deliver_sync(@serializer.call(notice))
@@ -59,6 +62,10 @@ module Chronos
         @notice_builder.call(exception, context)
       end
 
+      def ignored?(notice)
+        @ignore_policy && @ignore_policy.ignored?(notice)
+      end
+
       def diagnose(error)
         @logger.warn("Chronos capture failed: #{error.class}")
       end

data/lib/chronos/application/capture_telemetry.rb

@@ -40,6 +40,17 @@ module Chronos
         false
       end
 
+      def call_sync(event_type, payload = {}, context = {})
+        return false unless @config.enabled_for_environment?
+        return false unless synchronous_capture_allowed?(event_type)
+
+        event = Core::TelemetryEvent.new(event_type, payload, context)
+        @delivery_pipeline.deliver_sync(@serializer.call(event))
+      rescue StandardError => error
+        @logger.warn("Chronos synchronous telemetry capture failed: #{error.class}")
+        false
+      end
+
       def flush
         enqueue_batches(@aggregator.flush)
       rescue StandardError => error
@@ -55,6 +66,12 @@ module Chronos
 
       private
 
+      def synchronous_capture_allowed?(event_type)
+        return @delivery_pipeline.event_enabled?(event_type) if event_type.to_s == "deploy"
+
+        @delivery_pipeline.capture_allowed?(event_type)
+      end
+
       def aggregate_type?(event_type)
         ApmAggregator::METRIC_TYPES.include?(event_type.to_s)
       end

data/lib/chronos/application/dependency_reporter.rb

@@ -19,6 +19,17 @@ module Chronos
         @constants = options[:constants] || {}
         @mutex = Mutex.new
         @reported = false
+        @release_override = nil
+      end
+
+      def reset(release = nil)
+        @mutex.synchronize do
+          @release_override = bounded(release, 128)
+          @reported = false
+        end
+        true
+      rescue StandardError
+        false
       end
 
       def call
@@ -45,7 +56,7 @@ module Chronos
           "web_server" => detected("web_server") { web_server },
           "database_adapter" => detected("database_adapter") { database_adapter },
           "sidekiq" => detected("sidekiq") { sidekiq_version },
-          "release" => bounded(@config.app_version.to_s, 128)
+          "release" => @release_override || bounded(@config.app_version.to_s, 128)
         }
         payload.delete_if do |key, value|
           !["dependencies", "ruby"].include?(key) && value.to_s.empty?

data/lib/chronos/application/ignore_policy.rb

@@ -0,0 +1,54 @@
+module Chronos
+  module Application
+    # Stores and evaluates bounded application-owned exception ignore rules.
+    #
+    # @responsibility Decide whether a normalized Notice should be discarded locally.
+    # @motivation Expected application failures should not consume queue or network capacity.
+    # @limits Rules inspect only the bounded Notice API and cannot be installed remotely.
+    # @collaborators CaptureException and application-provided callables.
+    # @thread_safety Rule registration and snapshots are protected by a mutex.
+    # @compatibility Ruby 2.2.10 through Ruby 2.6.
+    # @example
+    #   policy.add { |notice| notice.exception_class == "ExpectedError" }
+    # @errors A failing rule is contained, logged, and treated as not matching.
+    # @performance The number of evaluated rules is capped by configuration.
+    class IgnorePolicy
+      def initialize(rules, limit, logger)
+        @rules = Array(rules).dup
+        @limit = limit
+        @logger = logger
+        @mutex = Mutex.new
+      end
+
+      def add(rule = nil, &block)
+        candidate = rule || block
+        return false unless candidate.respond_to?(:call)
+
+        @mutex.synchronize do
+          return false if @rules.length >= @limit
+
+          @rules << candidate
+        end
+        true
+      rescue StandardError
+        false
+      end
+
+      def ignored?(notice)
+        rules = @mutex.synchronize { @rules.dup }
+        rules.any? { |rule| safely_matches?(rule, notice) }
+      rescue StandardError
+        false
+      end
+
+      private
+
+      def safely_matches?(rule, notice)
+        rule.call(notice) == true
+      rescue StandardError => error
+        @logger.warn("Chronos ignore rule failed: #{error.class}")
+        false
+      end
+    end
+  end
+end

data/lib/chronos/application/remote_configuration.rb

@@ -14,7 +14,7 @@ module Chronos
     # @performance Validation is bounded by configured document and list limits.
     class RemoteConfiguration
       SUPPORTED_EVENT_TYPES = %w(
-        exception request query job cache external_http dependencies metric_batch
+        exception request query job cache external_http dependencies deploy metric_batch
       ).freeze
       MAX_IGNORED_FINGERPRINTS = 100
       MAX_FINGERPRINT_BYTES = 256

data/lib/chronos/capistrano.rb

@@ -0,0 +1,4 @@
+require "chronos"
+require "chronos/integrations/capistrano"
+
+Chronos::Integrations::Capistrano.install(self) if respond_to?(:namespace, true) && respond_to?(:after, true)

data/lib/chronos/configuration/apm_validation.rb

@@ -65,9 +65,20 @@ module Chronos
         unless dependency_max_items.is_a?(Integer) && dependency_max_items >= 1 && dependency_max_items <= 200
           errors << "dependency_max_items must be between 1 and 200"
         end
+        correlation_attributes.each do |name, value|
+          errors << "#{name} must be a String with at most 128 bytes" unless bounded_optional_string?(value, 128)
+        end
         errors
       end
 
+      def correlation_attributes
+        {:revision => revision, :deploy_id => deploy_id, :region => region, :instance_id => instance_id}
+      end
+
+      def bounded_optional_string?(value, limit)
+        value.nil? || (value.is_a?(String) && value.bytesize <= limit)
+      end
+
       def boolean?(value)
         [true, false].include?(value)
       end

data/lib/chronos/configuration/validation.rb

@@ -9,7 +9,7 @@ module Chronos
     # @thread_safety Validation reads one configuration instance without shared state.
     # @compatibility Ruby 2.2.10 through Ruby 2.6.
     # @errors Invalid values become messages; malformed URLs are contained.
-    module ConfigurationValidation
+    module ConfigurationValidation # rubocop:disable Metrics/ModuleLength
       private
 
       def resilience_errors
@@ -60,6 +60,7 @@ module Chronos
         errors.concat(matcher_errors("allowlist_keys", allowlist_keys))
         errors.concat(matcher_errors("hash_keys", hash_keys))
         errors.concat(filter_errors)
+        errors.concat(ignore_rule_errors)
         errors.concat(anonymization_errors)
         errors
       end
@@ -99,6 +100,20 @@ module Chronos
         [true, false].include?(anonymize_ip) ? [] : ["anonymize_ip must be true or false"]
       end
 
+      def ignore_rule_errors
+        errors = []
+        unless ignore_rules.is_a?(Array) && ignore_rules.all? { |rule| rule.respond_to?(:call) }
+          errors << "ignore_rules must contain only callable objects"
+        end
+        unless positive_integer?(max_ignore_rules) && max_ignore_rules <= 100
+          errors << "max_ignore_rules must be an integer between 1 and 100"
+        end
+        if ignore_rules.is_a?(Array) && max_ignore_rules.is_a?(Integer) && ignore_rules.length > max_ignore_rules
+          errors << "ignore_rules cannot exceed max_ignore_rules"
+        end
+        errors
+      end
+
       def matcher_errors(name, values)
         return [] unless values.is_a?(Array)
         return [] if values.all? { |value| value.is_a?(String) || value.is_a?(Symbol) || value.is_a?(Regexp) }

data/lib/chronos/configuration.rb

@@ -32,11 +32,12 @@ module Chronos
 
     ATTRIBUTES = [
       :project_id, :project_key, :host, :environment, :app_version,
-      :service_name, :root_directory, :logger, :timeout, :open_timeout,
+      :service_name, :revision, :deploy_id, :region, :instance_id,
+      :root_directory, :logger, :timeout, :open_timeout,
       :queue_size, :workers, :enabled, :error_notifications,
       :ignored_environments, :proxy, :ssl_verify, :user_agent,
       :max_payload_size, :gzip, :blocklist_keys, :allowlist_keys,
-      :filters, :hash_keys, :anonymize_ip, :max_retries,
+      :filters, :hash_keys, :anonymize_ip, :ignore_rules, :max_ignore_rules, :max_retries,
       :retry_base_interval, :retry_max_interval, :retry_jitter,
       :backlog_size, :circuit_failure_threshold, :circuit_reset_timeout,
       :remote_configuration, :remote_config_max_bytes, :sampling_rate,
@@ -59,6 +60,7 @@ module Chronos
       initialize_rails_defaults
       initialize_apm_defaults
       initialize_observability_defaults
+      initialize_correlation_defaults
     end
 
     def snapshot
@@ -120,6 +122,13 @@ module Chronos
       @breadcrumb_max_bytes = 2048
     end
 
+    def initialize_correlation_defaults
+      @revision = nil
+      @deploy_id = nil
+      @region = nil
+      @instance_id = nil
+    end
+
     def initialize_rails_defaults
       @rails_enabled = true
       @rails_capture_in_console = false
@@ -153,6 +162,8 @@ module Chronos
       @filters = []
       @hash_keys = []
       @anonymize_ip = true
+      @ignore_rules = []
+      @max_ignore_rules = 20
     end
 
     def initialize_resilience_defaults
@@ -167,7 +178,7 @@ module Chronos
       @remote_config_max_bytes = 4096
       @sampling_rate = 1.0
       @enabled_event_types = [
-        "exception", "request", "query", "job", "cache", "external_http", "dependencies", "metric_batch"
+        "exception", "request", "query", "job", "cache", "external_http", "dependencies", "deploy", "metric_batch"
       ]
       @max_remote_send_interval = 60.0
     end

data/lib/chronos/core/correlation_context.rb

@@ -0,0 +1,65 @@
+module Chronos
+  module Core
+    # Builds the bounded release/deploy correlation shared by every event envelope.
+    #
+    # @responsibility Normalize release, revision, deploy, environment, service, region, and instance.
+    # @motivation Give the SaaS stable before/after-deploy dimensions without integration-specific fields.
+    # @limits Values come only from explicit configuration or caller overrides; no environment is scanned.
+    # @collaborators PayloadSerializer, TelemetrySerializer, and Configuration::Snapshot.
+    # @thread_safety Instances hold immutable configuration and calls allocate independent frozen hashes.
+    # @compatibility Ruby 2.2.10 through Ruby 2.6.
+    # @example
+    #   CorrelationContext.new(config).call("revision" => "abc123")
+    # @errors Unreadable optional values become nil and do not escape.
+    # @performance Seven strings are copied with a fixed 128-byte maximum each.
+    class CorrelationContext
+      FIELDS = %w(release revision deploy_id environment service region instance).freeze
+
+      def initialize(config)
+        @config = config
+      end
+
+      def call(overrides = {})
+        values = defaults.merge(string_hash(overrides))
+        result = FIELDS.each_with_object({}) do |name, correlation|
+          correlation[name.freeze] = bounded(values[name], 128)
+        end
+        result.each_value { |value| value.freeze if value }
+        result.freeze
+      rescue StandardError
+        FIELDS.each_with_object({}) { |name, fallback| fallback[name] = nil }.freeze
+      end
+
+      private
+
+      def defaults
+        {
+          "release" => @config.app_version, "revision" => @config.revision,
+          "deploy_id" => @config.deploy_id, "environment" => @config.environment,
+          "service" => @config.service_name, "region" => @config.region,
+          "instance" => @config.instance_id
+        }
+      end
+
+      def string_hash(value)
+        return {} unless value.is_a?(Hash)
+
+        value.each_with_object({}) do |(key, child), result|
+          result[key.to_s] = child if key.is_a?(String) || key.is_a?(Symbol)
+        end
+      end
+
+      def bounded(value, limit)
+        return nil if value.nil?
+        return nil unless value.is_a?(String) || value.is_a?(Symbol) || value.is_a?(Numeric)
+
+        text = value.to_s
+        text = text.scrub("?") if text.respond_to?(:scrub)
+        text = text.byteslice(0, limit) if text.bytesize > limit
+        text
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end