logstruct 0.0.1 → 0.0.2.pre.rc1

data/lib/log_struct/multi_error_reporter.rb

@@ -0,0 +1,149 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "enums/error_reporter"
+
+# Try to require all supported error reporting libraries
+# Users may have multiple installed, so we should load all of them
+%w[sentry-ruby bugsnag rollbar honeybadger].each do |gem_name|
+  require gem_name
+rescue LoadError
+  # If a particular gem is not available, we'll still load the others
+end
+
+module LogStruct
+  # MultiErrorReporter provides a unified interface for reporting errors to various services.
+  # You can also override this with your own error reporter by setting
+  # LogStruct#.config.error_reporting_handler
+  # NOTE: This is used for cases where an error should be reported
+  # but the operation should be allowed to continue (e.g. scrubbing log data.)
+  class MultiErrorReporter
+    # Class variable to store the selected reporter
+    @reporter = T.let(nil, T.nilable(ErrorReporter))
+
+    class << self
+      extend T::Sig
+
+      sig { returns(ErrorReporter) }
+      def reporter
+        @reporter ||= detect_reporter
+      end
+
+      # Set the reporter to use (user-friendly API that accepts symbols)
+      sig { params(reporter_type: T.any(ErrorReporter, Symbol)).returns(ErrorReporter) }
+      def reporter=(reporter_type)
+        @reporter = case reporter_type
+        when ErrorReporter
+          reporter_type
+        when Symbol
+          case reporter_type
+          when :sentry then ErrorReporter::Sentry
+          when :bugsnag then ErrorReporter::Bugsnag
+          when :rollbar then ErrorReporter::Rollbar
+          when :honeybadger then ErrorReporter::Honeybadger
+          when :rails_logger then ErrorReporter::RailsLogger
+          else
+            valid_types = ErrorReporter.values.map { |v| ":#{v.serialize}" }.join(", ")
+            raise ArgumentError, "Unknown reporter type: #{reporter_type}. Valid types are: #{valid_types}"
+          end
+        end
+      end
+
+      # Auto-detect which error reporting service to use
+      sig { returns(ErrorReporter) }
+      def detect_reporter
+        if defined?(::Sentry)
+          ErrorReporter::Sentry
+        elsif defined?(::Bugsnag)
+          ErrorReporter::Bugsnag
+        elsif defined?(::Rollbar)
+          ErrorReporter::Rollbar
+        elsif defined?(::Honeybadger)
+          ErrorReporter::Honeybadger
+        else
+          ErrorReporter::RailsLogger
+        end
+      end
+
+      # Report an error to the configured error reporting service
+      sig { params(error: StandardError, context: T::Hash[T.untyped, T.untyped]).void }
+      def report_error(error, context = {})
+        # Call the appropriate reporter method based on what's available
+        case reporter
+        when ErrorReporter::Sentry
+          report_to_sentry(error, context)
+        when ErrorReporter::Bugsnag
+          report_to_bugsnag(error, context)
+        when ErrorReporter::Rollbar
+          report_to_rollbar(error, context)
+        when ErrorReporter::Honeybadger
+          report_to_honeybadger(error, context)
+        else
+          fallback_logging(error, context)
+        end
+      end
+
+      private
+
+      # Report to Sentry
+      sig { params(error: StandardError, context: T::Hash[T.untyped, T.untyped]).void }
+      def report_to_sentry(error, context = {})
+        return unless defined?(::Sentry)
+
+        # Use the proper Sentry interface defined in the RBI
+        ::Sentry.capture_exception(error, extra: context)
+      rescue => e
+        fallback_logging(e, {original_error: error.class.to_s})
+      end
+
+      # Report to Bugsnag
+      sig { params(error: StandardError, context: T::Hash[T.untyped, T.untyped]).void }
+      def report_to_bugsnag(error, context = {})
+        return unless defined?(::Bugsnag)
+
+        ::Bugsnag.notify(error) do |report|
+          report.add_metadata(:context, context)
+        end
+      rescue => e
+        fallback_logging(e, {original_error: error.class.to_s})
+      end
+
+      # Report to Rollbar
+      sig { params(error: StandardError, context: T::Hash[T.untyped, T.untyped]).void }
+      def report_to_rollbar(error, context = {})
+        return unless defined?(::Rollbar)
+
+        ::Rollbar.error(error, context)
+      rescue => e
+        fallback_logging(e, {original_error: error.class.to_s})
+      end
+
+      # Report to Honeybadger
+      sig { params(error: StandardError, context: T::Hash[T.untyped, T.untyped]).void }
+      def report_to_honeybadger(error, context = {})
+        return unless defined?(::Honeybadger)
+
+        ::Honeybadger.notify(error, context: context)
+      rescue => e
+        fallback_logging(e, {original_error: error.class.to_s})
+      end
+
+      # Fallback logging when no error reporting services are available
+      # Uses the LogStruct.error method to properly log the error
+      sig { params(error: StandardError, context: T::Hash[T.untyped, T.untyped]).void }
+      def fallback_logging(error, context = {})
+        return if error.nil?
+
+        # Create a proper error log entry
+        error_log = Log::Error.from_exception(
+          Source::LogStruct,
+          error,
+          context
+        )
+
+        # Use LogStruct.error to properly log the error
+        LogStruct.error(error_log)
+      end
+    end
+  end
+end

