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

data/docs/modules/deploy-tracking.md

@@ -0,0 +1,86 @@
+# Deploy tracking and release correlation
+
+Version `0.9.0.pre.1` adds synchronous deploy notifications and a bounded correlation block to every exception and telemetry envelope. The SaaS can compare errors and performance before and after a release using release, revision, deploy ID, environment, service, region, and instance.
+
+## Public API
+
+Configure the agent, then provide deploy metadata explicitly:
+
+```ruby
+Chronos.notify_deploy(
+  :environment => "production",
+  :revision => ENV["GIT_SHA"],
+  :version => ENV["APP_VERSION"],
+  :repository => "owner/repository",
+  :actor => ENV["DEPLOY_USER"],
+  :deploy_id => ENV["DEPLOY_ID"],
+  :service => "billing",
+  :region => "sa-east-1",
+  :instance => "web-1"
+)
+```
+
+Environment is required, and either revision or version must be present. A UUID deploy ID is generated when none is supplied. The call uses synchronous delivery, bypasses ordinary event sampling, then refreshes the bounded dependency inventory for the new release and flushes it before returning. Local/remote event disabling and the kill switch still apply. It returns `false` instead of leaking configuration, normalization, serialization, or transport failures.
+
+Fields are limited to 128 bytes, except repository at 512 bytes. HTTP and SCP-style repository credentials are stripped before serialization. The shared sanitizer still filters explicit actor/repository content. Do not send access tokens, e-mail addresses, or unnecessary personal data.
+
+## Correlation on application events
+
+Set the values that identify the currently running release during normal application configuration:
+
+```ruby
+Chronos.configure do |config|
+  # project and endpoint settings omitted
+  config.app_version = ENV["APP_VERSION"]
+  config.revision = ENV["GIT_SHA"]
+  config.deploy_id = ENV["DEPLOY_ID"]
+  config.environment = ENV["APP_ENV"] || "production"
+  config.service_name = "billing"
+  config.region = ENV["REGION"]
+  config.instance_id = ENV["INSTANCE_ID"]
+end
+```
+
+The gem never reads these variables itself. The host application chooses each source. Configuration snapshots are immutable, so `notify_deploy` does not mutate correlation for an already running process; newly deployed processes must start with their own release values.
+
+## Capistrano
+
+Require the optional entry point after Capistrano loads:
+
+```ruby
+require "chronos/capistrano"
+
+set :chronos_version, ENV["APP_VERSION"]
+set :chronos_actor, ENV["DEPLOY_USER"]
+set :chronos_deploy_id, ENV["DEPLOY_ID"]
+set :chronos_service, "billing"
+set :chronos_region, ENV["DEPLOY_REGION"]
+```
+
+It registers `chronos:notify_deploy` after `deploy:published`, once per DSL object. Revision, stage, and repository use the public Capistrano variables `current_revision`, `stage`, and `repo_url`; all Chronos-specific values are optional and explicit. The integration adds no Capistrano runtime dependency.
+
+## Manual, Kamal, and GitHub Actions
+
+[`examples/deploy/notify.rb`](../../examples/deploy/notify.rb) is the shared command. It requires project credentials/host and deploy environment, reads only named variables, notifies synchronously, closes the agent, and exits nonzero on failure.
+
+For Kamal, pass the variables to the deployed container or command environment and execute after publication:
+
+```bash
+kamal app exec --reuse "bundle exec ruby examples/deploy/notify.rb"
+```
+
+Adapt the command to the application's Kamal hook lifecycle and secret-management policy. The repository also provides a non-active [GitHub Actions workflow example](../../examples/deploy/github-actions.yml) using read-only repository permission and secret-scoped Chronos credentials.
+
+For a network-free payload demonstration:
+
+```bash
+bundle _1.17.3_ exec ruby examples/plain-ruby/deploy_tracking.rb
+```
+
+## Limitations
+
+- delivery is process-local and uses the existing finite retry/circuit/backlog policy;
+- an unsuccessful synchronous delivery returns `false`; deployment policy decides whether that blocks publication;
+- Capistrano auto-registration requires its task DSL to be loaded first;
+- Kamal integration is command/documentation based, not a Kamal plugin;
+- repository and actor are explicit metadata and remain subject to application privacy review.

