ez_logs_agent 0.1.0

data/RELEASING.md

@@ -0,0 +1,55 @@
+# Release Checklist
+
+Steps to release a new version of `ez_logs_agent`.
+
+---
+
+## Pre-Release
+
+- [ ] All tests passing: `bundle exec rspec`
+- [ ] Code style clean: `bundle exec rubocop` (if configured)
+- [ ] README.md reviewed and accurate
+- [ ] CHANGELOG.md updated with new version
+- [ ] Version bumped in `lib/ez_logs_agent/version.rb`
+- [ ] Gemspec metadata reviewed (summary, description, homepage)
+- [ ] No uncommitted changes: `git status`
+
+---
+
+## Release
+
+```bash
+# Build the gem
+gem build ez_logs_agent.gemspec
+
+# Verify the gem contents
+gem specification ez_logs_agent-X.Y.Z.gem
+
+# Push to RubyGems (requires authentication)
+gem push ez_logs_agent-X.Y.Z.gem
+
+# Tag the release
+git tag vX.Y.Z
+git push origin vX.Y.Z
+```
+
+---
+
+## Post-Release
+
+- [ ] Verify gem is available: `gem info ez_logs_agent -r`
+- [ ] Create GitHub release with changelog notes
+- [ ] Monitor for issues or bug reports
+- [ ] Update CURRENT_STATE.md if needed
+
+---
+
+## Version Numbering
+
+This project follows [Semantic Versioning](https://semver.org/):
+
+- **MAJOR** (X.0.0): Breaking changes to public API
+- **MINOR** (0.X.0): New features, backwards compatible
+- **PATCH** (0.0.X): Bug fixes, backwards compatible
+
+Pre-1.0: API is not yet stable. Minor version bumps may include breaking changes.

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/lib/ez_logs_agent/actor.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "request_store"
+
+module EzLogsAgent
+  # Manages actor context for the current request.
+  #
+  # Actor represents "who triggered this action" - the logged-in user.
+  #
+  # Actor schema:
+  # {
+  #   id: String,         # REQUIRED - stable identifier (e.g., user.id)
+  #   label: String       # optional - human-readable display (e.g., user.email)
+  # }
+  #
+  # Usage:
+  #   # Configured via actor_from_request hook in EzLogsAgent.configure
+  module Actor
+    class << self
+      # Get the current actor for this request
+      # @return [Hash, nil] Current actor or nil if not set
+      def current
+        RequestStore.store[:ez_logs_actor]
+      rescue => e
+        EzLogsAgent::Logger.debug("[Actor] current failed: #{e.message}")
+        nil
+      end
+
+      # Set the current actor for this request
+      # Validates and sanitizes the actor before storing
+      # @param actor [Hash, nil] Actor to set
+      # @return [Hash, nil] The sanitized actor that was stored
+      def current=(actor)
+        validated = ActorValidator.sanitize(actor)
+
+        # Log debug message if actor was invalid (user hook misconfiguration)
+        if actor && validated.nil?
+          EzLogsAgent::Logger.debug("[Actor] Invalid actor structure ignored: #{actor.inspect}")
+        end
+
+        RequestStore.store[:ez_logs_actor] = validated
+        validated
+      rescue => e
+        EzLogsAgent::Logger.debug("[Actor] current= failed: #{e.message}")
+        nil
+      end
+
+      # Clear the current actor
+      # @return [void]
+      def clear
+        RequestStore.store[:ez_logs_actor] = nil
+      rescue => e
+        EzLogsAgent::Logger.debug("[Actor] clear failed: #{e.message}")
+      end
+    end
+  end
+end

data/lib/ez_logs_agent/actor_validator.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module EzLogsAgent
+  # Validates and sanitizes actor data structures.
+  #
+  # Actor schema:
+  # {
+  #   id: String,               # REQUIRED, stable identifier
+  #   label: String | nil       # optional, human-readable display
+  # }
+  #
+  # This module ensures actors conform to the expected structure
+  # before being stored in event context.
+  module ActorValidator
+    class << self
+      # Check if an actor structure is valid
+      # @param actor [Hash, nil] Actor hash to validate
+      # @return [Boolean] true if valid (including nil), false otherwise
+      def valid?(actor)
+        # nil actor is valid (means "unknown provenance")
+        return true if actor.nil?
+
+        # Must be a Hash
+        return false unless actor.is_a?(Hash)
+
+        # id is required
+        id = actor[:id] || actor["id"]
+        return false if id.nil? || id.to_s.empty?
+
+        true
+      end
+
+      # Sanitize actor structure to ensure consistent format
+      # Returns nil for invalid actors
+      # @param actor [Hash, nil] Actor hash to sanitize
+      # @return [Hash, nil] Sanitized actor or nil
+      def sanitize(actor)
+        return nil unless valid?(actor)
+        return nil if actor.nil?
+
+        id = actor[:id] || actor["id"]
+        label = actor[:label] || actor["label"]
+
+        result = { id: id.to_s }
+        result[:label] = label.to_s if label
+
+        result
+      end
+    end
+  end
+end

data/lib/ez_logs_agent/buffer.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require 'monitor'
+
+module EzLogsAgent
+  # Thread-safe in-memory event buffer.
+  # Stores events until flushed. Drops oldest when full.
+  # Never raises exceptions to host application.
+  class Buffer
+    @queue = []
+    @monitor = Monitor.new
+
+    class << self
+      # Add event to buffer. Drops oldest if full.
+      # @param event [Hash] Event hash from EventBuilder
+      # @return [void]
+      def push(event)
+        @monitor.synchronize do
+          if @queue.size >= max_size
+            @queue.shift
+            log_warn("[Buffer] Buffer full (#{max_size}), dropped oldest event")
+          end
+
+          @queue.push(event)
+        end
+      rescue => error
+        log_error("[Buffer] push failed: #{error.message}")
+        # Fail open: discard event, never crash host
+      end
+
+      # Flush all buffered events and clear buffer atomically.
+      # @return [Array<Hash>] Array of events (empty if buffer was empty)
+      def flush
+        @monitor.synchronize do
+          events = @queue.dup
+          @queue.clear
+          events
+        end
+      rescue => error
+        log_error("[Buffer] flush failed: #{error.message}")
+        []
+      end
+
+      # Current number of buffered events.
+      # @return [Integer]
+      def size
+        @monitor.synchronize { @queue.size }
+      rescue => error
+        log_error("[Buffer] size failed: #{error.message}")
+        0
+      end
+
+      # Clear all buffered events.
+      # @return [void]
+      def clear
+        @monitor.synchronize { @queue.clear }
+      rescue => error
+        log_error("[Buffer] clear failed: #{error.message}")
+        # Best effort, ignore failures
+      end
+
+      private
+
+      def max_size
+        EzLogsAgent.configuration.buffer_size
+      rescue
+        100 # Defensive fallback if configuration unavailable
+      end
+
+      def log_warn(message)
+        EzLogsAgent::Logger.warn(message) if defined?(EzLogsAgent::Logger)
+      rescue
+        # Logging must never crash the buffer
+      end
+
+      def log_error(message)
+        EzLogsAgent::Logger.error(message) if defined?(EzLogsAgent::Logger)
+      rescue
+        # Logging must never crash the buffer
+      end
+    end
+  end
+end

data/lib/ez_logs_agent/capturers/active_job_capturer.rb

@@ -0,0 +1,270 @@
+# frozen_string_literal: true
+
+module EzLogsAgent
+  module Capturers
+    # ActiveJob hooks for correlation propagation and job execution capture.
+    #
+    # This capturer provides first-class ActiveJob support with two responsibilities:
+    #
+    # 1. **Enqueue-Time (Correlation Propagation)**:
+    #    - Uses `before_enqueue` callback to inject correlation_id into job
+    #    - Preserves causal chain: HTTP → Job → Job
+    #
+    # 2. **Execution-Time (Job Capture)**:
+    #    - Uses `around_perform` callback to capture job execution as background_job events
+    #    - Restores correlation_id from job
+    #    - Measures duration and captures success/failure outcome
+    #
+    # == Serialization Support
+    #
+    # ActiveJob's metadata hash is NOT automatically serialized. This capturer
+    # overrides `serialize` and `deserialize` to persist the correlation_id
+    # across job serialization (required for Async adapter and other adapters
+    # that serialize jobs).
+    #
+    # == Sidekiq Adapter Detection
+    #
+    # If the job's queue adapter is Sidekiq, this capturer:
+    # - STILL propagates correlation at enqueue-time
+    # - SKIPS execution capture (defers to Sidekiq server middleware)
+    #
+    # This prevents double events when Sidekiq is the adapter.
+    #
+    # == Installation
+    #
+    # This capturer is automatically installed by Railtie when ActiveJob
+    # is detected and `capture_jobs = true`.
+    #
+    # For manual installation (if not using Rails):
+    #
+    #   EzLogsAgent::Capturers::ActiveJobCapturer.install
+    #
+    class ActiveJobCapturer
+      @serialization_installed = false
+
+      class << self
+        # Installs ActiveJob hooks for correlation propagation and job capture.
+        #
+        # This method is idempotent and can be called multiple times safely.
+        #
+        # @return [void]
+        def install
+          return unless defined?(ActiveJob)
+
+          install_serialization_hooks unless @serialization_installed
+
+          ActiveJob::Base.before_enqueue do |job|
+            ActiveJobCapturer.propagate_correlation(job)
+          end
+
+          ActiveJob::Base.around_perform do |job, block|
+            ActiveJobCapturer.capture_execution(job, block)
+          end
+
+          EzLogsAgent::Logger.debug("[ActiveJobCapturer] Hooks installed")
+        rescue StandardError => e
+          EzLogsAgent::Logger.error("[ActiveJobCapturer] Installation failed: #{e.class} - #{e.message}")
+        end
+
+        # Propagates correlation_id from current context into job.
+        #
+        # Runs at enqueue-time (when job is scheduled).
+        # Stores correlation in `ezlogs_correlation_id` attribute which
+        # survives serialization/deserialization.
+        #
+        # @param job [ActiveJob::Base] The job being enqueued
+        # @return [void]
+        def propagate_correlation(job)
+          correlation_id = EzLogsAgent::Correlation.current
+          return unless correlation_id && !correlation_id.empty?
+
+          job.ezlogs_correlation_id = correlation_id
+        rescue StandardError => e
+          EzLogsAgent::Logger.error("[ActiveJobCapturer] Correlation propagation failed: #{e.class} - #{e.message}")
+        end
+
+        # Captures job execution as a background_job event.
+        #
+        # Runs at execution-time (when job executes).
+        # Skips capture if job uses Sidekiq adapter (prevents double events).
+        #
+        # IMPORTANT: When jobs run inline (Async adapter, perform_now, test adapter),
+        # they execute in the same thread as the caller (HTTP request or parent job).
+        # We must save and restore the previous correlation to avoid clearing the
+        # outer context's correlation. This applies to:
+        # - Development with Async adapter
+        # - Production with perform_now calls
+        # - Test environments
+        # - Any synchronous job execution
+        #
+        # @param job [ActiveJob::Base] The job being executed
+        # @param block [Proc] The job execution block
+        # @return [Object] The result of the job execution
+        def capture_execution(job, block)
+          return block.call unless EzLogsAgent.configuration.capture_jobs
+
+          if sidekiq_adapter?(job)
+            EzLogsAgent::Logger.debug("[ActiveJobCapturer] Skipping capture (Sidekiq adapter)")
+            return block.call
+          end
+
+          if excluded_job_class?(job)
+            EzLogsAgent::Logger.debug("[ActiveJobCapturer] Skipping capture (excluded job class: #{job.class.name})")
+            return block.call
+          end
+
+          # Save the previous correlation (from HTTP middleware or parent job)
+          # so we can restore it after the job completes
+          previous_correlation = EzLogsAgent::Correlation.current
+
+          # Use job's propagated correlation, fall back to current context, or generate new
+          correlation_id = extract_correlation(job) || previous_correlation || EzLogsAgent::Correlation.generate
+          EzLogsAgent::Correlation.current = correlation_id
+
+          start_time = Time.now
+          result = block.call
+          duration_ms = ((Time.now - start_time) * 1000).to_i
+
+          capture_success(job, correlation_id, duration_ms, start_time)
+          result
+        rescue StandardError => error
+          capture_failure(job, correlation_id, error, start_time)
+          raise
+        ensure
+          # Restore previous correlation instead of unconditionally clearing.
+          # This is critical for inline jobs that run in the same thread as the caller.
+          if previous_correlation
+            EzLogsAgent::Correlation.current = previous_correlation
+          else
+            EzLogsAgent::Correlation.clear
+          end
+        end
+
+        private
+
+        # Installs serialization hooks on ActiveJob::Base to persist correlation_id
+        # across job serialization/deserialization.
+        #
+        # This is required because ActiveJob's metadata hash is NOT automatically
+        # serialized. We override `serialize` and `deserialize` to include our
+        # correlation_id in the job data.
+        #
+        # @return [void]
+        def install_serialization_hooks
+          return if @serialization_installed
+
+          ActiveJob::Base.class_eval do
+            attr_accessor :ezlogs_correlation_id
+          end
+
+          ActiveJob::Base.prepend(Module.new do
+            def serialize
+              super.merge("ezlogs_correlation_id" => @ezlogs_correlation_id)
+            end
+
+            def deserialize(job_data)
+              super
+              @ezlogs_correlation_id = job_data["ezlogs_correlation_id"]
+            end
+          end)
+
+          @serialization_installed = true
+          EzLogsAgent::Logger.debug("[ActiveJobCapturer] Serialization hooks installed")
+        rescue StandardError => e
+          EzLogsAgent::Logger.error("[ActiveJobCapturer] Failed to install serialization hooks: #{e.class} - #{e.message}")
+        end
+
+        # Checks if job uses Sidekiq adapter.
+        #
+        # @param job [ActiveJob::Base] The job instance
+        # @return [Boolean] true if Sidekiq adapter, false otherwise
+        def sidekiq_adapter?(job)
+          return false unless defined?(ActiveJob::QueueAdapters::SidekiqAdapter)
+
+          job.class.queue_adapter.is_a?(ActiveJob::QueueAdapters::SidekiqAdapter)
+        rescue StandardError
+          false
+        end
+
+        # Checks if job class is in the excluded list.
+        #
+        # @param job [ActiveJob::Base] The job instance
+        # @return [Boolean] true if excluded, false otherwise
+        def excluded_job_class?(job)
+          job_class_name = job.class.name
+          EzLogsAgent.configuration.all_excluded_job_classes.include?(job_class_name)
+        rescue StandardError
+          false
+        end
+
+        # Extracts correlation_id from job.
+        #
+        # @param job [ActiveJob::Base] The job instance
+        # @return [String, nil] The correlation_id if present
+        def extract_correlation(job)
+          return nil unless job.respond_to?(:ezlogs_correlation_id)
+
+          correlation = job.ezlogs_correlation_id
+          correlation if correlation && !correlation.empty?
+        rescue StandardError
+          nil
+        end
+
+        # Captures successful job execution.
+        #
+        # @param job [ActiveJob::Base] The job instance
+        # @param correlation_id [String] The correlation ID
+        # @param duration_ms [Integer] Job execution duration in milliseconds
+        # @param start_time [Time] Job start time
+        # @return [void]
+        def capture_success(job, correlation_id, duration_ms, start_time)
+          event = EzLogsAgent::EventBuilder.build(
+            source_type: :background_job,
+            source_data: extract_job_data(job),
+            outcome: :success,
+            correlation_id: correlation_id,
+            duration_ms: duration_ms,
+            timestamp: start_time
+          )
+
+          EzLogsAgent::Buffer.push(event)
+        rescue StandardError => e
+          EzLogsAgent::Logger.error("[ActiveJobCapturer] Failed to capture success event: #{e.class} - #{e.message}")
+        end
+
+        # Captures failed job execution.
+        #
+        # @param job [ActiveJob::Base] The job instance
+        # @param correlation_id [String] The correlation ID
+        # @param error [StandardError] The error that caused the failure
+        # @param start_time [Time] Job start time
+        # @return [void]
+        def capture_failure(job, correlation_id, error, start_time)
+          event = EzLogsAgent::EventBuilder.build(
+            source_type: :background_job,
+            source_data: extract_job_data(job),
+            outcome: :failure,
+            correlation_id: correlation_id,
+            error_message: "#{error.class}: #{error.message}",
+            timestamp: start_time
+          )
+
+          EzLogsAgent::Buffer.push(event)
+        rescue StandardError => e
+          EzLogsAgent::Logger.error("[ActiveJobCapturer] Failed to capture failure event: #{e.class} - #{e.message}")
+        end
+
+        # Extracts relevant job data for event source_data.
+        #
+        # @param job [ActiveJob::Base] The job instance
+        # @return [Hash] Job metadata for source_data
+        def extract_job_data(job)
+          {
+            job_class: job.class.name,
+            queue: job.queue_name
+          }.compact
+        end
+      end
+    end
+  end
+end