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

data/lib/chronos/rails/installer.rb

@@ -0,0 +1,70 @@
+module Chronos
+  module Rails
+    # Installs Rails middleware and subscribers exactly once per application.
+    #
+    # @responsibility Apply feature-detected integration hooks after Rails initializers load.
+    # @motivation Centralize version-neutral installation outside Railtie DSL code.
+    # @limits It does not configure credentials or depend on private Rails APIs.
+    # @collaborators Rails application middleware, NotificationsSubscriber, and Chronos facade.
+    # @thread_safety A mutex protects the per-application installation registry.
+    # @compatibility Rails 4.2 through Rails 5.2 without Zeitwerk.
+    # @example
+    #   Chronos::Rails::Installer.new.install(Rails.application)
+    # @errors Missing optional Rails capabilities return false without affecting boot.
+    # @performance Installation is one-time; request work is delegated to bounded integrations.
+    class Installer
+      @mutex = Mutex.new
+      @applications = {}
+
+      class << self
+        attr_reader :mutex, :applications
+      end
+
+      def initialize(notifier = Chronos, subscriber = nil)
+        @notifier = notifier
+        @subscriber = subscriber || NotificationsSubscriber.new(notifier)
+      end
+
+      def install(application)
+        options = @notifier.rails_integration_options(environment, console?)
+        return false unless options[:enabled]
+
+        self.class.mutex.synchronize do
+          return false if self.class.applications[application.object_id]
+
+          install_middleware(application, options)
+          @subscriber.install
+          self.class.applications[application.object_id] = true
+        end
+        true
+      rescue StandardError
+        false
+      end
+
+      def rails_version
+        defined?(::Rails) && ::Rails.respond_to?(:version) ? ::Rails.version.to_s : "unknown"
+      end
+
+      private
+
+      def install_middleware(application, options)
+        middleware = application.config.middleware
+        return false unless middleware.respond_to?(:use)
+
+        middleware.use(
+          Chronos::Integrations::Rack::Middleware,
+          :include_user_agent => options[:include_user_agent]
+        )
+        true
+      end
+
+      def environment
+        defined?(::Rails) && ::Rails.respond_to?(:env) ? ::Rails.env.to_s : nil
+      end
+
+      def console?
+        defined?(::Rails::Console)
+      end
+    end
+  end
+end

data/lib/chronos/rails/notifications_subscriber.rb

