makit 0.0.98 → 0.0.111

data/lib/makit/logging/sinks/structured.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Makit
+  module Logging
+    module Sinks
+      # Structured sink for adding metadata to log requests
+      #
+      # This sink enriches log requests with structured metadata like
+      # process information, thread details, and other contextual data that
+      # can be useful for debugging and monitoring. It follows the same
+      # pattern as other sinks but focuses on data enrichment rather than output.
+      #
+      # @example Basic usage
+      #   structured_sink = Structured.new
+      #   logger = Logger.new(sinks: [structured_sink])
+      #   logger.info("Processing started")
+      #   # Adds metadata like process_id, thread_id, etc.
+      #
+      # @example With custom metadata
+      #   structured_sink = Structured.new(
+      #     custom_metadata: { environment: "production" }
+      #   )
+      class Structured < Base
+        # Initialize structured sink
+        #
+        # @param include_process_info [Boolean] whether to include process information
+        # @param include_thread_info [Boolean] whether to include thread information
+        # @param include_timing [Boolean] whether to include timing information
+        # @param custom_metadata [Hash] custom metadata to add to all log requests
+        def initialize(include_process_info: true, include_thread_info: true, include_timing: true, custom_metadata: {})
+          @include_process_info = include_process_info
+          @include_thread_info = include_thread_info
+          @include_timing = include_timing
+          @custom_metadata = custom_metadata.dup
+        end
+
+        # Execute sink logic to add structured metadata
+        #
+        # @param log_request [LogRequest] the log request to process
+        # @yield [LogRequest] yields the processed log request to the next sink
+        # @yieldreturn [LogRequest] the processed log request
+        # @return [LogRequest] the final processed log request
+        def call(log_request, &block)
+          add_structured_metadata(log_request)
+          block&.call(log_request) if block_given?
+          log_request
+        end
+
+        # Get sink configuration
+        #
+        # @return [Hash] sink configuration
+        def config
+          {
+            name: self.class.name.split("::").last,
+            include_process_info: @include_process_info,
+            include_thread_info: @include_thread_info,
+            include_timing: @include_timing,
+            custom_metadata: @custom_metadata,
+          }
+        end
+
+        private
+
+        # Add structured metadata to the log request
+        #
+        # @param log_request [LogRequest] the log request to enrich
+        def add_structured_metadata(log_request)
+          metadata = {}
+
+          # Add process information
+          if @include_process_info
+            metadata.merge!(get_process_metadata)
+          end
+
+          # Add thread information
+          if @include_thread_info
+            metadata.merge!(get_thread_metadata)
+          end
+
+          # Add timing information
+          if @include_timing
+            metadata.merge!(get_timing_metadata)
+          end
+
+          # Add custom metadata
+          metadata.merge!(@custom_metadata)
+
+          # Add to log request
+          log_request.add_metadata(metadata)
+        end
+
+        # Get process-related metadata
+        #
+        # @return [Hash] process metadata
+        def get_process_metadata
+          {
+            process_id: ::Process.pid,
+            process_title: $0,
+            ruby_version: RUBY_VERSION,
+            ruby_platform: RUBY_PLATFORM,
+          }
+        end
+
+        # Get thread-related metadata
+        #
+        # @return [Hash] thread metadata
+        def get_thread_metadata
+          {
+            thread_id: Thread.current.object_id,
+            thread_name: Thread.current.name || "main",
+          }
+        end
+
+        # Get timing-related metadata
+        #
+        # @return [Hash] timing metadata
+        def get_timing_metadata
+          {
+            timestamp: Time.now.iso8601,
+            unix_timestamp: Time.now.to_i,
+            timezone: Time.now.zone,
+          }
+        end
+      end
+    end
+  end
+end

data/lib/makit/logging/sinks/unified_file_sink.rb

