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

data/lib/chronos/core/deploy_normalizer.rb

@@ -0,0 +1,102 @@
+require "securerandom"
+require "uri"
+
+module Chronos
+  module Core
+    # Normalizes explicit deployment metadata into the versioned deploy payload.
+    #
+    # @responsibility Validate required deploy identity and bound every public API field.
+    # @motivation Deployment commands need predictable safe input independent of frameworks.
+    # @limits It does not inspect Git, environment variables, credentials, or deployment systems.
+    # @collaborators Chronos.notify_deploy, CorrelationContext, and Configuration::Snapshot.
+    # @thread_safety Stateless apart from immutable configuration and an injected ID generator.
+    # @compatibility Ruby 2.2.10 through Ruby 2.6.
+    # @example
+    #   DeployNormalizer.new(config).call(:revision => "abc", :version => "1.2.3")
+    # @errors Missing environment or both revision/version raise ArgumentError for the agent to contain.
+    # @performance Constant work over nine bounded scalar fields.
+    class DeployNormalizer
+      def initialize(config, options = {})
+        @config = config
+        @id_generator = options[:id_generator] || proc { SecureRandom.uuid }
+      end
+
+      def call(attributes = {})
+        values = string_hash(attributes)
+        payload = {
+          "deploy_id" => deploy_id(values["deploy_id"] || @config.deploy_id),
+          "environment" => bounded(values["environment"] || @config.environment, 128),
+          "revision" => bounded(values["revision"] || @config.revision, 128),
+          "version" => bounded(values["version"] || @config.app_version, 128),
+          "repository" => repository(values["repository"]),
+          "actor" => bounded(values["actor"], 128),
+          "service" => bounded(values["service"] || @config.service_name, 128),
+          "region" => bounded(values["region"] || @config.region, 128),
+          "instance" => bounded(values["instance"] || @config.instance_id, 128)
+        }
+        validate!(payload)
+        payload
+      end
+
+      private
+
+      def validate!(payload)
+        raise ArgumentError, "deploy environment is required" if payload["environment"].to_s.empty?
+        return unless payload["revision"].to_s.empty? && payload["version"].to_s.empty?
+
+        raise ArgumentError, "deploy revision or version is required"
+      end
+
+      def generated_id
+        value = bounded(@id_generator.call, 128)
+        raise ArgumentError, "deploy ID is required" if value.to_s.empty?
+
+        value
+      end
+
+      def deploy_id(value)
+        normalized = bounded(value, 128)
+        normalized.to_s.empty? ? generated_id : normalized
+      end
+
+      def repository(value)
+        text = bounded(value, 512)
+        return nil if text.nil?
+
+        scp = text.match(/\A[^@]+@([^:]+):(.+)\z/)
+        return bounded("#{scp[1]}/#{scp[2]}", 512) if scp
+
+        uri = URI.parse(text)
+        return bounded("#{uri.host}#{uri.path}", 512) if uri.host
+        return bounded(uri.path, 512) unless uri.path.to_s.empty?
+
+        nil
+      rescue StandardError
+        nil
+      end
+
+      def string_hash(value)
+        raise ArgumentError, "deploy attributes must be a Hash" 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 scalar?(value)
+
+        text = value.to_s
+        text = text.scrub("?") if text.respond_to?(:scrub)
+        text.bytesize > limit ? text.byteslice(0, limit) : text
+      rescue StandardError
+        nil
+      end
+
+      def scalar?(value)
+        value.is_a?(String) || value.is_a?(Symbol) || value.is_a?(Numeric)
+      end
+    end
+  end
+end

data/lib/chronos/core/payload_serializer.rb

@@ -44,6 +44,7 @@ module Chronos
         @sanitizer = options[:sanitizer] || Sanitizer.new(config)
         @safe_serializer = options[:safe_serializer] || SafeSerializer.new
         @max_payload_size = options[:max_payload_size] || proc { @config.max_payload_size }
+        @correlation = options[:correlation] || CorrelationContext.new(config)
       end
 
       def call(notice)
@@ -70,8 +71,10 @@ module Chronos
           "service" => {
             "name" => @config.service_name,
             "version" => @config.app_version,
-            "instance_id" => notice.host
+            "instance_id" => @config.instance_id || notice.host
           },
+          "correlation" => @correlation.call("environment" => notice.environment,
+                                             "instance" => @config.instance_id || notice.host),
           "runtime" => notice.runtime,
           "context" => notice.context,
           "payload" => payload(notice)

data/lib/chronos/core/telemetry_event.rb

@@ -16,7 +16,7 @@ module Chronos
     # @errors Unsupported types raise ArgumentError during construction.
     # @performance Construction is linear in supplied context and payload size.
     class TelemetryEvent
