ez_logs_agent 0.1.0

data/lib/ez_logs_agent/railtie.rb

@@ -0,0 +1,353 @@
+# frozen_string_literal: true
+
+require "rails/railtie"
+
+module EzLogsAgent
+  # Rails Railtie for automatic zero-config runtime integration.
+  #
+  # This Railtie is the ONLY orchestrator in EzLogs Agent. It handles:
+  # - Starting/stopping the FlushScheduler
+  # - Auto-registering HTTP middleware
+  # - Auto-registering Sidekiq middleware (client + server)
+  # - Auto-installing ActiveJob capturer
+  # - Auto-installing Database capturer
+  #
+  # All integrations are:
+  # - Defensive (wrapped in begin/rescue, never crash host app)
+  # - Configuration-gated (respect capture_http, capture_jobs, capture_database)
+  # - Framework-aware (check defined?(Sidekiq), defined?(ActiveRecord), etc.)
+  # - Idempotent (safe to boot multiple times)
+  # - Explicitly logged (log what's enabled/skipped and why)
+  #
+  class Railtie < Rails::Railtie
+    # Track registration state for idempotency
+    @sidekiq_client_registered = false
+    @sidekiq_server_registered = false
+    @activejob_installed = false
+    @database_capturer_installed = false
+
+    class << self
+      attr_accessor :sidekiq_client_registered, :sidekiq_server_registered,
+                    :activejob_installed, :database_capturer_installed
+
+      # Reset registration state (for testing)
+      def reset_registration_state!
+        @sidekiq_client_registered = false
+        @sidekiq_server_registered = false
+        @activejob_installed = false
+        @database_capturer_installed = false
+      end
+    end
+
+    # =========================================================================
+    # HTTP Middleware Registration
+    # =========================================================================
+    #
+    # Registers HTTP request capture middleware into the Rails middleware stack.
+    # Runs during Rails initialization (before after_initialize).
+    #
+    initializer "ez_logs_agent.http_middleware" do |app|
+      begin
+        if EzLogsAgent.configuration.capture_http
+          app.middleware.use EzLogsAgent::Middleware::HttpRequest
+          EzLogsAgent::Logger.debug("[Railtie] HTTP capture enabled")
+        else
+          EzLogsAgent::Logger.debug("[Railtie] HTTP capture disabled (capture_http = false)")
+        end
+      rescue StandardError => e
+        EzLogsAgent::Logger.error("[Railtie] Failed to register HTTP middleware: #{e.class} - #{e.message}")
+      end
+    end
+
+    # =========================================================================
+    # After Initialize: Register Capturers + Setup FlushScheduler
+    # =========================================================================
+    #
+    # This hook runs after Rails has fully initialized. We:
+    # 1. Register Sidekiq middleware (if Sidekiq present + capture_jobs enabled)
+    # 2. Install ActiveJob capturer (if ActiveJob present + capture_jobs enabled)
+    # 3. Install Database capturer (if ActiveRecord present + capture_database enabled)
+    # 4. Start FlushScheduler (with special handling for forking servers like Puma)
+    #
+    # IMPORTANT: FlushScheduler uses a background thread. In forking servers
+    # (Puma cluster mode, Unicorn), threads don't survive fork(). We must:
+    # - Start FlushScheduler AFTER fork in each worker process
+    # - Use server-specific hooks (Puma on_worker_boot, etc.)
+    # - Fall back to starting here for non-forking servers (Puma single mode, WEBrick)
+    #
+    config.after_initialize do
+      # Validate configuration before doing anything
+      validation_result = validate_configuration
+      next unless validation_result
+
+      # Register Sidekiq middleware
+      register_sidekiq_middleware
+
+      # Install ActiveJob capturer
+      install_activejob_capturer
+
+      # Install Database capturer
+      install_database_capturer
+
+      # Setup FlushScheduler with fork-aware initialization
+      setup_flush_scheduler
+
+      log_configuration_summary
+      EzLogsAgent::Logger.debug("[Railtie] Agent initialized successfully")
+    end
+
+    # =========================================================================
+    # Shutdown Hook: Stop FlushScheduler
+    # =========================================================================
+    at_exit do
+      begin
+        EzLogsAgent::FlushScheduler.stop
+        EzLogsAgent::Logger.debug("[Railtie] Agent stopped")
+      rescue StandardError => e
+        EzLogsAgent::Logger.error("[Railtie] Failed to stop: #{e.class} - #{e.message}")
+      end
+    end
+
+    # =========================================================================
+    # Private Registration Methods
+    # =========================================================================
+
+    private
+
+    # Register Sidekiq client and server middleware
+    #
+    # @return [void]
+    def self.register_sidekiq_middleware
+      # Check if Sidekiq is present
+      unless defined?(Sidekiq)
+        EzLogsAgent::Logger.debug("[Railtie] Sidekiq not detected, skipping job capture middleware")
+        return
+      end
+
+      # Check if job capture is enabled
+      unless EzLogsAgent.configuration.capture_jobs
+        EzLogsAgent::Logger.debug("[Railtie] Job capture disabled (capture_jobs = false)")
+        return
+      end
+
+      # Register client middleware (correlation propagation)
+      register_sidekiq_client_middleware
+
+      # Register server middleware (job execution capture)
+      register_sidekiq_server_middleware
+    rescue StandardError => e
+      EzLogsAgent::Logger.error("[Railtie] Failed to register Sidekiq middleware: #{e.class} - #{e.message}")
+    end
+
+    # Register Sidekiq client middleware
+    #
+    # Client middleware runs in ALL processes (web, worker, console) and
+    # injects correlation_id into job payloads at enqueue-time.
+    #
+    # @return [void]
+    def self.register_sidekiq_client_middleware
+      return if @sidekiq_client_registered
+
+      Sidekiq.configure_client do |config|
+        config.client_middleware do |chain|
+          chain.add EzLogsAgent::Capturers::JobCapturer::ClientMiddleware
+        end
+      end
+
+      @sidekiq_client_registered = true
+      EzLogsAgent::Logger.debug("[Railtie] Sidekiq client middleware registered")
+    rescue StandardError => e
+      EzLogsAgent::Logger.error("[Railtie] Failed to register Sidekiq client middleware: #{e.class} - #{e.message}")
+    end
+
+    # Register Sidekiq server middleware
+    #
+    # Server middleware runs ONLY in Sidekiq worker processes and
+    # captures job execution as background_job events.
+    #
+    # @return [void]
+    def self.register_sidekiq_server_middleware
+      return if @sidekiq_server_registered
+
+      Sidekiq.configure_server do |config|
+        # Also register client middleware in server process (for job-enqueues-job scenarios)
+        config.client_middleware do |chain|
+          chain.add EzLogsAgent::Capturers::JobCapturer::ClientMiddleware
+        end
+
+        config.server_middleware do |chain|
+          chain.add EzLogsAgent::Capturers::JobCapturer::ServerMiddleware
+        end
+      end
+
+      @sidekiq_server_registered = true
+      EzLogsAgent::Logger.debug("[Railtie] Sidekiq server middleware registered")
+    rescue StandardError => e
+      EzLogsAgent::Logger.error("[Railtie] Failed to register Sidekiq server middleware: #{e.class} - #{e.message}")
+    end
+
+    # Install ActiveJob capturer
+    #
+    # ActiveJob capturer handles correlation propagation and job capture
+    # for non-Sidekiq adapters (async, inline, etc.).
+    #
+    # @return [void]
+    def self.install_activejob_capturer
+      # Check if ActiveJob is present
+      unless defined?(ActiveJob)
+        EzLogsAgent::Logger.debug("[Railtie] ActiveJob not detected, skipping ActiveJob capturer")
+        return
+      end
+
+      # Check if job capture is enabled
+      unless EzLogsAgent.configuration.capture_jobs
+        # Already logged in register_sidekiq_middleware if Sidekiq present
+        # Only log here if Sidekiq is NOT present
+        unless defined?(Sidekiq)
+          EzLogsAgent::Logger.debug("[Railtie] Job capture disabled (capture_jobs = false)")
+        end
+        return
+      end
+
+      return if @activejob_installed
+
+      EzLogsAgent::Capturers::ActiveJobCapturer.install
+      @activejob_installed = true
+      EzLogsAgent::Logger.debug("[Railtie] ActiveJob capturer installed")
+    rescue StandardError => e
+      EzLogsAgent::Logger.error("[Railtie] Failed to install ActiveJob capturer: #{e.class} - #{e.message}")
+    end
+
+    # Install Database capturer
+    #
+    # Database capturer installs ActiveRecord lifecycle callbacks
+    # (after_create, after_update, after_destroy) for all models.
+    #
+    # @return [void]
+    def self.install_database_capturer
+      # Check if ActiveRecord is present
+      unless defined?(ActiveRecord)
+        EzLogsAgent::Logger.debug("[Railtie] ActiveRecord not detected, skipping database capture")
+        return
+      end
+
+      # Check if database capture is enabled
+      unless EzLogsAgent.configuration.capture_database
+        EzLogsAgent::Logger.debug("[Railtie] Database capture disabled (capture_database = false)")
+        return
+      end
+
+      return if @database_capturer_installed
+
+      EzLogsAgent::Capturers::DatabaseCapturer.install
+      @database_capturer_installed = true
+      EzLogsAgent::Logger.debug("[Railtie] Database capture installed")
+    rescue StandardError => e
+      EzLogsAgent::Logger.error("[Railtie] Failed to install database capturer: #{e.class} - #{e.message}")
+    end
+
+    # Setup FlushScheduler with fork-aware initialization
+    #
+    # Background threads don't survive fork(). In forking servers like Puma
+    # cluster mode or Unicorn, we must start FlushScheduler AFTER the fork
+    # in each worker process.
+    #
+    # Strategy:
+    # 1. Always register ActiveSupport::ForkTracker hook (handles all forking cases)
+    # 2. Also start immediately (for non-forking servers or single-process mode)
+    # 3. FlushScheduler.start is idempotent, so calling it multiple times is safe
+    #
+    # @return [void]
+    def self.setup_flush_scheduler
+      # Register fork hook for Puma cluster mode, Unicorn, etc.
+      # ActiveSupport::ForkTracker (Rails 6.1+) is the most reliable way
+      if defined?(ActiveSupport::ForkTracker)
+        ActiveSupport::ForkTracker.after_fork do
+          start_flush_scheduler
+        end
+        EzLogsAgent::Logger.debug("[Railtie] Registered ActiveSupport::ForkTracker hook for FlushScheduler")
+      end
+
+      # Always start FlushScheduler now (for non-forking servers or master process)
+      # In forking servers, this runs in master (will be killed on fork)
+      # then ForkTracker restarts it in each worker
+      start_flush_scheduler
+    rescue StandardError => e
+      EzLogsAgent::Logger.error("[Railtie] Failed to setup FlushScheduler: #{e.class} - #{e.message}")
+    end
+
+    # Start the FlushScheduler
+    #
+    # @return [void]
+    def self.start_flush_scheduler
+      EzLogsAgent::FlushScheduler.start
+      EzLogsAgent::Logger.debug("[Railtie] FlushScheduler started (PID: #{Process.pid})")
+    rescue StandardError => e
+      EzLogsAgent::Logger.error("[Railtie] Failed to start FlushScheduler: #{e.class} - #{e.message}")
+    end
+
+    # Validate configuration at boot time
+    #
+    # Logs errors and warnings from configuration validation.
+    # If configuration is invalid, logs errors and returns false to skip initialization.
+    # If configuration has warnings, logs them but continues.
+    #
+    # @return [Boolean] true if valid or has only warnings, false if invalid
+    def self.validate_configuration
+      result = EzLogsAgent::ConfigurationValidator.validate(EzLogsAgent.configuration)
+
+      # Log errors
+      if result.errors.any?
+        EzLogsAgent::Logger.error("[Railtie] Configuration validation failed:")
+        result.errors.each do |error|
+          EzLogsAgent::Logger.error("[Railtie]   - #{error}")
+        end
+        EzLogsAgent::Logger.error("[Railtie] Agent initialization skipped. Please fix configuration errors.")
+        return false
+      end
+
+      # Log warnings
+      if result.warnings.any?
+        result.warnings.each do |warning|
+          EzLogsAgent::Logger.warn("[Railtie]   ⚠ #{warning}")
+        end
+      end
+
+      true
+    rescue StandardError => e
+      EzLogsAgent::Logger.error("[Railtie] Failed to validate configuration: #{e.class} - #{e.message}")
+      false
+    end
+
+    # Log configuration summary at boot time
+    #
+    # Shows what's enabled/disabled to help with debugging and visibility.
+    #
+    # @return [void]
+    def self.log_configuration_summary
+      config = EzLogsAgent.configuration
+
+      EzLogsAgent::Logger.info("[Railtie] Configuration:")
+      EzLogsAgent::Logger.info("[Railtie]   Server: #{config.server_url}")
+      EzLogsAgent::Logger.info("[Railtie]   Capture HTTP: #{config.capture_http}")
+      EzLogsAgent::Logger.info("[Railtie]   Capture Jobs: #{config.capture_jobs}")
+      EzLogsAgent::Logger.info("[Railtie]   Capture Database: #{config.capture_database}")
+
+      # Show optional configuration if present
+      if config.actor_from_request
+        EzLogsAgent::Logger.info("[Railtie]   Actor Extraction: enabled")
+      end
+
+      if config.display_name_for && config.display_name_for.any?
+        EzLogsAgent::Logger.info("[Railtie]   Display Names: configured for #{config.display_name_for.keys.join(', ')}")
+      end
+    rescue StandardError => e
+      EzLogsAgent::Logger.error("[Railtie] Failed to log configuration summary: #{e.class} - #{e.message}")
+    end
+
+    # Load rake tasks
+    rake_tasks do
+      load "tasks/ez_logs_agent.rake"
+    end
+  end
+end