data/docs/modules/external-http.md

@@ -0,0 +1,27 @@
+# External HTTP instrumentation
+
+Version `0.8.0.pre.1` provides an optional `Net::HTTP` wrapper loaded through `chronos/net_http`. It is disabled by default and prepended only to a connection object explicitly passed to `Chronos.instrument_net_http`; the `Net::HTTP` class and unrelated instances are unchanged.
+
+```ruby
+require "net/http"
+require "chronos"
+
+Chronos.configure do |config|
+  # connection settings omitted
+  config.external_http_enabled = true
+  config.external_http_trace_headers = true
+end
+
+http = Net::HTTP.new("payments.example.com", 443)
+http.use_ssl = true
+Chronos.instrument_net_http(http)
+response = http.request(Net::HTTP::Get.new("/health"))
+```
+
+The event contains a bounded lowercase host, uppercase method, response status, monotonic duration, timeout flag, connection-error flag, and error class. A request made inside a Chronos context receives `X-Chronos-Trace-ID` and `X-Chronos-Request-ID` unless the application already set those headers. Disable propagation with `external_http_trace_headers = false`.
+
+The wrapper never reads or records the path, query string, Authorization, other request headers, request body, response headers/body, or exception message. The native streaming block is forwarded and the identical HTTP exception is re-raised. Telemetry failures are contained.
+
+Successful and failed calls become bounded `external_http` APM groups keyed only by host and method. A call carrying a trace ID contributes its duration to the enclosing request's `external_http` breakdown. Faraday, HTTP.rb, Excon, and RestClient are outside this release.
+
+Installation is idempotent per object. A `false` result means collection is disabled, the object is incompatible or already instrumented, or installation was contained after an internal error.

data/docs/modules/rails-legacy.md

@@ -29,7 +29,7 @@ The public `ActiveSupport::Notifications.subscribe` API is used for:
 | `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 |
+| 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.
 

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.7.0.pre.1", :require => "chronos/sidekiq"
+gem "chronos-ruby", "0.9.0.pre.1", :require => "chronos/sidekiq"
 ```
 
 `chronos/sidekiq` installs middleware through the public `configure_client` and `configure_server` APIs. It does nothing when Sidekiq is unavailable, and the core gem never requires Sidekiq. Installation adds no Chronos thread or Redis/database connection per job; delivery continues through the agent's existing fixed worker pool.

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`, and `cache` events. These values exist so framework adapters do not model operational timings 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.7 aggregates request, query, and job observations into `metric_batch` events by default. Cache remains an individual event while contributing to an existing traced request breakdown. Set `apm_enabled = false` only when individual legacy telemetry is required for diagnostics. Percentiles remain server-side; see [Essential APM aggregation](apm-aggregation.md).
+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.7 makes no unverified speed claim.
+Performance is a functional requirement, but version 0.9 makes no unverified speed claim.
 
 Current controls:
 
@@ -21,6 +21,11 @@ Current controls:
 - Rails subscribers copy only small allowlisted field sets and never copy raw SQL or job arguments.
 - Sidekiq middleware creates no per-job thread or connection and bounds arguments, collections, nesting, strings, and tags before telemetry capture.
 - APM group, trace, query-fingerprint, histogram, and batch counts are fixed; no APM timer thread is created.
+- 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.
 
@@ -100,3 +105,27 @@ ITERATIONS=100000 bundle _1.17.3_ exec ruby benchmarks/apm_aggregation.rb
 The fixture repeatedly updates one SQL metric group and one trace-local fingerprint. It excludes ActiveSupport dispatch, serialization, queueing, and network delivery. The benchmark must report one retained group; memory must remain bounded by configuration. Record runtime, hardware, warmup, median, and dispersion before publishing a performance claim.
 
 A local diagnostic run on 2026-07-20 used Ruby 2.2.10 on macOS arm64 and 10,000 observations. It retained one group and measured approximately 34.972 microseconds per observation. This single run has no controlled warmup, median, or dispersion and is not a production performance claim.
+
+## Version 0.8 external HTTP benchmark
+
+Run:
+
+```bash
+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.7 sanitizes exception, framework telemetry, and APM metric batches before JSON serialization, queueing, retry backlog, or transport. This reduces accidental exposure, but the host application remains responsible for lawful purpose, minimization, access control, retention, and responses to data-subject requests.
+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
 