-      TYPES = %w(request query job cache external_http dependencies metric_batch).freeze
+      TYPES = %w(request query job cache external_http dependencies deploy metric_batch).freeze
 
       attr_reader :event_id, :event_type, :timestamp, :context, :payload
 
@@ -68,6 +68,7 @@ module Chronos
         @safe_serializer = options[:safe_serializer] || SafeSerializer.new
         @max_payload_size = options[:max_payload_size] || proc { @config.max_payload_size }
         @runtime_info = RuntimeInfo.new
+        @correlation = options[:correlation] || CorrelationContext.new(config)
       end
 
       def call(event)
@@ -89,13 +90,39 @@ module Chronos
           "schema_version" => "1.0", "event_id" => event.event_id,
           "event_type" => event.event_type, "occurred_at" => event.timestamp,
           "sent_at" => @clock.call.utc.iso8601(6), "project_key" => @config.project_id,
-          "environment" => @config.environment,
-          "service" => {"name" => @config.service_name, "version" => @config.app_version,
-                        "instance_id" => runtime[:host]},
+          "environment" => event_environment(event),
+          "service" => event_service(event, runtime),
+          "correlation" => event_correlation(event, runtime),
           "runtime" => runtime[:runtime], "context" => event.context, "payload" => event.payload
         }
       end
 
+      def event_environment(event)
+        event.event_type == "deploy" ? event.payload["environment"] : @config.environment
+      end
+
+      def event_service(event, runtime)
+        deploy = event.event_type == "deploy" ? event.payload : {}
+        {
+          "name" => deploy["service"] || @config.service_name,
+          "version" => deploy["version"] || @config.app_version,
+          "instance_id" => deploy["instance"] || @config.instance_id || runtime[:host]
+        }
+      end
+
+      def event_correlation(event, runtime)
+        overrides = {"instance" => @config.instance_id || runtime[:host]}
+        if event.event_type == "deploy"
+          overrides.merge!(
+            "release" => event.payload["version"], "revision" => event.payload["revision"],
+            "deploy_id" => event.payload["deploy_id"], "environment" => event.payload["environment"],
+            "service" => event.payload["service"], "region" => event.payload["region"],
+            "instance" => event.payload["instance"]
+          )
+        end
+        @correlation.call(overrides)
+      end
+
       def compact_envelope(envelope)
         envelope["context"] = {"_truncated" => true}
         envelope["payload"] = {"_truncated" => true}

data/lib/chronos/integrations/active_job.rb