data/lib/log_struct/param_filters.rb

@@ -0,0 +1,89 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "digest"
+require_relative "hash_utils"
+
+module LogStruct
+  # This class contains methods for filtering sensitive data in logs
+  # It is used by Formatter to determine which keys should be filtered
+  class ParamFilters
+    class << self
+      extend T::Sig
+
+      # Check if a key should be filtered based on our defined sensitive keys
+      sig { params(key: T.any(String, Symbol)).returns(T::Boolean) }
+      def should_filter_key?(key)
+        LogStruct.config.filters.filter_keys.include?(key.to_s.downcase.to_sym)
+      end
+
+      # Check if a key should be hashed rather than completely filtered
+      sig { params(key: T.any(String, Symbol)).returns(T::Boolean) }
+      def should_include_string_hash?(key)
+        LogStruct.config.filters.filter_keys_with_hashes.include?(key.to_s.downcase.to_sym)
+      end
+
+      # Convert a value to a filtered summary hash (e.g. { _filtered: { class: "String", ... }})
+      sig { params(key: T.any(String, Symbol), data: T.untyped).returns(T::Hash[Symbol, T.untyped]) }
+      def summarize_json_attribute(key, data)
+        case data
+        when Hash
+          summarize_hash(data)
+        when Array
+          summarize_array(data)
+        when String
+          summarize_string(data, should_include_string_hash?(key))
+        else
+          {_class: data.class}
+        end
+      end
+
+      # Summarize a String for logging, including details and an SHA256 hash (if configured)
+      sig { params(string: String, include_hash: T::Boolean).returns(T::Hash[Symbol, T.untyped]) }
+      def summarize_string(string, include_hash)
+        filtered_string = {
+          _class: String
+        }
+        if include_hash
+          filtered_string[:_hash] = HashUtils.hash_value(string)
+        else
+          filtered_string[:_bytes] = string.bytesize
+        end
+
+        filtered_string
+      end
+
+      # Summarize a Hash for logging, including details about the size and keys
+      sig { params(hash: T::Hash[T.untyped, T.untyped]).returns(T::Hash[Symbol, T.untyped]) }
+      def summarize_hash(hash)
+        return {_class: "Hash", _empty: true} if hash.empty?
+
+        # Don't include byte size if hash contains any filtered keys
+        has_sensitive_keys = hash.keys.any? { |key| should_filter_key?(key) }
+
+        summary = {
+          _class: Hash,
+          _keys_count: hash.keys.size,
+          _keys: hash.keys.map(&:to_sym).take(10)
+        }
+
+        # Only add byte size if no sensitive keys are present
+        summary[:_bytes] = hash.to_json.bytesize unless has_sensitive_keys
+
+        summary
+      end
+
+      # Summarize an Array for logging, including details about the size and items
+      sig { params(array: T::Array[T.untyped]).returns(T::Hash[Symbol, T.untyped]) }
+      def summarize_array(array)
+        return {_class: "Array", _empty: true} if array.empty?
+
+        {
+          _class: Array,
+          _count: array.size,
+          _bytes: array.to_json.bytesize
+        }
+      end
+    end
+  end
+end

data/lib/log_struct/railtie.rb