data/lib/ez_logs_agent/resource_extractor.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+module EzLogsAgent
+  # ResourceExtractor provides explicit, opt-in helpers for extracting resource_ids from objects.
+  #
+  # This module is a small, boring utility that:
+  # - Converts ActiveRecord model instances to resource_id hashes
+  # - Extracts resource_ids from arrays of models
+  # - Passes through existing resource_ids from hashes
+  # - Returns empty array for unsupported inputs (defensive)
+  #
+  # ResourceExtractor does NOT:
+  # - Automatically hook into anything
+  # - Infer resources from SQL or context
+  # - Guess actor or ownership
+  # - Read RequestStore or global state
+  # - Modify EventBuilder or other components
+  # - Raise exceptions for unsupported input
+  #
+  # Missing resource_ids is acceptable.
+  # Wrong or guessed resource_ids is NOT acceptable.
+  #
+  # @example Extract from ActiveRecord model
+  #   user = User.find(123)
+  #   EzLogsAgent::ResourceExtractor.from_record(user)
+  #   # => [{ resource_type: "user_id", resource_id: "123" }]
+  #
+  # @example Extract from array of models
+  #   orders = [Order.find(1), Order.find(2)]
+  #   EzLogsAgent::ResourceExtractor.from_records(orders)
+  #   # => [
+  #   #   { resource_type: "order_id", resource_id: "1" },
+  #   #   { resource_type: "order_id", resource_id: "2" }
+  #   # ]
+  #
+  # @example Extract from hash
+  #   hash = { resource_ids: [{ resource_type: "product_id", resource_id: "456" }] }
+  #   EzLogsAgent::ResourceExtractor.from_hash(hash)
+  #   # => [{ resource_type: "product_id", resource_id: "456" }]
+  #
+  # @example Unsupported input returns empty array
+  #   EzLogsAgent::ResourceExtractor.from_record("not a model")
+  #   # => []
+  #
+  module ResourceExtractor
+    # Extracts resource_id from a single ActiveRecord model instance
+    #
+    # @param record [Object] Potentially an ActiveRecord model instance
+    # @return [Array<Hash>] Array containing single resource_id hash, or empty array
+    #
+    # @example Valid ActiveRecord model
+    #   user = User.find(123)
+    #   ResourceExtractor.from_record(user)
+    #   # => [{ resource_type: "user_id", resource_id: "123" }]
+    #
+    # @example Unsupported input
+    #   ResourceExtractor.from_record("not a model")
+    #   # => []
+    #
+    # @example Nil input
+    #   ResourceExtractor.from_record(nil)
+    #   # => []
+    #
+    def self.from_record(record)
+      return [] if record.nil?
+      return [] unless active_record_model?(record)
+
+      [{
+        resource_type: resource_type_from_class(record.class),
+        resource_id: record.id.to_s
+      }]
+    rescue => e
+      # Defensive: never raise exceptions, return empty array
+      []
+    end
+
+    # Extracts resource_ids from an array of ActiveRecord model instances
+    #
+    # @param records [Array] Array of potentially ActiveRecord model instances
+    # @return [Array<Hash>] Array of resource_id hashes, or empty array
+    #
+    # @example Valid ActiveRecord models
+    #   orders = [Order.find(1), Order.find(2)]
+    #   ResourceExtractor.from_records(orders)
+    #   # => [
+    #   #   { resource_type: "order_id", resource_id: "1" },
+    #   #   { resource_type: "order_id", resource_id: "2" }
+    #   # ]
+    #
+    # @example Mixed array (filters invalid entries)
+    #   ResourceExtractor.from_records([user, "not a model", nil])
+    #   # => [{ resource_type: "user_id", resource_id: "123" }]
+    #
+    # @example Empty array
+    #   ResourceExtractor.from_records([])
+    #   # => []
+    #
+    def self.from_records(records)
+      return [] unless records.is_a?(Array)
+
+      records.flat_map { |record| from_record(record) }.compact
+    rescue => e
+      # Defensive: never raise exceptions, return empty array
+      []
+    end
+
+    # Extracts resource_ids from a hash containing a :resource_ids key
+    #
+    # @param hash [Hash] Hash potentially containing :resource_ids key
+    # @return [Array<Hash>] Array of resource_id hashes, or empty array
+    #
+    # @example Valid hash with resource_ids
+    #   hash = { resource_ids: [{ resource_type: "product_id", resource_id: "456" }] }
+    #   ResourceExtractor.from_hash(hash)
+    #   # => [{ resource_type: "product_id", resource_id: "456" }]
+    #
+    # @example Hash without resource_ids key
+    #   ResourceExtractor.from_hash({ foo: "bar" })
+    #   # => []
+    #
+    # @example Non-hash input
+    #   ResourceExtractor.from_hash("not a hash")
+    #   # => []
+    #
+    def self.from_hash(hash)
+      return [] unless hash.is_a?(Hash)
+      return [] unless hash.key?(:resource_ids)
+
+      resource_ids = hash[:resource_ids]
+      return [] unless resource_ids.is_a?(Array)
+
+      resource_ids
+    rescue => e
+      # Defensive: never raise exceptions, return empty array
+      []
+    end
+
+    # Checks if an object is an ActiveRecord model instance
+    #
+    # @param object [Object] Object to check
+    # @return [Boolean] True if object is an ActiveRecord::Base instance
+    # @private
+    def self.active_record_model?(object)
+      defined?(ActiveRecord::Base) && object.is_a?(ActiveRecord::Base)
+    end
+    private_class_method :active_record_model?
+
+    # Converts a class to a resource_type string
+    #
+    # @param klass [Class] ActiveRecord model class
+    # @return [String] Snake-cased class name with "_id" suffix
+    #
+    # @example
+    #   resource_type_from_class(User) # => "user_id"
+    #   resource_type_from_class(OrderItem) # => "order_item_id"
+    #
+    # @private
+    def self.resource_type_from_class(klass)
+      # Convert class name to snake_case and append "_id"
+      class_name = klass.name
+      snake_case = class_name
+        .gsub(/::/, "/")
+        .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+        .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+        .tr("-", "_")
+        .downcase
+
+      "#{snake_case}_id"
+    end
+    private_class_method :resource_type_from_class
+  end
+end