@@ -16,8 +16,26 @@ Version 0.7 sanitizes exception, framework telemetry, and APM metric batches bef
 | Request/response bodies, raw query strings, cookies, authorization headers, raw SQL/binds, cache values, mail bodies, environment variables | Never collected automatically |
 | Sidekiq arguments | Collected automatically, limited before sanitization, then redacted by the common policy |
 | SQL | Comments, quoted/numeric/boolean/null literals removed; binds never read; bounded identifiers remain |
+| 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.7 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
+
+Outbound HTTP instrumentation is disabled by default and installed per connection. Trace headers reveal correlation identifiers to the selected destination; enable propagation only for destinations permitted to receive them. The wrapper does not inspect any other header or URL component.
+
+Raw cache keys can contain user or business data and are never delivered. Optional hashing is pseudonymization, not anonymization: predictable low-entropy keys can still be guessed. Dependency reporting is a separate once-per-agent event, never copied into exceptions, and can be disabled. It reads loaded gem name/version pairs only, with no filesystem path, source, configuration, or complete lockfile.
 
 ## Rails telemetry
 

data/docs/troubleshooting.md

@@ -22,7 +22,31 @@ Require `chronos/rails` from the generated initializer and confirm it runs befor
 
 ## 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.
+This is intentional. Chronos records bounded SQL and cache operational metadata without raw statements, binds, keys, or values. Set `cache_key_mode = :sha256` before configuration only when a stable pseudonymous key identity is required.
+
+## External HTTP telemetry is missing
+
+Set `external_http_enabled = true`, then call `Chronos.instrument_net_http(http)` for each `Net::HTTP` instance after Chronos is configured. Existing and future objects are not patched globally. The method returns `false` when disabled, already installed, incompatible, or unconfigured.
+
+## Trace headers should not reach a destination
+
+Set `external_http_trace_headers = false` before configuring the agent, or do not instrument that connection. Chronos preserves an application-supplied Chronos header instead of overwriting it.
+
+## Dependency inventory is missing or incomplete
+
+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
 

data/lib/chronos/agent.rb

@@ -37,13 +37,16 @@ module Chronos
         pipeline_options
       )
       initialize_capture(options)
+      initialize_observability(options)
     end
 
     def notify(exception, context = {})
+      report_dependencies
       @capture.call(exception, context_for_capture(context))
     end
 
     def notify_sync(exception, context = {})
+      report_dependencies
       @capture.call_sync(exception, context_for_capture(context))
     end
 
@@ -64,9 +67,34 @@ 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
 
+    def report_dependencies
+      payload = @dependency_reporter.call
+      return false unless payload
+
+      @telemetry.call("dependencies", payload, {})
+    rescue StandardError => error
+      @logger.warn("Chronos dependency reporting failed: #{error.class}")
+      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] || {}
@@ -87,6 +115,14 @@ module Chronos
       }
     end
 
+    def external_http_integration_options
+      {:enabled => @config.external_http_enabled, :trace_headers => @config.external_http_trace_headers}
+    end
+
+    def cache_integration_options
+      {:project_id => @config.project_id, :key_mode => @config.cache_key_mode}
+    end
+
     # Returns the correlation subset safe for an integration-owned process boundary.
     def propagation_context
       current = context_hash(@context_store.get)
@@ -124,6 +160,7 @@ module Chronos
     end
 
     def flush(timeout = DEFAULT_FLUSH_TIMEOUT)
+      report_dependencies
       @telemetry.flush
       @delivery_pipeline.flush(timeout)
     rescue StandardError => error
@@ -132,6 +169,7 @@ module Chronos
     end
 
     def close(timeout = DEFAULT_FLUSH_TIMEOUT)
+      report_dependencies
       @telemetry.flush
       @delivery_pipeline.close(timeout)
     rescue StandardError => error
@@ -152,6 +190,11 @@ module Chronos
       @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/apm_aggregator.rb

@@ -1,6 +1,6 @@
 module Chronos
   module Application