@@ -0,0 +1,119 @@
+require "securerandom"
+
+module Chronos
+  module Integrations
+    # Propagates bounded Chronos context through Active Job serialization.
+    #
+    # @responsibility Add trace/request identifiers to the job envelope and restore them while performing.
+    # @motivation Active Job adapters commonly cross process boundaries where thread-local context is lost.
+    # @limits It changes only a namespaced serialization field, never public job arguments or adapter behavior.
+    # @collaborators ActiveJob::Base serialization hooks and the Chronos facade.
+    # @thread_safety Installation is mutex-protected and each job owns its restored context.
+    # @compatibility Active Job shipped with Rails 4.2 through Rails 5.2.
+    # @example
+    #   Chronos::Integrations::ActiveJob.install(ActiveJob::Base)
+    # @errors Context failures are contained so enqueue and perform semantics remain unchanged.
+    # @performance Adds at most two strings of 128 bytes to a serialized job.
+    module ActiveJob
+      CONTEXT_KEY = "chronos_context".freeze
+      SCHEMA_VERSION = "1.0".freeze
+      MAX_IDENTIFIER_BYTES = 128
+
+      @mutex = Mutex.new
+
+      class << self
+        def install(base = nil, notifier = Chronos)
+          target = base || (::ActiveJob::Base if defined?(::ActiveJob::Base))
+          return false unless target && target.respond_to?(:prepend)
+
+          @mutex.synchronize do
+            return false if target.ancestors.include?(JobExtensions)
+
+            JobExtensions.notifier = notifier
+            target.send(:prepend, JobExtensions)
+          end
+          true
+        rescue StandardError
+          false
+        end
+
+        def envelope(notifier)
+          source = notifier.respond_to?(:propagation_context) ? notifier.propagation_context : {}
+          source = {} unless source.is_a?(Hash)
+          context = %w(trace_id request_id).each_with_object({}) do |key, result|
+            value = source[key] || source[key.to_sym]
+            result[key] = bounded(value) unless value.to_s.empty?
+          end
+          context["trace_id"] = SecureRandom.uuid if context["trace_id"].to_s.empty?
+          {"schema_version" => SCHEMA_VERSION, "context" => context}
+        rescue StandardError
+          nil
+        end
+
+        def context(value)
+          return {} unless value.is_a?(Hash)
+          return {} unless (value["schema_version"] || value[:schema_version]).to_s == SCHEMA_VERSION
+
+          source = value["context"] || value[:context]
+          return {} unless source.is_a?(Hash)
+
+          %w(trace_id request_id).each_with_object({}) do |key, result|
+            candidate = source[key] || source[key.to_sym]
+            result[key] = bounded(candidate) unless candidate.to_s.empty?
+          end
+        rescue StandardError
+          {}
+        end
+
+        private
+
+        def bounded(value)
+          string = value.to_s
+          return string if string.bytesize <= MAX_IDENTIFIER_BYTES
+
+          string.byteslice(0, MAX_IDENTIFIER_BYTES)
+        rescue StandardError
+          ""
+        end
+      end
+
+      # Active Job instance hooks installed through Module#prepend.
+      module JobExtensions
+        class << self
+          attr_accessor :notifier
+        end
+
+        def serialize(*arguments)
+          data = super
+          begin
+            envelope = Chronos::Integrations::ActiveJob.envelope(JobExtensions.notifier || Chronos)
+            data[CONTEXT_KEY] = envelope if data.is_a?(Hash) && envelope
+          rescue StandardError
+            nil
+          end
+          data
+        end
+
+        def deserialize(job_data)
+          result = super
+          begin
+            @chronos_context = Chronos::Integrations::ActiveJob.context(
+              job_data.is_a?(Hash) ? (job_data[CONTEXT_KEY] || job_data[CONTEXT_KEY.to_sym]) : nil
+            )
+          rescue StandardError
+            @chronos_context = {}
+          end
+          result
+        end
+
+        def perform_now(*arguments, &block)
+          context = @chronos_context || {}
+          notifier = JobExtensions.notifier || Chronos
+          return super if context.empty? || !notifier.respond_to?(:with_context)
+
+          notifier.with_context(:context => context) { super }
+        end
+      end
+    end
+  end
+end

data/lib/chronos/integrations/capistrano.rb

@@ -0,0 +1,61 @@
+module Chronos
+  module Integrations
+    # Optional Capistrano task installer using only the public task DSL.
+    #
+    # @responsibility Register one post-publish task that delegates explicit values to notify_deploy.
+    # @motivation Legacy deployments need release reporting without a Capistrano runtime dependency.
+    # @limits Values are read only from configured Capistrano variables; Git and ENV are not inspected.
+    # @collaborators Capistrano/Rake DSL and the Chronos public facade.
+    # @thread_safety Installation is idempotent per DSL object before task execution.
+    # @compatibility Capistrano task DSLs available to supported Ruby 2.2.10 through Ruby 2.6 apps.
+    # @example
+    #   require "chronos/capistrano"
+    # @errors Missing DSL methods return false; notification failures are contained by Chronos.
+    # @performance Adds one task and one after hook; no background worker is created.
+    module Capistrano
+      INSTALLED_KEY = :@__chronos_capistrano_installed
+
+      class << self
+        def install(dsl)
+          return false if dsl.instance_variable_get(INSTALLED_KEY)
+          return false unless compatible?(dsl)
+
+          dsl.send(:namespace, :chronos) do
+            dsl.send(:desc, "Notify Chronos about the published deployment") if dsl.respond_to?(:desc, true)
+            dsl.send(:task, :notify_deploy) { notify(dsl) }
+          end
+          dsl.send(:after, "deploy:published", "chronos:notify_deploy")
+          dsl.instance_variable_set(INSTALLED_KEY, true)
+          true
+        rescue StandardError
+          false
+        end
+
+        def notify(dsl)
+          Chronos.notify_deploy(
+            :environment => value(dsl, :stage).to_s,
+            :revision => value(dsl, :current_revision) || value(dsl, :branch),
+            :version => value(dsl, :chronos_version) || value(dsl, :release_name),
+            :repository => value(dsl, :repo_url), :actor => value(dsl, :chronos_actor),
+            :deploy_id => value(dsl, :chronos_deploy_id), :service => value(dsl, :chronos_service),
+            :region => value(dsl, :chronos_region), :instance => value(dsl, :chronos_instance)
+          )
+        rescue StandardError
+          false
+        end
+
+        private
+
+        def compatible?(dsl)
+          [:namespace, :task, :after, :fetch].all? { |name| dsl.respond_to?(name, true) }
+        end
+
+        def value(dsl, name)
+          dsl.send(:fetch, name, nil)
+        rescue StandardError
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/chronos/observability_facade.rb