@@ -0,0 +1,303 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "../format_registry"
+require "fileutils"
+
+module Makit
+  module Logging
+    module Sinks
+      # Unified file sink with configurable multiple outputs
+      #
+      # This sink replaces the need for multiple separate sinks by providing
+      # a single, highly configurable sink that can write to multiple files
+      # with different formats, filtering, and options. It supports console
+      # output, file logging, and structured logging through configuration.
+      #
+      # @example Basic usage with console and file output
+      #   sink = UnifiedFileSink.new(
+      #     configurations: [
+      #       { file: $stdout, format: :console },
+      #       { file: "logs/app.log", format: :json }
+      #     ]
+      #   )
+      #
+      # @example Advanced configuration with filtering and formatting
+      #   sink = UnifiedFileSink.new(
+      #     configurations: [
+      #       {
+      #         file: $stdout,
+      #         format: :console,
+      #         show_timestamp: true,
+      #         show_level: true
+      #       },
+      #       {
+      #         file: "logs/debug.log",
+      #         format: :text,
+      #         min_level: :debug,
+      #         include_context: true
+      #       },
+      #       {
+      #         file: "logs/audit.log",
+      #         format: :json,
+      #         min_level: :info,
+      #         include_metadata: true
+      #       }
+      #     ]
+      #   )
+      class UnifiedFileSink < Base
+        # @return [Array<Hash>] list of output configurations
+        attr_reader :configurations
+
+        # Initialize unified file sink
+        #
+        # @param configurations [Array<Hash>] list of output configurations
+        def initialize(configurations: [])
+          @configurations = validate_configurations(configurations)
+          @formatters = {}
+          @files = {}
+
+          # Pre-initialize formatters and files
+          initialize_formatters
+          initialize_files
+        end
+
+        # Execute sink logic to write log entry to configured outputs
+        #
+        # @param log_request [LogRequest] the log request to process
+        # @yield [LogRequest] yields the processed log request to the next sink
+        # @yieldreturn [LogRequest] the processed log request
+        # @return [LogRequest] the final processed log request
+        def call(log_request, &block)
+          write_to_outputs(log_request)
+          block&.call(log_request) if block_given?
+          log_request
+        end
+
+        # Get sink configuration
+        #
+        # @return [Hash] sink configuration
+        def config
+          {
+            name: self.class.name.split("::").last,
+            configurations_count: @configurations.length,
+            configurations: @configurations.map { |config| sanitize_config(config) },
+          }
+        end
+
+        private
+
+        # Validate configuration array
+        #
+        # @param configurations [Array<Hash>] configurations to validate
+        # @return [Array<Hash>] validated configurations
+        # @raise [ArgumentError] if configuration is invalid
+        def validate_configurations(configurations)
+          raise ArgumentError, "configurations must be an array" unless configurations.is_a?(Array)
+          raise ArgumentError, "at least one configuration is required" if configurations.empty?
+
+          configurations.each_with_index do |config, index|
+            validate_single_configuration(config, index)
+          end
+
+          configurations
+        end
+
+        # Validate a single configuration
+        #
+        # @param config [Hash] configuration to validate
+        # @param index [Integer] configuration index for error messages
+        # @raise [ArgumentError] if configuration is invalid
+        def validate_single_configuration(config, index)
+          raise ArgumentError, "configuration #{index} must be a hash" unless config.is_a?(Hash)
+
+          required_keys = [:file, :format]
+          missing_keys = required_keys - config.keys
+          raise ArgumentError, "configuration #{index} missing required keys: #{missing_keys.join(", ")}" unless missing_keys.empty?
+
+          # Validate file
+          file = config[:file]
+          unless file.is_a?(String) || file.is_a?(IO) || file.respond_to?(:write)
+            raise ArgumentError, "configuration #{index} file must be a String path, IO object, or writable object"
+          end
+
+          # Validate format
+          format = config[:format]
+          unless format.is_a?(Symbol) || format.is_a?(String)
+            raise ArgumentError, "configuration #{index} format must be a Symbol or String"
+          end
+
+          # Validate log levels if specified
+          if config[:min_level] && !valid_log_level?(config[:min_level])
+            raise ArgumentError, "configuration #{index} min_level must be a valid log level"
+          end
+
+          if config[:max_level] && !valid_log_level?(config[:max_level])
+            raise ArgumentError, "configuration #{index} max_level must be a valid log level"
+          end
+        end
+
+        # Check if log level is valid
+        #
+        # @param level [Symbol] log level to check
+        # @return [Boolean] true if valid
+        def valid_log_level?(level)
+          %i[debug info warn error fatal success].include?(level)
+        end
+
+        # Initialize formatters for each configuration
+        #
+        # @return [void]
+        def initialize_formatters
+          @configurations.each_with_index do |config, index|
+            format = config[:format].to_sym
+            formatter_options = config[:formatter_options] || {}
+
+            # Merge configuration options into formatter options
+            formatter_options[:include_context] = config[:include_context] if config.key?(:include_context)
+            formatter_options[:include_metadata] = config[:include_metadata] if config.key?(:include_metadata)
+            formatter_options[:show_timestamp] = config[:show_timestamp] if config.key?(:show_timestamp)
+            formatter_options[:show_level] = config[:show_level] if config.key?(:show_level)
+
+            begin
+              formatter_class = FormatRegistry.get(format)
+
+              # Handle different formatter initialization patterns
+              if formatter_class == Formatters::ConsoleFormatter
+                # ConsoleFormatter expects keyword arguments
+                @formatters[index] = formatter_class.new(
+                  show_timestamp: formatter_options[:show_timestamp] || false,
+                  show_level: formatter_options[:show_level] || false,
+                )
+              elsif formatter_class == Formatters::TextFormatter
+                # TextFormatter expects keyword arguments
+                @formatters[index] = formatter_class.new(
+                  timestamp_format: formatter_options[:timestamp_format] || "%Y-%m-%d %H:%M:%S",
+                  include_context: formatter_options[:include_context] || false,
+                )
+              elsif formatter_class == Formatters::JsonFormatter
+                # JsonFormatter expects keyword arguments
+                @formatters[index] = formatter_class.new(
+                  options: formatter_options,
+                )
+              elsif formatter_class == Formatters::PlainTextFormatter
+                # PlainTextFormatter expects keyword arguments
+                @formatters[index] = formatter_class.new(
+                  include_context: formatter_options[:include_context] || false,
+                )
+              else
+                # Other formatters expect hash or no arguments
+                if formatter_options.empty?
+                  @formatters[index] = formatter_class.new
+                else
+                  @formatters[index] = formatter_class.new(formatter_options)
+                end
+              end
+            rescue ArgumentError => e
+              raise ArgumentError, "configuration #{index} has invalid format '#{format}': #{e.message}"
+            end
+          end
+        end
+
+        # Initialize file handles for each configuration
+        #
+        # @return [void]
+        def initialize_files
+          @configurations.each_with_index do |config, index|
+            file = config[:file]
+
+            if file.is_a?(String)
+              # Ensure directory exists
+              FileUtils.mkdir_p(File.dirname(file)) unless File.dirname(file) == "."
+
+              # Open file with appropriate mode
+              mode = config[:append] != false ? "a" : "w"
+              @files[index] = File.open(file, mode)
+            else
+              # Use IO object directly
+              @files[index] = file
+            end
+          end
+        end
+
+        # Write log request to all applicable outputs
+        #
+        # @param log_request [LogRequest] the log request to write
+        def write_to_outputs(log_request)
+          @configurations.each_with_index do |config, index|
+            next unless should_output?(log_request, config)
+
+            formatter = @formatters[index]
+            file = @files[index]
+
+            formatted_message = formatter.format(log_request)
+            file.write(formatted_message)
+            file.write("\n") unless config[:no_newline]
+            file.flush
+          end
+        end
+
+        # Check if log request should be output to this configuration
+        #
+        # @param log_request [LogRequest] the log request
+        # @param config [Hash] the output configuration
+        # @return [Boolean] true if should output
+        def should_output?(log_request, config)
+          # Check level filtering
+          if config[:min_level] && !level_greater_or_equal?(log_request.level, config[:min_level])
+            return false
+          end
+
+          if config[:max_level] && !level_less_or_equal?(log_request.level, config[:max_level])
+            return false
+          end
+
+          # Check custom condition
+          if config[:condition] && !config[:condition].call(log_request)
+            return false
+          end
+
+          true
+        end
+
+        # Check if log level is greater than or equal to minimum level
+        #
+        # @param level [Symbol] log level to check
+        # @param min_level [Symbol] minimum level
+        # @return [Boolean] true if level >= min_level
+        def level_greater_or_equal?(level, min_level)
+          levels = %i[debug info warn error fatal success]
+          levels.index(level) >= levels.index(min_level)
+        end
+
+        # Check if log level is less than or equal to maximum level
+        #
+        # @param level [Symbol] log level to check
+        # @param max_level [Symbol] maximum level
+        # @return [Boolean] true if level <= max_level
+        def level_less_or_equal?(level, max_level)
+          levels = %i[debug info warn error fatal success]
+          levels.index(level) <= levels.index(max_level)
+        end
+
+        # Sanitize configuration for display (remove sensitive data)
+        #
+        # @param config [Hash] configuration to sanitize
+        # @return [Hash] sanitized configuration
+        def sanitize_config(config)
+          sanitized = config.dup
+
+          # Remove condition procs and other non-serializable items
+          sanitized.delete(:condition)
+
+          # Convert IO objects to string representation
+          if sanitized[:file].is_a?(IO)
+            sanitized[:file] = "<#{sanitized[:file].class.name}>"
+          end
+
+          sanitized
+        end
+      end
+    end
+  end
+end