@@ -0,0 +1,203 @@
+module Chronos
+  module Rails
+    # Converts public ActiveSupport notifications into bounded Chronos telemetry.
+    #
+    # @responsibility Subscribe once and normalize controller, view, SQL, mailer, job, and cache events.
+    # @motivation Support Rails 4.2 and 5.2 through feature detection and public notification APIs.
+    # @limits It never sends SQL text, bind values, cache keys, mail bodies, or job arguments.
+    # @collaborators ActiveSupport::Notifications and the Chronos facade.
+    # @thread_safety Subscription registry is mutex-protected; callbacks own their state.
+    # @compatibility ActiveSupport notification argument shapes from Rails 4.2 through 5.2.
+    # @example
+    #   Chronos::Rails::NotificationsSubscriber.new.install
+    # @errors Subscriber failures are contained and never escape into Rails.
+    # @performance Each notification builds a small allowlisted hash and queues asynchronously.
+    class NotificationsSubscriber
+      EVENTS = %w(
+        process_action.action_controller render_template.action_view sql.active_record
+        deliver.action_mailer perform.active_job cache_read.active_support
+        cache_write.active_support cache_fetch_hit.active_support
+      ).freeze
+
+      @mutex = Mutex.new
+      @installed_buses = {}
+
+      class << self
+        attr_reader :mutex, :installed_buses
+      end
+
+      def initialize(notifier = Chronos, notifications = nil)
+        @notifier = notifier
+        @notifications = notifications || active_support_notifications
+      end
+
+      def install
+        return false unless @notifications && @notifications.respond_to?(:subscribe)
+
+        self.class.mutex.synchronize do
+          return false if self.class.installed_buses[@notifications.object_id]
+
+          event_names.each { |name| subscribe(name) }
+          self.class.installed_buses[@notifications.object_id] = true
+        end
+        true
+      rescue StandardError
+        false
+      end
+
+      def handle(name, arguments)
+        event = notification_event(name, arguments)
+        dispatch(name, event[:payload], event[:duration_ms])
+      rescue StandardError
+        false
+      end
+
+      private
+
+      def active_support_notifications
+        return nil unless defined?(::ActiveSupport::Notifications)
+
+        ::ActiveSupport::Notifications
+      end
+
+      def subscribe(name)
+        @notifications.subscribe(name) { |*arguments| handle(name, arguments) }
+      end
+
+      def event_names
+        return EVENTS if defined?(::ActiveJob)
+
+        EVENTS.reject { |name| name == "perform.active_job" }
+      end
+
+      def notification_event(name, arguments)
+        candidate = arguments.first
+        if arguments.length == 1 && candidate.respond_to?(:payload)
+          return {:payload => hash(candidate.payload), :duration_ms => candidate.duration.to_f}
+        end
+
+        started_at = arguments[1]
+        finished_at = arguments[2]
+        {
+          :payload => hash(arguments[4]),
+          :duration_ms => duration_ms(started_at, finished_at),
+          :name => name
+        }
+      end
+
+      def dispatch(name, payload, duration)
+        case name
+        when "process_action.action_controller" then process_action(payload, duration)
+        when "render_template.action_view" then render_template(payload, duration)
+        when "sql.active_record" then sql(payload, duration)
+        when "deliver.action_mailer" then mailer(payload, duration)
+        when "perform.active_job" then active_job(payload, duration)
+        else cache(name, payload, duration)
+        end
+      end
+
+      def process_action(payload, duration)
+        capture_controller_exception(payload)
+        data = {
+          "kind" => "controller", "controller" => value(payload, :controller),
+          "action" => value(payload, :action), "status" => value(payload, :status).to_i,
+          "method" => value(payload, :method), "path" => query_free_path(value(payload, :path)),
+          "route" => route(payload),
+          "duration_ms" => duration, "parameters" => hash(value(payload, :params))
+        }
+        @notifier.record_event("request", data)
+      end
+
+      def render_template(payload, duration)
+        data = {
+          "kind" => "view", "template" => safe_basename(value(payload, :identifier)),
+          "duration_ms" => duration
+        }
+        @notifier.record_event("request", data)
+      end
+
+      def sql(payload, duration)
+        data = {
+          "name" => value(payload, :name).to_s, "cached" => value(payload, :cached) == true,
+          "duration_ms" => duration
+        }
+        @notifier.record_event("query", data)
+      end
+
+      def mailer(payload, duration)
+        data = {
+          "kind" => "mailer", "mailer" => value(payload, :mailer).to_s,
+          "action" => value(payload, :action).to_s, "duration_ms" => duration
+        }
+        @notifier.record_event("job", data)
+      end
+
+      def active_job(payload, duration)
+        job = value(payload, :job)
+        data = {
+          "kind" => "active_job", "class" => safe_class_name(job),
+          "queue" => safe_job_value(job, :queue_name), "duration_ms" => duration
+        }
+        @notifier.record_event("job", data)
+      end
+
+      def cache(name, payload, duration)
+        data = {
+          "operation" => name.split(".").first, "store" => value(payload, :store).to_s,
+          "hit" => value(payload, :hit), "duration_ms" => duration
+        }
+        @notifier.record_event("cache", data)
+      end
+
+      def capture_controller_exception(payload)
+        exception = value(payload, :exception_object)
+        details = value(payload, :exception)
+        exception ||= RuntimeError.new(Array(details).last.to_s) if details
+        @notifier.notify_once(exception, :parameters => hash(value(payload, :params))) if exception
+      end
+
+      def value(payload, key)
+        payload.key?(key) ? payload[key] : payload[key.to_s]
+      end
+
+      def hash(value)
+        value.is_a?(Hash) ? value : {}
+      end
+
+      def duration_ms(started_at, finished_at)
+        return 0.0 unless started_at && finished_at
+
+        ((finished_at.to_f - started_at.to_f) * 1000.0).round(3)
+      end
+
+      def query_free_path(path)
+        path.to_s.split("?", 2).first
+      end
+
+      def route(payload)
+        explicit = value(payload, :route)
+        return explicit.to_s unless explicit.to_s.empty?
+
+        [value(payload, :controller), value(payload, :action)].compact.join("#")
+      end
+
+      def safe_basename(identifier)
+        File.basename(identifier.to_s)
+      rescue StandardError
+        "<template>"
+      end
+
+      def safe_class_name(object)
+        object ? object.class.name.to_s : ""
+      rescue StandardError
+        "Object"
+      end
+
+      def safe_job_value(job, method_name)
+        job.respond_to?(method_name) ? job.public_send(method_name).to_s : ""
+      rescue StandardError
+        ""
+      end
+    end
+  end
+end