@@ -1,7 +1,7 @@
 module Chronos
-  # Public entry points for optional version 0.8 observability integrations.
+  # Public entry points for optional observability and deployment integrations.
   #
-  # @responsibility Delegate dependency, cache, and outbound HTTP integration calls to the agent.
+  # @responsibility Delegate dependency, cache, outbound HTTP, and deploy calls to the agent.
   # @motivation Keep the main public facade small while preserving one stable Chronos namespace.
   # @limits It installs only explicitly supplied Net::HTTP connections and never enables features.
   # @collaborators Chronos::Agent and Chronos::Integrations::NetHttp.
@@ -19,6 +19,13 @@ module Chronos
       false
     end
 
+    def notify_deploy(attributes = {}, timeout = Agent::DEFAULT_FLUSH_TIMEOUT)
+      agent = current_agent
+      agent ? agent.notify_deploy(attributes, timeout) : false
+    rescue StandardError
+      false
+    end
+
     def external_http_integration_options
       agent = current_agent
       agent ? agent.external_http_integration_options : {:enabled => false}

data/lib/chronos/rails/installer.rb

@@ -33,6 +33,7 @@ module Chronos
           return false if self.class.applications[application.object_id]
 
           install_middleware(application, options)
+          install_active_job
           @subscriber.install
           self.class.applications[application.object_id] = true
         end
@@ -58,6 +59,12 @@ module Chronos
         true
       end
 
+      def install_active_job
+        return false unless defined?(::ActiveJob::Base)
+
+        Chronos::Integrations::ActiveJob.install(::ActiveJob::Base, @notifier)
+      end
+
       def environment
         defined?(::Rails) && ::Rails.respond_to?(:env) ? ::Rails.env.to_s : nil
       end

data/lib/chronos/rails/notifications_subscriber.rb

@@ -144,11 +144,39 @@ module Chronos
 
       def active_job(payload, duration)
         job = value(payload, :job)
+        exception = job_exception(payload)
         data = {
           "kind" => "active_job", "class" => safe_class_name(job),
-          "queue" => safe_job_value(job, :queue_name), "duration_ms" => duration
+          "adapter" => active_job_adapter(job), "job_id" => safe_job_value(job, :job_id),
+          "provider_job_id" => safe_job_value(job, :provider_job_id),
+          "queue" => safe_job_value(job, :queue_name), "attempts" => job_attempts(job),
+          "duration_ms" => duration, "status" => exception ? "failed" : "completed"
         }
+        data["error_class"] = exception.class.name.to_s if exception
         @notifier.record_event("job", data)
+        @notifier.notify_once(exception, :context => {"job" => data}) if exception
+      end
+
+      def job_exception(payload)
+        exception = value(payload, :exception_object)
+        details = value(payload, :exception)
+        exception ||= RuntimeError.new(Array(details).last.to_s) if details
+        exception
+      end
+
+      def active_job_adapter(job)
+        adapter = job.respond_to?(:queue_adapter) ? job.queue_adapter : nil
+        adapter = adapter.class if adapter && !adapter.is_a?(Class)
+        adapter ? adapter.name.to_s.split("::").last.to_s.sub(/Adapter$/, "") : ""
+      rescue StandardError
+        ""
+      end
+
+      def job_attempts(job)
+        value = job.respond_to?(:executions) ? job.executions : 0
+        value.is_a?(Numeric) ? value.to_i : 0
+      rescue StandardError
+        0
       end
 
       def cache(name, payload, duration)

data/lib/chronos/rails.rb

@@ -1,5 +1,6 @@
 require "chronos"
 require "chronos/rails/notifications_subscriber"
+require "chronos/integrations/active_job"
 require "chronos/rails/installer"
 
 require "chronos/rails/railtie" if defined?(::Rails::Railtie)

data/lib/chronos/version.rb

@@ -1,4 +1,4 @@
 module Chronos
   # Current version of the legacy Chronos Ruby agent.
-  VERSION = "0.8.0.pre.1".freeze
+  VERSION = "0.9.0.pre.2".freeze
 end

data/lib/chronos.rb

@@ -14,6 +14,8 @@ require "chronos/core/notice_builder"
 require "chronos/core/sensitive_value_filter"
 require "chronos/core/sanitizer"
 require "chronos/core/safe_serializer"
+require "chronos/core/correlation_context"
+require "chronos/core/deploy_normalizer"
 require "chronos/core/payload_serializer"
 require "chronos/core/telemetry_event"
 require "chronos/core/sql_normalizer"
