fractor 0.1.6 → 0.1.7

data/lib/fractor/error_statistics.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+module Fractor
+  # Error statistics for a specific category or job.
+  # Tracks error counts, severity distribution, and trends over time.
+  class ErrorStatistics
+    attr_reader :category, :total_count, :by_severity, :by_code, :recent_errors
+
+    def initialize(category)
+      @category = category
+      @total_count = 0
+      @by_severity = Hash.new(0)
+      @by_code = Hash.new(0)
+      @recent_errors = []
+      @first_seen = nil
+      @last_seen = nil
+      @mutex = Mutex.new
+    end
+
+    # Record an error from a work result
+    #
+    # @param work_result [WorkResult] The failed work result
+    # @return [void]
+    def record(work_result)
+      @mutex.synchronize do
+        @total_count += 1
+        @by_severity[work_result.error_severity] += 1
+        @by_code[work_result.error_code] += 1 if work_result.error_code
+
+        # Handle both String and Exception error types
+        error_obj = work_result.error
+        error_message = if error_obj.is_a?(Exception)
+                          error_obj.message
+                        elsif error_obj.is_a?(String)
+                          error_obj
+                        else
+                          error_obj&.to_s
+                        end
+
+        error_entry = {
+          timestamp: Time.now,
+          error_class: error_obj.is_a?(Exception) ? error_obj.class.name : nil,
+          error_message: error_message,
+          error_code: work_result.error_code,
+          error_severity: work_result.error_severity,
+          error_context: work_result.error_context,
+        }
+
+        @recent_errors << error_entry
+        @recent_errors.shift if @recent_errors.size > 100
+
+        @first_seen ||= Time.now
+        @last_seen = Time.now
+      end
+    end
+
+    # Get error rate (errors per second)
+    #
+    # @return [Float] Errors per second
+    def error_rate
+      return 0.0 unless @first_seen && @last_seen
+
+      duration = @last_seen - @first_seen
+      return 0.0 if duration <= 0
+
+      @total_count / duration
+    end
+
+    # Get most common error code
+    #
+    # @return [String, nil] Most common error code
+    def most_common_code
+      return nil if @by_code.empty?
+
+      @by_code.max_by { |_code, count| count }&.first
+    end
+
+    # Get most severe error level
+    #
+    # @return [String, nil] Highest severity level
+    def highest_severity
+      return nil if @by_severity.empty?
+
+      severities = [
+        WorkResult::SEVERITY_CRITICAL,
+        WorkResult::SEVERITY_ERROR,
+        WorkResult::SEVERITY_WARNING,
+        WorkResult::SEVERITY_INFO,
+      ]
+
+      severities.find { |severity| @by_severity[severity].positive? }
+    end
+
+    # Check if error rate is increasing
+    #
+    # @return [Boolean] True if errors are trending upward
+    def increasing?
+      return false if @recent_errors.size < 10
+
+      recent_10 = @recent_errors.last(10)
+
+      # Check if errors are happening in a short time span (rapid burst)
+      first_timestamp = recent_10.first[:timestamp]
+      last_timestamp = recent_10.last[:timestamp]
+      total_timespan = last_timestamp - first_timestamp
+
+      # If all errors happened in a very short time (burst), consider it increasing
+      return true if total_timespan < 1.0 # Less than 1 second for 10 errors
+
+      # Otherwise, check if the rate is increasing by comparing first half vs second half
+      first_5 = recent_10.first(5)
+      last_5 = recent_10.last(5)
+
+      first_5_timespan = first_5.last[:timestamp] - first_5.first[:timestamp]
+      last_5_timespan = last_5.last[:timestamp] - last_5.first[:timestamp]
+
+      # Avoid division by zero - use small epsilon if timespan is very small
+      first_5_timespan = 0.001 if first_5_timespan <= 0
+      last_5_timespan = 0.001 if last_5_timespan <= 0
+
+      # Calculate error rate (errors per second) for each group
+      first_5_rate = 5.0 / first_5_timespan
+      last_5_rate = 5.0 / last_5_timespan
+
+      # Consider increasing if the rate is 50% higher
+      last_5_rate > first_5_rate * 1.5
+    end
+
+    # Get summary hash
+    #
+    # @return [Hash] Summary of statistics
+    def to_h
+      {
+        category: @category,
+        total_count: @total_count,
+        error_rate: error_rate.round(2),
+        by_severity: @by_severity,
+        by_code: @by_code,
+        most_common_code: most_common_code,
+        highest_severity: highest_severity,
+        first_seen: @first_seen,
+        last_seen: @last_seen,
+        trending: increasing? ? "increasing" : "stable",
+      }
+    end
+  end
+end