@@ -0,0 +1,31 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "rails"
+require "semantic_logger"
+require_relative "formatter"
+require_relative "semantic_logger/setup"
+
+module LogStruct
+  # Railtie to integrate with Rails
+  class Railtie < ::Rails::Railtie
+    # Configure early, right after logger initialization
+    initializer "logstruct.configure_logger", after: :initialize_logger do |app|
+      next unless LogStruct.enabled?
+
+      # Use SemanticLogger for powerful logging features
+      LogStruct::SemanticLogger::Setup.configure_semantic_logger(app)
+    end
+
+    # Setup all integrations after logger setup is complete
+    initializer "logstruct.setup", before: :build_middleware_stack do |app|
+      next unless LogStruct.enabled?
+
+      # Merge Rails filter parameters into our filters
+      LogStruct.merge_rails_filter_parameters!
+
+      # Set up all integrations
+      Integrations.setup_integrations
+    end
+  end
+end

data/lib/log_struct/semantic_logger/color_formatter.rb

@@ -0,0 +1,209 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "semantic_logger"
+require_relative "formatter"
+
+module LogStruct
+  module SemanticLogger
+    # Development-Optimized Colorized JSON Formatter
+    #
+    # This formatter extends SemanticLogger's Color formatter to provide beautiful,
+    # readable JSON output in development environments. It significantly improves
+    # the developer experience when working with structured logs.
+    #
+    # ## Benefits of Colorized Output:
+    #
+    # ### Readability
+    # - **Syntax highlighting**: JSON keys, values, and data types are color-coded
+    # - **Visual hierarchy**: Different colors help identify structure at a glance
+    # - **Error spotting**: Quickly identify malformed data or unexpected values
+    # - **Context separation**: Log entries are visually distinct from each other
+    #
+    # ### Performance in Development
+    # - **Faster debugging**: Quickly scan logs without reading every character
+    # - **Pattern recognition**: Colors help identify common log patterns
+    # - **Reduced cognitive load**: Less mental effort required to parse log output
+    # - **Improved workflow**: Spend less time reading logs, more time coding
+    #
+    # ### Customization
+    # - **Configurable colors**: Customize colors for keys, strings, numbers, etc.
+    # - **Environment-aware**: Automatically disabled in production/CI environments
+    # - **Fallback support**: Gracefully falls back to standard formatting if needed
+    #
+    # ## Color Mapping:
+    # - **Keys**: Yellow - Easy to spot field names
+    # - **Strings**: Green - Clear indication of text values
+    # - **Numbers**: Blue - Numeric values stand out
+    # - **Booleans**: Magenta - true/false values are distinctive
+    # - **Null**: Red - Missing values are immediately visible
+    # - **Logger names**: Cyan - Source identification
+    #
+    # ## Integration with SemanticLogger:
+    # This formatter preserves all SemanticLogger benefits (performance, threading,
+    # reliability) while adding visual enhancements. It processes LogStruct types,
+    # hashes, and plain messages with appropriate colorization.
+    #
+    # The formatter is automatically enabled in development when `enable_color_output`
+    # is true (default), providing zero-configuration enhanced logging experience.
+    class ColorFormatter < ::SemanticLogger::Formatters::Color
+      extend T::Sig
+
+      sig { params(color_map: T.nilable(T::Hash[Symbol, Symbol]), args: T.untyped).void }
+      def initialize(color_map: nil, **args)
+        super(**args)
+        @logstruct_formatter = T.let(LogStruct::Formatter.new, LogStruct::Formatter)
+
+        # Set up custom color mapping
+        @custom_colors = T.let(color_map || default_color_map, T::Hash[Symbol, Symbol])
+      end
+
+      sig { override.params(log: ::SemanticLogger::Log, logger: T.untyped).returns(String) }
+      def call(log, logger)
+        # Handle LogStruct types specially with colorization
+        if log.payload.is_a?(LogStruct::Log::Interfaces::CommonFields)
+          # Get the LogStruct formatted JSON
+          logstruct_json = @logstruct_formatter.call(log.level, log.time, log.name, log.payload)
+
+          # Parse and colorize it
+          begin
+            parsed_data = T.let(JSON.parse(logstruct_json), T::Hash[String, T.untyped])
+            colorized_json = colorize_json(parsed_data)
+
+            # Use SemanticLogger's prefix formatting but with our colorized content
+            prefix = format("%<time>s %<level>s [%<process>s] %<name>s -- ",
+              time: format_time(log.time),
+              level: format_level(log.level),
+              process: log.process_info,
+              name: format_name(log.name))
+
+            "#{prefix}#{colorized_json}\n"
+          rescue JSON::ParserError
+            # Fallback to standard formatting
+            super
+          end
+        elsif log.payload.is_a?(Hash) || log.payload.is_a?(T::Struct)
+          # Process hashes through our formatter then colorize
+          begin
+            logstruct_json = @logstruct_formatter.call(log.level, log.time, log.name, log.payload)
+            parsed_data = T.let(JSON.parse(logstruct_json), T::Hash[String, T.untyped])
+            colorized_json = colorize_json(parsed_data)
+
+            prefix = format("%<time>s %<level>s [%<process>s] %<name>s -- ",
+              time: format_time(log.time),
+              level: format_level(log.level),
+              process: log.process_info,
+              name: format_name(log.name))
+
+            "#{prefix}#{colorized_json}\n"
+          rescue JSON::ParserError
+            # Fallback to standard formatting
+            super
+          end
+        else
+          # For plain messages, use SemanticLogger's default colorization
+          super
+        end
+      end
+
+      private
+
+      sig { returns(LogStruct::Formatter) }
+      attr_reader :logstruct_formatter
+
+      # Default color mapping for LogStruct JSON
+      sig { returns(T::Hash[Symbol, Symbol]) }
+      def default_color_map
+        {
+          key: :yellow,
+          string: :green,
+          number: :blue,
+          bool: :magenta,
+          nil: :red,
+          name: :cyan
+        }
+      end
+
+      # Simple JSON colorizer that adds ANSI codes
+      sig { params(data: T::Hash[String, T.untyped]).returns(String) }
+      def colorize_json(data)
+        # For now, just return a simple colorized version of the JSON
+        # This is much simpler than the full recursive approach
+        json_str = JSON.pretty_generate(data)
+
+        # Apply basic colorization with regex
+        json_str.gsub(/"([^"]+)":/, colorize_text('\1', :key) + ":")
+          .gsub(/: "([^"]*)"/, ": " + colorize_text('\1', :string))
+          .gsub(/: (\d+\.?\d*)/, ": " + colorize_text('\1', :number))
+          .gsub(/: (true|false)/, ": " + colorize_text('\1', :bool))
+          .gsub(": null", ": " + colorize_text("null", :nil))
+      end
+
+      # Add ANSI color codes to text
+      sig { params(text: String, color_type: Symbol).returns(String) }
+      def colorize_text(text, color_type)
+        color = @custom_colors[color_type] || :white
+        "\e[#{color_code_for(color)}m#{text}\e[0m"
+      end
+
+      # Format timestamp
+      sig { params(time: Time).returns(String) }
+      def format_time(time)
+        time.strftime("%Y-%m-%d %H:%M:%S.%6N")
+      end
+
+      # Format log level with color
+      sig { params(level: T.any(String, Symbol)).returns(String) }
+      def format_level(level)
+        level_str = level.to_s.upcase[0]
+        color = level_color_for(level.to_sym)
+        "\e[#{color_code_for(color)}m#{level_str}\e[0m"
+      end
+
+      # Format logger name with color
+      sig { params(name: T.nilable(String)).returns(String) }
+      def format_name(name)
+        return "" unless name
+        color = @custom_colors[:name] || :cyan
+        "\e[#{color_code_for(color)}m#{name}\e[0m"
+      end
+
+      # Get color for log level
+      sig { params(level: Symbol).returns(Symbol) }
+      def level_color_for(level)
+        case level
+        when :debug then :magenta
+        when :info then :cyan
+        when :warn then :yellow
+        when :error then :red
+        when :fatal then :red
+        else :cyan
+        end
+      end
+
+      # Get ANSI color code for color symbol
+      sig { params(color: Symbol).returns(String) }
+      def color_code_for(color)
+        case color
+        when :black then "30"
+        when :red then "31"
+        when :green then "32"
+        when :yellow then "33"
+        when :blue then "34"
+        when :magenta then "35"
+        when :cyan then "36"
+        when :white then "37"
+        when :bright_black then "90"
+        when :bright_red then "91"
+        when :bright_green then "92"
+        when :bright_yellow then "93"
+        when :bright_blue then "94"
+        when :bright_magenta then "95"
+        when :bright_cyan then "96"
+        when :bright_white then "97"
+        else "37" # default to white
+        end
+      end
+    end
+  end
+end