data/lib/chronos/rails/railtie.rb

@@ -0,0 +1,21 @@
+module Chronos
+  module Rails
+    # Hooks Chronos installation into the public Rails initializer lifecycle.
+    #
+    # @responsibility Install integrations after application configuration initializers load.
+    # @motivation Ensure generated Chronos configuration exists before hooks are activated.
+    # @limits It performs no autoloading and does not use private Rails initialization APIs.
+    # @collaborators Rails::Railtie and Chronos::Rails::Installer.
+    # @thread_safety Rails invokes the initializer during serialized application boot.
+    # @compatibility Rails 4.2 through Rails 5.2; no Zeitwerk requirement.
+    # @example
+    #   require "chronos/rails"
+    # @errors Installer contains optional integration failures and allows Rails to boot.
+    # @performance Adds only one initializer and one-time installation work.
+    class Railtie < ::Rails::Railtie
+      initializer "chronos.install", :after => :load_config_initializers do |application|
+        Chronos::Rails::Installer.new.install(application)
+      end
+    end
+  end
+end

data/lib/chronos/rails.rb

@@ -0,0 +1,16 @@
+require "chronos"
+require "chronos/rails/notifications_subscriber"
+require "chronos/rails/installer"
+
+require "chronos/rails/railtie" if defined?(::Rails::Railtie)
+
+module Chronos
+  # Legacy Rails integration loaded explicitly after Rails is available.
+  #
+  # @responsibility Namespace Railtie, installer, and notification subscribers.
+  # @motivation Keep Rails and ActiveSupport out of the framework-independent core.
+  # @limits Version 0.5 targets public APIs present in Rails 4.2 and 5.2.
+  # @thread_safety Installation and subscriptions are protected against duplication.
+  # @compatibility Rails 4.2 through Rails 5.2 with their supported legacy Rubies.
+  module Rails; end
+end

data/lib/chronos/version.rb

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

data/lib/chronos.rb

@@ -15,24 +15,32 @@ require "chronos/core/sensitive_value_filter"
 require "chronos/core/sanitizer"
 require "chronos/core/safe_serializer"
 require "chronos/core/payload_serializer"
+require "chronos/core/telemetry_event"
 require "chronos/ports/transport"
+require "chronos/ports/context_store"
 require "chronos/internal/safe_logger"
 require "chronos/internal/bounded_queue"
 require "chronos/internal/memory_backlog"
 require "chronos/internal/worker_pool"
 require "chronos/adapters/net_http_transport"
+require "chronos/adapters/thread_local_context_store"
+require "chronos/core/breadcrumb"
 require "chronos/application/retry_policy"
 require "chronos/application/circuit_breaker"
 require "chronos/application/remote_configuration"
 require "chronos/application/delivery_pipeline"
 require "chronos/application/capture_exception"