-    # Aggregates bounded request, query, and job observations into metric batches.
+    # Aggregates bounded request, query, job, and external HTTP observations into metric batches.
     #
     # @responsibility Maintain statistics, histograms, breakdown, and local query signals.
     # @motivation Avoid one network event per observation while retaining diagnostic value.
@@ -14,7 +14,9 @@ module Chronos
     # @errors Invalid observations are ignored and never escape to the application.
     # @performance Group, transaction, query, bucket, and batch counts are strictly bounded.
     class ApmAggregator
-      METRIC_TYPES = %w(request query job).freeze
+      include ApmErrorClassifier
+
+      METRIC_TYPES = %w(request query job external_http).freeze
       def initialize(config)
         @config = config
         @mutex = Mutex.new
@@ -77,7 +79,7 @@ module Chronos
           @groups[key] = aggregate
         end
         duration = non_negative(payload["duration_ms"] || payload[:duration_ms])
-        status = type == "request" ? payload["status"] || payload[:status] : nil
+        status = ["request", "external_http"].include?(type) ? payload["status"] || payload[:status] : nil
         signals = signals_for(type, payload, context, duration)
         breakdown = breakdown_for(type, payload, context, duration)
         aggregate.observe(
@@ -177,6 +179,7 @@ module Chronos
                 when "request" then %w(route method)
                 when "query" then %w(adapter operation table fingerprint normalized_query name cached role shard source)
                 when "job" then %w(kind class queue status)
+                when "external_http" then %w(host method)
                 else []
                 end
         names.each_with_object({}) do |name, result|
@@ -211,17 +214,11 @@ module Chronos
         return "view" if type == "request" && payload["kind"].to_s == "view"
         return "cache" if type == "cache"
         return "queue" if type == "job"
+        return "external_http" if type == "external_http"
 
         nil
       end
 
-      def error?(type, payload)
-        return (payload["status"] || payload[:status]).to_i >= 500 if type == "request"
-        return (payload["status"] || payload[:status]).to_s == "failed" if type == "job"
-
-        !(payload["error_class"] || payload[:error_class]).to_s.empty?
-      end
-
       def trace_id(context)
         (context["trace_id"] || context[:trace_id]).to_s
       end

data/lib/chronos/application/apm_error_classifier.rb

@@ -0,0 +1,27 @@
+module Chronos
+  module Application
+    # Classifies bounded APM observations without inspecting exception messages.
+    module ApmErrorClassifier
+      private
+
+      def error?(type, payload)
+        return status_error?(payload) if type == "request"
+        return (payload["status"] || payload[:status]).to_s == "failed" if type == "job"
+        return external_http_error?(payload) if type == "external_http"
+
+        !(payload["error_class"] || payload[:error_class]).to_s.empty?
+      end
+
+      def external_http_error?(payload)
+        return true unless (payload["error_class"] || payload[:error_class]).to_s.empty?
+        return true if payload["timeout"] == true || payload[:timeout] == true
+
+        status_error?(payload)
+      end
+
+      def status_error?(payload)
+        (payload["status"] || payload[:status]).to_i >= 500
+      end
+    end
+  end
+end

data/lib/chronos/application/capture_telemetry.rb

@@ -4,7 +4,7 @@ module Chronos
     #
     # @responsibility Aggregate APM observations or serialize and enqueue integration events.
     # @motivation Keep framework policy and local batching outside transport and domain objects.
-    # @limits It handles request, query, job, cache, and metric-batch events only.
+    # @limits It handles only the event types declared by TelemetryEvent.
     # @collaborators ApmAggregator, 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.
@@ -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

@@ -0,0 +1,140 @@
+module Chronos
+  module Application
+    # Builds one bounded inventory from already loaded runtime components.
+    #
+    # @responsibility Report loaded gems and runtime/framework versions once per agent.
+    # @motivation Dependency context aids diagnosis without attaching the bundle to every error.
+    # @limits It does not read lockfiles, environment variables, gem paths, or open DB connections.
+    # @collaborators RubyGems loaded specs and immutable Chronos configuration.
+    # @thread_safety A mutex guarantees at-most-once collection across concurrent first events.
+    # @compatibility Ruby 2.2.10 through Ruby 2.6; all framework detection is optional.
+    # @example
+    #   payload = DependencyReporter.new(config).call
+    # @errors Detection failures yield omitted fields and never escape.
+    # @performance Runs once and visits at most the configured number of loaded specs.
+    class DependencyReporter
+      def initialize(config, options = {})
+        @config = config
+        @loaded_specs = options[:loaded_specs] || proc { Gem.loaded_specs }
+        @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
+        @mutex.synchronize do
+          return nil if @reported || !@config.dependency_reporting
+
+          @reported = true
+          build_payload
+        end
+      rescue StandardError
+        nil
+      end
+
+      private
+
+      def build_payload
+        payload = {
+          "dependencies" => dependencies,
+          "ruby" => {
+            "version" => bounded(RUBY_VERSION, 64), "engine" => bounded(ruby_engine, 64),
+            "platform" => bounded(RUBY_PLATFORM, 128)
+          },
+          "rails" => detected("rails") { rails_version },
+          "web_server" => detected("web_server") { web_server },
+          "database_adapter" => detected("database_adapter") { database_adapter },
+          "sidekiq" => detected("sidekiq") { sidekiq_version },
+          "release" => @release_override || bounded(@config.app_version.to_s, 128)
+        }
+        payload.delete_if do |key, value|
+          !["dependencies", "ruby"].include?(key) && value.to_s.empty?
+        end
+        payload
+      end
+
+      def dependencies
+        specs = @loaded_specs.call
+        values = specs.respond_to?(:values) ? specs.values : []
+        values.first(@config.dependency_max_items).sort_by { |spec| spec.name.to_s }.map do |spec|
+          {"name" => bounded(spec.name.to_s, 128), "version" => bounded(spec.version.to_s, 64)}
+        end
+      rescue StandardError
+        []
+      end
+
+      def detected(name)
+        explicit = @constants[name]
+        return bounded(explicit.to_s, 128) unless explicit.nil?
+
+        bounded(yield.to_s, 128)
+      rescue StandardError
+        ""
+      end
+
+      def rails_version
+        defined?(::Rails) && ::Rails.respond_to?(:version) ? ::Rails.version.to_s : loaded_version("rails")
+      end
+
+      def sidekiq_version
+        defined?(::Sidekiq::VERSION) ? ::Sidekiq::VERSION.to_s : loaded_version("sidekiq")
+      end
+
+      def web_server
+        return "Puma" if defined?(::Puma)
+        return "Unicorn" if defined?(::Unicorn)
+        return "Passenger" if defined?(::PhusionPassenger)
+        return "WEBrick" if defined?(::WEBrick)
+
+        ""
+      end
+
+      def database_adapter
+        names = loaded_spec_names
+        return "PostgreSQL" if names.include?("pg")
+        return "MySQL" if names.include?("mysql2")
+        return "SQLite" if names.include?("sqlite3")
+
+        ""
+      end
+
+      def loaded_version(name)
+        specs = @loaded_specs.call
+        spec = specs[name] || specs[name.to_sym] if specs.respond_to?(:[])
+        spec ? spec.version.to_s : ""
+      rescue StandardError
+        ""
+      end
+
+      def loaded_spec_names
+        specs = @loaded_specs.call
+        specs.respond_to?(:keys) ? specs.keys.map(&:to_s) : []
+      rescue StandardError
+        []
+      end
+
+      def ruby_engine
+        defined?(RUBY_ENGINE) ? RUBY_ENGINE : "ruby"
+      end
+
+      def bounded(value, limit)
+        text = value.to_s
+        text = text.scrub("?") if text.respond_to?(:scrub)
+        text.bytesize > limit ? text.byteslice(0, limit) : text
+      rescue StandardError
+        ""
+      end
+    end
+  end
+end

data/lib/chronos/application/remote_configuration.rb

@@ -13,7 +13,9 @@ 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", "request", "query", "job", "cache", "metric_batch"].freeze
+      SUPPORTED_EVENT_TYPES = %w(
+        exception request query job cache external_http dependencies deploy metric_batch
+      ).freeze
       MAX_IGNORED_FINGERPRINTS = 100
       MAX_FINGERPRINT_BYTES = 256
       MIN_PAYLOAD_SIZE = 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)