@@ -31,6 +33,7 @@ require "chronos/core/breadcrumb"
 require "chronos/application/retry_policy"
 require "chronos/application/circuit_breaker"
 require "chronos/application/remote_configuration"
+require "chronos/application/ignore_policy"
 require "chronos/application/delivery_pipeline"
 require "chronos/application/capture_exception"
 require "chronos/application/apm_error_classifier"
@@ -58,7 +61,7 @@ require "chronos/integrations/rack/middleware"
 #     config.host = "https://chronos.example.com"
 #   end
 #   Chronos.notify(RuntimeError.new("failed"))
-module Chronos
+module Chronos # rubocop:disable Metrics/ModuleLength
   extend ObservabilityFacade
 
   @mutex = Mutex.new
@@ -142,6 +145,13 @@ module Chronos
       false
     end
 
+    def ignore_if(&block)
+      agent = current_agent
+      agent ? agent.ignore_if(&block) : false
+    rescue StandardError
+      false
+    end
+
     def rails_integration_options(environment = nil, console = false)
       agent = current_agent
       agent ? agent.rails_integration_options(environment, console) : {:enabled => false}

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: chronos-ruby
 version: !ruby/object:Gem::Version
-  version: 0.8.0.pre.1
+  version: 0.9.0.pre.2
 platform: ruby
 authors:
 - Antonio Jefferson
@@ -88,6 +88,7 @@ files:
 - SECURITY.md
 - contracts/apm-batch-v1.schema.json
 - contracts/dependencies-v1.schema.json
+- contracts/deploy-v1.schema.json
 - contracts/event-v1.schema.json
 - contracts/rack-context-v1.schema.json
 - contracts/sidekiq-job-v1.schema.json
@@ -103,17 +104,24 @@ files:
 - docs/adr/ADR-014-sidekiq-envelope-context.md
 - docs/adr/ADR-015-bounded-apm-aggregation.md
 - docs/adr/ADR-016-explicit-observability-integrations.md
+- docs/adr/ADR-017-deploy-events-and-correlation.md
+- docs/adr/ADR-018-pre-1.0-hardening.md
 - docs/architecture.md
 - docs/compatibility.md
 - docs/configuration.md
 - docs/data-collected.md
+- docs/deprecation-policy.md
 - docs/examples/plain-ruby.md
+- docs/migration-from-airbrake.md
+- docs/modules/active-job.md
 - docs/modules/apm-aggregation.md
 - docs/modules/async-queue.md
 - docs/modules/cache-observability.md
 - docs/modules/configuration.md
 - docs/modules/dependencies.md
+- docs/modules/deploy-tracking.md
 - docs/modules/external-http.md
+- docs/modules/ignore-rules.md
 - docs/modules/notice-pipeline.md
 - docs/modules/rack-context.md
 - docs/modules/rails-legacy.md
@@ -126,6 +134,10 @@ files:
 - docs/modules/transport.md
 - docs/performance.md
 - docs/privacy-lgpd.md
+- docs/protocol-v1.md
+- docs/release-1.0-readiness.md
+- docs/security-review.md
+- docs/semver.md
 - docs/troubleshooting.md
 - lib/chronos.rb
 - lib/chronos/adapters.rb
@@ -140,8 +152,10 @@ files:
 - lib/chronos/application/circuit_breaker.rb
 - lib/chronos/application/delivery_pipeline.rb
 - lib/chronos/application/dependency_reporter.rb
+- lib/chronos/application/ignore_policy.rb
 - lib/chronos/application/remote_configuration.rb
 - lib/chronos/application/retry_policy.rb
+- lib/chronos/capistrano.rb
 - lib/chronos/configuration.rb
 - lib/chronos/configuration/apm_validation.rb
 - lib/chronos/configuration/snapshot.rb
@@ -150,6 +164,8 @@ files:
 - lib/chronos/core/backtrace_parser.rb
 - lib/chronos/core/breadcrumb.rb
 - lib/chronos/core/cache_normalizer.rb
+- lib/chronos/core/correlation_context.rb
+- lib/chronos/core/deploy_normalizer.rb
 - lib/chronos/core/exception_cause_collector.rb
 - lib/chronos/core/metric_aggregate.rb
 - lib/chronos/core/notice.rb
@@ -163,6 +179,8 @@ files:
 - lib/chronos/core/telemetry_event.rb
 - lib/chronos/errors.rb
 - lib/chronos/integrations.rb
+- lib/chronos/integrations/active_job.rb
+- lib/chronos/integrations/capistrano.rb
 - lib/chronos/integrations/job_payload.rb
 - lib/chronos/integrations/net_http.rb
 - lib/chronos/integrations/rack.rb