data/lib/log_struct/semantic_logger/formatter.rb

@@ -0,0 +1,94 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "semantic_logger"
+require_relative "../formatter"
+
+module LogStruct
+  module SemanticLogger
+    # High-Performance JSON Formatter with LogStruct Integration
+    #
+    # This formatter extends SemanticLogger's JSON formatter to provide optimal
+    # JSON serialization performance while preserving all LogStruct features
+    # including data filtering, sensitive data scrubbing, and type-safe structures.
+    #
+    # ## Performance Advantages Over Rails Logger:
+    #
+    # ### Serialization Performance
+    # - **Direct JSON generation**: Bypasses intermediate object creation
+    # - **Streaming serialization**: Memory-efficient processing of large objects
+    # - **Type-optimized paths**: Fast serialization for common data types
+    # - **Zero-copy operations**: Minimal memory allocation during serialization
+    #
+    # ### Memory Efficiency
+    # - **Object reuse**: Formatter instances are reused across log calls
+    # - **Lazy evaluation**: Only processes data that will be included in output
+    # - **Efficient buffering**: Optimal buffer sizes for JSON generation
+    # - **Garbage collection friendly**: Minimal object allocation reduces GC pressure
+    #
+    # ### Integration Benefits
+    # - **LogStruct compatibility**: Native support for typed log structures
+    # - **Filter preservation**: Maintains all LogStruct filtering capabilities
+    # - **Scrubbing integration**: Seamless sensitive data scrubbing
+    # - **Error handling**: Robust handling of serialization errors
+    #
+    # ## Feature Preservation:
+    # This formatter maintains full compatibility with LogStruct's features:
+    # - Sensitive data filtering (passwords, tokens, etc.)
+    # - Recursive object scrubbing and processing
+    # - Type-safe log structure handling
+    # - Custom field transformations
+    # - Metadata preservation and enrichment
+    #
+    # ## JSON Output Structure:
+    # The formatter produces consistent, parseable JSON that includes:
+    # - Standard log fields (timestamp, level, message, logger name)
+    # - LogStruct-specific fields (source, event, context)
+    # - SemanticLogger metadata (process ID, thread ID, tags)
+    # - Application-specific payload data
+    #
+    # This combination provides the performance benefits of SemanticLogger with
+    # the structured data benefits of LogStruct, resulting in faster, more
+    # reliable logging for high-traffic applications.
+    class Formatter < ::SemanticLogger::Formatters::Json
+      extend T::Sig
+
+      sig { void }
+      def initialize
+        super
+        @logstruct_formatter = T.let(LogStruct::Formatter.new, LogStruct::Formatter)
+      end
+
+      sig { params(log: ::SemanticLogger::Log, logger: T.untyped).returns(String) }
+      def call(log, logger)
+        # Handle LogStruct types specially - they get wrapped in payload hash by SemanticLogger
+        if log.payload.is_a?(Hash) && log.payload[:payload].is_a?(LogStruct::Log::Interfaces::CommonFields)
+          # Use our formatter to process LogStruct types
+          @logstruct_formatter.call(log.level, log.time, log.name, log.payload[:payload])
+        elsif log.payload.is_a?(LogStruct::Log::Interfaces::CommonFields)
+          # Direct LogStruct (fallback case)
+          @logstruct_formatter.call(log.level, log.time, log.name, log.payload)
+        elsif log.payload.is_a?(Hash) && log.payload[:payload].is_a?(T::Struct)
+          # T::Struct wrapped in payload hash
+          @logstruct_formatter.call(log.level, log.time, log.name, log.payload[:payload])
+        elsif log.payload.is_a?(Hash) || log.payload.is_a?(T::Struct)
+          # Process hashes and T::Structs through our formatter
+          @logstruct_formatter.call(log.level, log.time, log.name, log.payload)
+        else
+          # For plain messages, create a Plain log entry
+          message_data = log.payload || log.message
+          plain_log = LogStruct::Log::Plain.new(
+            message: message_data,
+            timestamp: log.time
+          )
+          @logstruct_formatter.call(log.level, log.time, log.name, plain_log)
+        end
+      end
+
+      private
+
+      sig { returns(LogStruct::Formatter) }
+      attr_reader :logstruct_formatter
+    end
+  end
+end