data/lib/ez_logs_agent/retry_sender.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module EzLogsAgent
+  # Retry logic with exponential backoff
+  #
+  # Wraps Transport.send(events) with automatic retry logic.
+  # Implements exponential backoff with a maximum delay cap.
+  #
+  # Responsibilities:
+  # - Decides IF and WHEN to retry
+  # - Sleeps between retries using exponential backoff
+  # - Stops after max attempts
+  # - Never crashes the host application
+  #
+  # Does NOT:
+  # - Modify events
+  # - Inspect HTTP status codes
+  # - Interpret errors
+  # - Spawn threads
+  # - Read from or flush Buffer
+  class RetrySender
+    # Maximum sleep duration between retries (hard cap)
+    MAX_SLEEP_SECONDS = 5
+
+    # Base delay for exponential backoff calculation
+    BASE_DELAY_SECONDS = 0.5
+
+    class << self
+      # Send events with retry logic
+      #
+      # @param events [Array<Hash>] Array of event hashes
+      # @return [Symbol] :success if sent successfully, :failure otherwise
+      def send(events)
+        # Empty events is a success (no work to do)
+        return :success if events.nil? || events.empty?
+
+        max_attempts = retry_attempts + 1 # Initial attempt + retries
+        attempt = 1
+
+        while attempt <= max_attempts
+          result = attempt_send(events, attempt, max_attempts)
+          return :success if result == :success
+
+          # If this was the last attempt, return failure
+          break if attempt >= max_attempts
+
+          # Sleep before next retry
+          sleep_before_retry(attempt)
+          attempt += 1
+        end
+
+        # All attempts exhausted
+        log_final_failure(events.size)
+        :failure
+      rescue => error
+        # Defensive: if anything unexpected happens, log and return failure
+        log_error("[RetrySender] send failed with exception: #{error.class} - #{error.message}")
+        :failure
+      end
+
+      private
+
+      # Attempt to send events once
+      def attempt_send(events, attempt, max_attempts)
+        Transport.send(events)
+      rescue => error
+        # Transport shouldn't raise, but be defensive
+        log_error("[RetrySender] Transport raised exception (attempt #{attempt}/#{max_attempts}): #{error.message}")
+        :failure
+      end
+
+      # Sleep with exponential backoff before next retry
+      def sleep_before_retry(attempt)
+        # Formula: base_delay * (2 ** (attempt - 1))
+        # attempt=1: 0.5s, attempt=2: 1.0s, attempt=3: 2.0s, attempt=4: 4.0s, attempt=5: 8.0s
+        delay = BASE_DELAY_SECONDS * (2**(attempt - 1))
+
+        # Cap at MAX_SLEEP_SECONDS
+        delay = [delay, MAX_SLEEP_SECONDS].min
+
+        sleep(delay)
+      rescue => error
+        # Defensive: if sleep fails somehow, continue anyway
+        log_error("[RetrySender] sleep failed: #{error.message}")
+      end
+
+      # Get configured retry attempts, with fallback
+      def retry_attempts
+        attempts = EzLogsAgent.configuration.retry_attempts
+
+        # Validate and fallback to 3 if invalid
+        return 3 if attempts.nil?
+        return 3 if !attempts.is_a?(Integer)
+        return 3 if attempts < 0
+
+        attempts
+      rescue => error
+        # Defensive: if configuration fails, use default
+        log_error("[RetrySender] Failed to read retry_attempts configuration: #{error.message}")
+        3
+      end
+
+      # Log final failure after all retries exhausted
+      def log_final_failure(event_count)
+        Logger.error("[RetrySender] Failed after #{retry_attempts + 1} attempts, dropping #{event_count} events")
+      rescue => error
+        # Defensive: logging must never crash
+        nil
+      end
+
+      # Log error message
+      def log_error(message)
+        Logger.error(message)
+      rescue => error
+        # Defensive: logging must never crash
+        nil
+      end
+    end
+  end
+end