data/lib/fractor/execution_tracer.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+module Fractor
+  # Traces work item flow through the Fractor system for debugging.
+  # When enabled via FRACTOR_TRACE=1, captures the complete lifecycle of each work item.
+  #
+  # @example Instance-based usage (recommended)
+  #   tracer = ExecutionTracer.new(enabled: true)
+  #   tracer.trace(:created, work, worker_name: "MyWorker")
+  #
+  # @example Class-based usage (for backward compatibility)
+  #   ExecutionTracer.enabled = true
+  #   ExecutionTracer.trace(:created, work, worker_name: "MyWorker")
+  class ExecutionTracer
+    attr_reader :enabled, :trace_stream
+
+    # Initialize a new execution tracer instance.
+    #
+    # @param enabled [Boolean] Whether tracing is enabled
+    # @param trace_stream [IO] Output stream for trace messages
+    # @param check_env [Boolean] Whether to check FRACTOR_TRACE env var
+    def initialize(enabled: nil, trace_stream: nil, check_env: true)
+      @enabled = enabled || (check_env && ENV["FRACTOR_TRACE"] == "1")
+      @trace_stream = trace_stream || $stderr
+      @check_env = check_env
+    end
+
+    # Trace an event in the work item lifecycle.
+    #
+    # @param event [Symbol] The event type (:created, :queued, :assigned, :processing, :completed, :failed)
+    # @param work [Work] The work item
+    # @param context [Hash] Additional context (worker_name, timestamp, etc.)
+    def trace(event, work = nil, context = {})
+      return unless enabled?
+
+      timestamp = Time.now.strftime("%Y-%m-%d %H:%M:%S.%3N")
+      thread_id = Thread.current.object_id
+
+      # Build trace line
+      trace_line = build_trace_line(timestamp, event, work, context, thread_id)
+
+      # Output to trace stream
+      trace_stream.puts(trace_line)
+    end
+
+    # Set a custom trace stream.
+    #
+    # @param io [IO] The output stream
+    def trace_stream=(io)
+      @trace_stream = io
+    end
+
+    # Enable tracing.
+    def enable!
+      @enabled = true
+    end
+
+    # Disable tracing.
+    def disable!
+      @enabled = false
+    end
+
+    # Check if tracing is enabled.
+    #
+    # @return [Boolean] true if tracing is enabled
+    def enabled?
+      @enabled || (@check_env && ENV["FRACTOR_TRACE"] == "1")
+    end
+
+    # Reset tracer state.
+    def reset!
+      @enabled = nil
+      @trace_stream = $stderr
+    end
+
+    # Class-level convenience methods for backward compatibility.
+    # These use a singleton instance for global tracing.
+    class << self
+      # Enable or disable tracing (global).
+      #
+      # @param value [Boolean] Whether to enable tracing
+      def enabled=(value)
+        instance.enabled = value
+      end
+
+      # Check if global tracing is enabled.
+      #
+      # @return [Boolean] true if tracing is enabled
+      def enabled?
+        instance.enabled?
+      end
+
+      # Trace an event using the global tracer instance.
+      #
+      # @param event [Symbol] The event type
+      # @param work [Work] The work item
+      # @param context [Hash] Additional context
+      def trace(event, work = nil, context = {})
+        instance.trace(event, work, context)
+      end
+
+      # Get the global trace stream.
+      #
+      # @return [IO] The output stream
+      def trace_stream
+        instance.trace_stream
+      end
+
+      # Set a custom global trace stream.
+      #
+      # @param io [IO] The output stream
+      def trace_stream=(io)
+        instance.trace_stream = io
+      end
+
+      # Reset all global state (useful for testing and isolation).
+      def reset!
+        instance.reset!
+      end
+
+      # Get the singleton tracer instance.
+      #
+      # @return [ExecutionTracer] The global instance
+      def instance
+        @instance ||= new
+      end
+    end
+
+    private
+
+    # Build a formatted trace line.
+    #
+    # @param timestamp [String] Formatted timestamp
+    # @param event [Symbol] The event type
+    # @param work [Work] The work item
+    # @param context [Hash] Additional context
+    # @param thread_id [Integer] Thread ID
+    # @return [String] Formatted trace line
+    def build_trace_line(timestamp, event, work, context, thread_id)
+      parts = [
+        "[TRACE]",
+        timestamp,
+        "[T#{thread_id}]",
+        event.to_s.upcase,
+      ]
+
+      # Add work item info if available
+      if work
+        work_info = work.instance_of?(::Fractor::Work) ? "Work" : work.class.name
+        parts << "#{work_info}:#{work.object_id}"
+      end
+
+      # Add context info
+      parts << "worker=#{context[:worker_name]}" if context[:worker_name]
+      parts << "class=#{context[:worker_class]}" if context[:worker_class]
+      parts << "duration=#{context[:duration_ms]}ms" if context[:duration_ms]
+      parts << "queue_size=#{context[:queue_size]}" if context[:queue_size]
+
+      parts.join(" ")
+    end
+  end
+end