+require "chronos/application/capture_telemetry"
 require "chronos/agent"
+require "chronos/integrations"
+require "chronos/integrations/rack"
+require "chronos/integrations/rack/middleware"
 
 # Framework-independent public facade for the Chronos Ruby agent.
 #
 # @responsibility Configure the agent and expose its small lifecycle API.
 # @motivation Give applications a stable entry point while internals evolve.
-# @limits Version 0.3 captures Ruby exceptions manually; integrations arrive later.
+# @limits Rails integration remains optional and must be loaded through chronos/rails.
 # @collaborators Configuration and Agent.
 # @thread_safety Agent replacement and lookup are protected by a mutex.
 # @compatibility Ruby 2.2.10 through Ruby 2.6.
@@ -75,6 +83,41 @@ module Chronos
       false
     end
 
+    def with_context(context = {})
+      agent = current_agent
+      return yield unless agent
+
+      agent.with_context(context) { yield }
+    end
+
+    def add_breadcrumb(attributes = {})
+      agent = current_agent
+      agent ? agent.add_breadcrumb(attributes) : false
+    rescue StandardError
+      false
+    end
+
+    def record_event(event_type, payload = {}, context = {})
+      agent = current_agent
+      agent ? agent.record_event(event_type, payload, context) : false
+    rescue StandardError
+      false
+    end
+
+    def notify_once(exception, context = {})
+      agent = current_agent
+      agent ? agent.notify_once(exception, context) : 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}
+    rescue StandardError
+      {:enabled => false}
+    end
+
     def configured?
       !current_agent.nil?
     end
@@ -104,3 +147,5 @@ module Chronos
     end
   end
 end
+
+require "chronos/rails" if defined?(::Rails::Railtie)

data/lib/generators/chronos/install/install_generator.rb

@@ -0,0 +1,25 @@
+require "rails/generators"
+
+module Chronos
+  module Generators
+    # Generates the explicit Chronos initializer for legacy Rails applications.
+    #
+    # @responsibility Copy one documented initializer into config/initializers.
+    # @motivation Keep credentials explicit and avoid automatic environment scanning.
+    # @limits It does not modify routes, application classes, or Gemfiles.
+    # @collaborators Rails::Generators::Base file-copy API.
+    # @thread_safety Generator instances are used serially by the Rails command.
+    # @compatibility Rails generator APIs available in Rails 4.2 through Rails 5.2.
+    # @example
+    #   rails generate chronos:install
+    # @errors Existing-file conflict handling is delegated to Rails generators.
+    # @performance Copies one small text file.
+    class InstallGenerator < ::Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      def create_initializer
+        copy_file "chronos.rb", "config/initializers/chronos.rb"
+      end
+    end
+  end
+end

data/lib/generators/chronos/install/templates/chronos.rb

@@ -0,0 +1,20 @@
+require "chronos/rails"
+
+Chronos.configure do |config|
+  # Chronos reads only the environment variables explicitly selected here.
+  config.project_id = ENV["CHRONOS_PROJECT_ID"]
+  config.project_key = ENV["CHRONOS_PROJECT_KEY"]
+  config.host = ENV["CHRONOS_HOST"]
+  config.environment = Rails.env.to_s
+  config.service_name = ENV["CHRONOS_SERVICE_NAME"]
+  config.app_version = ENV["CHRONOS_APP_VERSION"]
+  config.logger = Rails.logger if Rails.respond_to?(:logger)
+
+  # Safe legacy defaults: test and console integrations remain disabled.
+  config.rails_capture_in_test = false
+  config.rails_capture_in_console = false
+  config.rails_capture_user_agent = false
+end
+
+# Safe when the Railtie already ran or will run later; installation is idempotent.
+Chronos::Rails::Installer.new.install(Rails.application)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: chronos-ruby
 version: !ruby/object:Gem::Version
-  version: 0.3.0.pre.1
+  version: 0.5.0.pre.1
 platform: ruby
 authors:
 - Antonio Jefferson
@@ -87,6 +87,7 @@ files:
 - README.md
 - SECURITY.md
 - contracts/event-v1.schema.json
+- contracts/rack-context-v1.schema.json
 - docs/adr/ADR-001-core-and-integrations.md
 - docs/adr/ADR-002-version-lines.md
 - docs/adr/ADR-003-net-http-legacy-transport.md
@@ -94,6 +95,8 @@ files:
 - docs/adr/ADR-005-sanitize-before-backlog.md
 - docs/adr/ADR-006-versioned-event-contract.md
 - docs/adr/ADR-011-bounded-resilience-and-remote-control.md
+- docs/adr/ADR-012-rack-context-isolation.md
+- docs/adr/ADR-013-legacy-rails-notifications.md
 - docs/architecture.md
 - docs/compatibility.md
 - docs/configuration.md
@@ -102,10 +105,13 @@ files:
 - docs/modules/async-queue.md
 - docs/modules/configuration.md
 - docs/modules/notice-pipeline.md
+- docs/modules/rack-context.md
+- docs/modules/rails-legacy.md
 - docs/modules/remote-configuration.md
 - docs/modules/retry-backlog.md
 - docs/modules/sanitization.md
 - docs/modules/serialization.md
+- docs/modules/telemetry-events.md
 - docs/modules/transport.md
 - docs/performance.md
 - docs/privacy-lgpd.md
@@ -113,16 +119,21 @@ files:
 - lib/chronos.rb
 - lib/chronos/adapters.rb
 - lib/chronos/adapters/net_http_transport.rb
+- lib/chronos/adapters/thread_local_context_store.rb
 - lib/chronos/agent.rb
 - lib/chronos/application.rb
 - lib/chronos/application/capture_exception.rb
+- lib/chronos/application/capture_telemetry.rb
 - lib/chronos/application/circuit_breaker.rb
 - lib/chronos/application/delivery_pipeline.rb
 - lib/chronos/application/remote_configuration.rb
 - lib/chronos/application/retry_policy.rb
 - lib/chronos/configuration.rb
+- lib/chronos/configuration/snapshot.rb
+- lib/chronos/configuration/validation.rb
 - lib/chronos/core.rb
 - lib/chronos/core/backtrace_parser.rb
+- lib/chronos/core/breadcrumb.rb
 - lib/chronos/core/exception_cause_collector.rb
 - lib/chronos/core/notice.rb
 - lib/chronos/core/notice_builder.rb
@@ -131,17 +142,28 @@ files:
 - lib/chronos/core/safe_serializer.rb
 - lib/chronos/core/sanitizer.rb
 - lib/chronos/core/sensitive_value_filter.rb
+- lib/chronos/core/telemetry_event.rb
 - lib/chronos/errors.rb
+- lib/chronos/integrations.rb
+- lib/chronos/integrations/rack.rb
+- lib/chronos/integrations/rack/middleware.rb
 - lib/chronos/internal.rb
 - lib/chronos/internal/bounded_queue.rb
 - lib/chronos/internal/memory_backlog.rb
 - lib/chronos/internal/safe_logger.rb
 - lib/chronos/internal/worker_pool.rb
 - lib/chronos/ports.rb
+- lib/chronos/ports/context_store.rb
 - lib/chronos/ports/transport.rb
+- lib/chronos/rails.rb
+- lib/chronos/rails/installer.rb
+- lib/chronos/rails/notifications_subscriber.rb
+- lib/chronos/rails/railtie.rb
 - lib/chronos/ruby.rb
 - lib/chronos/ruby/version.rb
 - lib/chronos/version.rb
+- lib/generators/chronos/install/install_generator.rb
+- lib/generators/chronos/install/templates/chronos.rb
 homepage: https://github.com/antoniojefferson/chronos-ruby
 licenses:
 - MIT