data/lib/fractor/logger.rb

@@ -0,0 +1,230 @@
+# frozen_string_literal: true
+
+require "logger"
+
+module Fractor
+  class << self
+    attr_writer :logger
+
+    # Get the Fractor logger instance
+    # @return [Logger] Logger instance
+    def logger
+      @logger ||= create_default_logger
+    end
+
+    # Enable debug logging to STDOUT
+    # @return [Logger] The configured logger
+    def enable_logging(level = Logger::DEBUG)
+      main_logger = create_logger_for_output($stdout, level)
+      @logger = main_logger
+      main_logger
+    end
+
+    # Disable logging entirely
+    def disable_logging
+      @logger = create_disabled_logger
+    end
+
+    # Check if debug logging is enabled
+    def debug_enabled?
+      @logger&.debug?
+    end
+
+    private
+
+    # Create default logger with sensible defaults
+    # Respects FRACTOR_LOG_LEVEL and FRACTOR_LOG_OUTPUT environment variables
+    # @return [Logger] Configured logger instance
+    def create_default_logger
+      # Get log level from environment variable or use INFO as default
+      level = parse_log_level(ENV["FRACTOR_LOG_LEVEL"]) || Logger::INFO
+
+      # Get output destination from environment variable or use STDOUT as default
+      output = parse_log_output(ENV["FRACTOR_LOG_OUTPUT"]) || $stdout
+
+      create_logger_for_output(output, level)
+    end
+
+    # Create a logger for the specified output with the given level
+    # @param output [IO, String, nil] Output destination
+    # @param level [Integer] Log level
+    # @return [Logger] Configured logger instance
+    def create_logger_for_output(output, level)
+      logger = Logger.new(output)
+      logger.level = level
+      logger.formatter = proc do |severity, datetime, _progname, msg|
+        "[#{datetime.strftime('%Y-%m-%d %H:%M:%S')}] #{severity}: #{msg}\n"
+      end
+      logger
+    end
+
+    # Parse log level from environment variable string
+    # @param level_str [String, nil] Log level string (DEBUG, INFO, WARN, ERROR)
+    # @return [Integer, nil] Logger constant or nil if invalid
+    def parse_log_level(level_str)
+      return nil unless level_str
+
+      case level_str.to_s.upcase
+      when "DEBUG" then Logger::DEBUG
+      when "INFO" then Logger::INFO
+      when "WARN" then Logger::WARN
+      when "ERROR" then Logger::ERROR
+      when "FATAL" then Logger::FATAL
+      when "UNKNOWN" then Logger::UNKNOWN
+      end
+    end
+
+    # Parse log output destination from environment variable string
+    # @param output_str [String, nil] Output destination (stdout, stderr, or file path)
+    # @return [IO, nil] Output destination
+    def parse_log_output(output_str)
+      return nil unless output_str
+
+      case output_str.to_s.downcase
+      when "stdout" then $stdout
+      when "stderr" then $stderr
+      else
+        # Treat as file path
+        begin
+          File.open(output_str.to_s, "a")
+        rescue ArgumentError, IOError => e
+          warn "Failed to open log file #{output_str}: #{e.message}, using STDOUT"
+          $stdout
+        end
+      end
+    end
+
+    # Create a disabled logger that outputs nothing
+    # @return [Logger] Disabled logger instance
+    def create_disabled_logger
+      logger = Logger.new(nil)
+      logger.level = Logger::UNKNOWN
+      logger
+    end
+
+    # Reset all global state (useful for testing and isolation)
+    def reset!
+      @logger = nil
+    end
+  end
+
+  # Ractor-safe logging module.
+  #
+  # This module provides logging functionality that works correctly
+  # within Ractors by using $stderr for unbuffered output.
+  #
+  # @example Inside a worker or ractor
+  #   Fractor::RactorLogger.debug("Processing work", ractor_name: "worker-1")
+  #   Fractor::RactorLogger.info("Worker started", ractor_name: "worker-1")
+  #   Fractor::RactorLogger.warn("Long processing time", ractor_name: "worker-1")
+  #   Fractor::RactorLogger.error("Worker failed", ractor_name: "worker-1", exception: e)
+  #
+  module RactorLogger
+    # Log levels in order of severity
+    LEVELS = {
+      debug: 0,
+      info: 1,
+      warn: 2,
+      error: 3,
+    }.freeze
+
+    class << self
+      # Get or set the current log level
+      # @return [Symbol] Current log level (:debug, :info, :warn, :error)
+      attr_accessor :level
+
+      # Enable or disable logging
+      # @return [Boolean] Whether logging is enabled
+      attr_accessor :enabled
+
+      # Enable debug mode (sets level to :debug)
+      def debug!
+        self.level = :debug
+        self.enabled = true
+      end
+
+      # Disable debug mode (sets level to :warn)
+      def nodebug!
+        self.level = :warn
+        self.enabled = false
+      end
+
+      # Check if a given log level would be logged
+      # @param lvl [Symbol] Log level to check
+      # @return [Boolean] True if messages at this level would be logged
+      def log?(lvl)
+        enabled && LEVELS[lvl.to_sym] >= LEVELS[level]
+      end
+
+      # Log a debug message
+      # @param message [String] Message to log
+      # @param ractor_name [String, nil] Name of the ractor (optional)
+      def debug(message, ractor_name: nil)
+        return unless log?(:debug)
+
+        log(:debug, message, ractor_name: ractor_name)
+      end
+
+      # Log an info message
+      # @param message [String] Message to log
+      # @param ractor_name [String, nil] Name of the ractor (optional)
+      def info(message, ractor_name: nil)
+        return unless log?(:info)
+
+        log(:info, message, ractor_name: ractor_name)
+      end
+
+      # Log a warning message
+      # @param message [String] Message to log
+      # @param ractor_name [String, nil] Name of the ractor (optional)
+      def warn(message, ractor_name: nil)
+        return unless log?(:warn)
+
+        log(:warn, message, ractor_name: ractor_name)
+      end
+
+      # Log an error message
+      # @param message [String] Message to log
+      # @param ractor_name [String, nil] Name of the ractor (optional)
+      # @param exception [Exception, nil] Exception object (optional)
+      def error(message, ractor_name: nil, exception: nil)
+        return unless log?(:error)
+
+        log(:error, message, ractor_name: ractor_name, exception: exception)
+      end
+
+      private
+
+      # Internal logging method
+      # @param level [Symbol] Log level
+      # @param message [String] Message to log
+      # @param ractor_name [String, nil] Name of the ractor
+      # @param exception [Exception, nil] Exception object
+      def log(level, message, ractor_name: nil, exception: nil)
+        timestamp = Time.now.strftime("%Y-%m-%d %H:%M:%S.%3N")
+        level_tag = level.to_s.upcase.ljust(5)
+
+        # Format: [TIMESTAMP] [LEVEL] [RACTOR] message
+        ractor_tag = ractor_name ? "[#{ractor_name}] " : ""
+        output = "[#{timestamp}] [#{level_tag}] #{ractor_tag}#{message}"
+
+        # Always use $stderr for immediate, unbuffered output
+        warn(output)
+        $stderr.flush
+
+        # If there's an exception, log the stack trace
+        if exception
+          warn("[#{timestamp}] [#{level_tag}] #{ractor_tag}#{exception.class}: #{exception.message}")
+          exception.backtrace&.each do |line|
+            warn("[#{timestamp}] [#{level_tag}] #{ractor_tag}    #{line}")
+          end
+          $stderr.flush
+        end
+      end
+    end
+
+    # Initialize with defaults - check FRACTOR_DEBUG environment variable
+    @enabled = ["1", "true"].include?(ENV["FRACTOR_DEBUG"])
+    @level = @enabled ? :debug : :info
+  end
+end