lambda_loadout 0.0.1

data/lib/lambda_loadout/logger.rb

@@ -0,0 +1,256 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'logger'
+
+module LambdaLoadout
+  # Structured logger with Lambda context enrichment
+  #
+  # Provides JSON structured logging with automatic Lambda context injection,
+  # correlation IDs, and support for custom fields.
+  #
+  # @example Basic usage
+  #   logger = LambdaLoadout::Logger.new(service: "payment")
+  #   logger.info("Processing payment", order_id: "12345")
+  #   # => {"level":"INFO","timestamp":"2025-01-01T12:00:00.000Z","message":"Processing payment","service":"payment","order_id":"12345"}
+  #
+  # @example With Lambda context
+  #   def lambda_handler(event:, context:)
+  #     logger = LambdaLoadout::Logger.new(service: "payment")
+  #     logger.inject_lambda_context(context)
+  #     logger.info("Handler invoked")
+  #     # => Includes function_name, request_id, etc.
+  #   end
+  class Logger
+    attr_reader :service, :level, :output
+    attr_accessor :lambda_context
+
+    LOG_LEVELS = {
+      debug: 0,
+      info: 1,
+      warn: 2,
+      error: 3,
+      fatal: 4
+    }.freeze
+
+    # Initialize a new structured logger
+    #
+    # @param service [String] Service name (adds 'service' field to all logs)
+    # @param level [Symbol, String] Log level (:debug, :info, :warn, :error, :fatal)
+    # @param output [IO] Output stream (defaults to $stdout)
+    # @param sampling_rate [Float] Sampling rate for debug logs (0.0-1.0)
+    def initialize(service: nil, level: :info, output: $stdout, sampling_rate: nil)
+      @service = service || ENV.fetch('POWERTOOLS_SERVICE_NAME', nil)
+      @level = LOG_LEVELS[level.to_sym] || LOG_LEVELS[:info]
+      @output = output
+      @sampling_rate = sampling_rate&.to_f
+      @lambda_context = nil
+      @persistent_fields = {}
+      @persistent_fields['service'] = @service if @service
+    end
+
+    # Inject Lambda context into logs
+    #
+    # @param context [Object] Lambda context object
+    # @return [void]
+    def inject_lambda_context(context)
+      @lambda_context = context
+    end
+
+    # Add persistent fields that will be included in all log entries
+    #
+    # @param fields [Hash] Fields to add to all logs
+    # @return [void]
+    def append_keys(**fields)
+      @persistent_fields.merge!(fields.transform_keys(&:to_s))
+    end
+
+    # Remove persistent fields
+    #
+    # @param keys [Array<Symbol, String>] Keys to remove
+    # @return [void]
+    def remove_keys(*keys)
+      keys.each { |key| @persistent_fields.delete(key.to_s) }
+    end
+
+    # Log debug message
+    #
+    # @param message [String] Log message
+    # @param exception [Exception, nil] Optional exception object
+    # @param fields [Hash] Additional fields
+    # @return [void]
+    def debug(message, exception = nil, **fields)
+      return unless should_log?(:debug)
+
+      if exception.is_a?(Exception)
+        fields[:error] = exception.message
+        fields[:error_class] = exception.class.name
+        fields[:backtrace] = exception.backtrace&.first(10)
+      end
+
+      log(:debug, message, **fields)
+    end
+
+    # Log info message
+    #
+    # @param message [String] Log message
+    # @param exception [Exception, nil] Optional exception object
+    # @param fields [Hash] Additional fields
+    # @return [void]
+    def info(message, exception = nil, **fields)
+      return unless should_log?(:info)
+
+      if exception.is_a?(Exception)
+        fields[:error] = exception.message
+        fields[:error_class] = exception.class.name
+        fields[:backtrace] = exception.backtrace&.first(10)
+      end
+
+      log(:info, message, **fields)
+    end
+
+    # Log warning message
+    #
+    # @param message [String] Log message
+    # @param exception [Exception, nil] Optional exception object
+    # @param fields [Hash] Additional fields
+    # @return [void]
+    def warn(message, exception = nil, **fields)
+      return unless should_log?(:warn)
+
+      if exception.is_a?(Exception)
+        fields[:error] = exception.message
+        fields[:error_class] = exception.class.name
+        fields[:backtrace] = exception.backtrace&.first(10)
+      end
+
+      log(:warn, message, **fields)
+    end
+
+    # Log error message
+    #
+    # @param message [String] Log message
+    # @param exception [Exception, nil] Optional exception object
+    # @param fields [Hash] Additional fields
+    # @return [void]
+    def error(message, exception = nil, **fields)
+      return unless should_log?(:error)
+
+      if exception.is_a?(Exception)
+        fields[:error] = exception.message
+        fields[:error_class] = exception.class.name
+        fields[:backtrace] = exception.backtrace&.first(10)
+      end
+
+      log(:error, message, **fields)
+    end
+
+    # Log fatal message
+    #
+    # @param message [String] Log message
+    # @param fields [Hash] Additional fields
+    # @return [void]
+    def fatal(message, **fields)
+      return unless should_log?(:fatal)
+
+      log(:fatal, message, **fields)
+    end
+
+    # Log an exception with full details
+    #
+    # @param exception [Exception] Exception to log
+    # @param message [String] Additional message
+    # @param fields [Hash] Additional fields
+    # @return [void]
+    def exception(exception, message: nil, **fields)
+      error(
+        message || exception.message,
+        exception: exception.class.name,
+        error_message: exception.message,
+        backtrace: exception.backtrace&.first(10),
+        **fields
+      )
+    end
+
+    private
+
+    # Check if log level should be logged
+    #
+    # @param log_level [Symbol] Level to check
+    # @return [Boolean]
+    def should_log?(log_level)
+      level_value = LOG_LEVELS[log_level]
+      return false if level_value < @level
+
+      # Apply sampling for debug logs if configured
+      if log_level == :debug && @sampling_rate
+        rand <= @sampling_rate
+      else
+        true
+      end
+    end
+
+    # Core logging method
+    #
+    # @param level [Symbol] Log level
+    # @param message [String] Log message
+    # @param fields [Hash] Additional fields
+    # @return [void]
+    def log(level, message, **fields)
+      log_entry = build_log_entry(level, message, fields)
+      @output.puts JSON.generate(log_entry)
+    rescue StandardError => e
+      # Fallback to basic output if JSON serialization fails
+      @output.puts "[LambdaLoadout::Logger] Error serializing log: #{e.message}"
+      @output.puts "Original message: #{message}"
+    end
+
+    # Build structured log entry
+    #
+    # @param level [Symbol] Log level
+    # @param message [String] Log message
+    # @param fields [Hash] Additional fields
+    # @return [Hash]
+    def build_log_entry(level, message, fields)
+      entry = {
+        'level' => level.to_s.upcase,
+        'timestamp' => Time.now.utc.strftime('%Y-%m-%dT%H:%M:%S.%3NZ'),
+        'message' => message
+      }
+
+      # Add persistent fields
+      entry.merge!(@persistent_fields)
+
+      # Add Lambda context if available
+      entry.merge!(lambda_context_fields) if @lambda_context
+
+      # Add custom fields
+      entry.merge!(stringify_keys(fields))
+
+      entry
+    end
+
+    # Extract fields from Lambda context
+    #
+    # @return [Hash]
+    def lambda_context_fields
+      {
+        'function_name' => @lambda_context.function_name,
+        'function_version' => @lambda_context.function_version,
+        'function_memory_size' => @lambda_context.memory_limit_in_mb,
+        'function_request_id' => @lambda_context.aws_request_id,
+        'cold_start' => LambdaLoadout.cold_start?
+      }.compact
+    rescue StandardError
+      {}
+    end
+
+    # Convert hash keys to strings
+    #
+    # @param hash [Hash] Hash with symbol or string keys
+    # @return [Hash] Hash with string keys
+    def stringify_keys(hash)
+      hash.transform_keys(&:to_s)
+    end
+  end
+end

data/lib/lambda_loadout/metrics.rb

@@ -0,0 +1,296 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'time'
+
+module LambdaLoadout
+  # CloudWatch Metrics using Embedded Metric Format (EMF)
+  #
+  # Creates custom metrics asynchronously by outputting metrics to stdout
+  # following Amazon CloudWatch Embedded Metric Format (EMF).
+  #
+  # @example Basic usage
+  #   metrics = LambdaLoadout::Metrics.new(namespace: "MyApp", service: "payment")
+  #   metrics.add_metric(name: "PaymentProcessed", unit: "Count", value: 1)
+  #   metrics.add_dimension(name: "region", value: "us-east-1")
+  #   metrics.flush
+  #
+  # @example With middleware
+  #   def lambda_handler(event:, context:)
+  #     metrics = LambdaLoadout::Metrics.new(namespace: "MyApp")
+  #
+  #     begin
+  #       metrics.add_metric(name: "RequestReceived", unit: "Count", value: 1)
+  #       # Your logic here
+  #     ensure
+  #       metrics.flush
+  #     end
+  #   end
+  class Metrics
+    # CloudWatch metric units
+    UNITS = %w[
+      Seconds Microseconds Milliseconds
+      Bytes Kilobytes Megabytes Gigabytes Terabytes
+      Bits Kilobits Megabits Gigabits Terabits
+      Percent Count
+      Bytes/Second Kilobytes/Second Megabytes/Second Gigabytes/Second Terabytes/Second
+      Bits/Second Kilobits/Second Megabits/Second Gigabits/Second Terabits/Second
+      Count/Second None
+    ].freeze
+
+    # Metric resolutions in seconds
+    RESOLUTIONS = [1, 60].freeze
+
+    MAX_DIMENSIONS = 29
+    MAX_METRICS = 100
+
+    attr_reader :namespace, :service, :output
+
+    # Initialize metrics
+    #
+    # @param namespace [String] CloudWatch metric namespace (required)
+    # @param service [String] Service name (added as default dimension)
+    # @param output [IO] Output stream for EMF (defaults to $stdout)
+    def initialize(namespace: nil, service: nil, output: $stdout)
+      @namespace = namespace || ENV.fetch('POWERTOOLS_METRICS_NAMESPACE', nil)
+      @service = service || ENV.fetch('POWERTOOLS_SERVICE_NAME', nil)
+      @output = output
+
+      raise ArgumentError, 'Namespace is required' if @namespace.nil? || @namespace.empty?
+
+      @metrics = {}
+      @dimensions = {}
+      @metadata = {}
+      @default_dimensions = {}
+      @timestamp = nil
+      @cold_start_captured = false
+
+      # Add service as default dimension if provided
+      add_dimension(name: 'service', value: @service) if @service
+    end
+
+    # Add a metric
+    #
+    # @param name [String] Metric name
+    # @param unit [String] Metric unit (must be valid CloudWatch unit)
+    # @param value [Numeric] Metric value
+    # @param resolution [Integer] Storage resolution in seconds (1 or 60)
+    # @return [void]
+    # @raise [ArgumentError] if parameters are invalid
+    def add_metric(name:, unit:, value:, resolution: 60)
+      validate_metric_name!(name)
+      validate_metric_unit!(unit)
+      validate_metric_value!(value)
+      validate_metric_resolution!(resolution)
+
+      # Auto-flush if we've hit the max metrics limit
+      flush_metrics if @metrics.size >= MAX_METRICS
+
+      metric_key = name.to_s
+      @metrics[metric_key] ||= { 'Unit' => unit.to_s, 'StorageResolution' => resolution, 'Values' => [] }
+      @metrics[metric_key]['Values'] << value.to_f
+    end
+
+    # Add a dimension to all metrics
+    #
+    # @param name [String] Dimension name
+    # @param value [String] Dimension value
+    # @return [void]
+    # @raise [ArgumentError] if max dimensions exceeded
+    def add_dimension(name:, value:)
+      raise ArgumentError, "Maximum number of dimensions (#{MAX_DIMENSIONS}) exceeded" if @dimensions.size >= MAX_DIMENSIONS
+
+      @dimensions[name.to_s] = value.to_s
+    end
+
+    # Add metadata (searchable in CloudWatch Logs but not as a metric dimension)
+    #
+    # @param key [String] Metadata key
+    # @param value [Object] Metadata value
+    # @return [void]
+    def add_metadata(key:, value:)
+      @metadata[key.to_s] = value
+    end
+
+    # Set default dimensions that persist across flushes
+    #
+    # @param dimensions [Hash] Default dimensions
+    # @return [void]
+    def set_default_dimensions(**dimensions)
+      @default_dimensions.merge!(dimensions.transform_keys(&:to_s))
+      @dimensions.merge!(@default_dimensions)
+    end
+
+    # Set custom timestamp for metrics
+    #
+    # @param timestamp [Time, Integer] Timestamp (Time object or epoch in milliseconds)
+    # @return [void]
+    def set_timestamp(timestamp)
+      @timestamp = case timestamp
+                   when Time
+                     (timestamp.to_f * 1000).to_i
+                   when Integer
+                     timestamp
+                   else
+                     raise ArgumentError, 'Timestamp must be Time object or Integer (epoch ms)'
+                   end
+
+      # Validate timestamp is within CloudWatch limits (14 days past, 2 hours future)
+      now = (Time.now.to_f * 1000).to_i
+      min_time = now - (14 * 24 * 60 * 60 * 1000)
+      max_time = now + (2 * 60 * 60 * 1000)
+
+      return unless @timestamp < min_time || @timestamp > max_time
+
+      warn '[LambdaLoadout::Metrics] Timestamp outside CloudWatch limits (14 days past, 2 hours future)'
+    end
+
+    # Add cold start metric
+    #
+    # @param context [Object] Lambda context
+    # @return [void]
+    def add_cold_start_metric(context)
+      return if @cold_start_captured
+      return unless LambdaLoadout.cold_start?
+
+      @cold_start_captured = true
+
+      # Create a separate EMF blob for cold start metric
+      cold_start_metrics = self.class.new(namespace: @namespace, output: @output)
+      cold_start_metrics.add_metric(name: 'ColdStart', unit: 'Count', value: 1)
+      cold_start_metrics.add_dimension(name: 'function_name', value: context.function_name)
+      cold_start_metrics.add_dimension(name: 'service', value: @service) if @service
+      cold_start_metrics.flush
+    rescue StandardError => e
+      warn "[LambdaLoadout::Metrics] Failed to add cold start metric: #{e.message}"
+    end
+
+    # Serialize and flush all metrics
+    #
+    # Outputs metrics in CloudWatch Embedded Metric Format (EMF) to stdout.
+    # Metrics are automatically ingested by CloudWatch when running in Lambda.
+    #
+    # @param raise_on_empty [Boolean] Raise error if no metrics to flush
+    # @return [void]
+    def flush(raise_on_empty: false)
+      if @metrics.empty?
+        warn '[LambdaLoadout::Metrics] No metrics to flush' unless raise_on_empty
+        raise 'No metrics to flush' if raise_on_empty
+
+        return
+      end
+
+      flush_metrics
+    end
+
+    # Clear all metrics, dimensions, and metadata
+    #
+    # @return [void]
+    def clear
+      @metrics.clear
+      @dimensions.clear
+      @metadata.clear
+      @dimensions.merge!(@default_dimensions)
+      @timestamp = nil
+    end
+
+    private
+
+    # Flush metrics to output in EMF format
+    #
+    # @return [void]
+    def flush_metrics
+      return if @metrics.empty?
+
+      emf_output = serialize_metrics
+      @output.puts JSON.generate(emf_output)
+
+      # Clear metrics but keep dimensions and metadata
+      @metrics.clear
+      @timestamp = nil
+    rescue StandardError => e
+      warn "[LambdaLoadout::Metrics] Failed to serialize metrics: #{e.message}"
+    end
+
+    # Serialize metrics to EMF format
+    #
+    # @return [Hash] EMF formatted metrics
+    def serialize_metrics
+      # Build metric definitions for EMF
+      metric_definitions = @metrics.map do |name, metric|
+        definition = {
+          'Name' => name,
+          'Unit' => metric['Unit']
+        }
+
+        # Add storage resolution for high-resolution metrics
+        definition['StorageResolution'] = metric['StorageResolution'] if metric['StorageResolution'] == 1
+
+        definition
+      end
+
+      # Build metric values
+      metric_values = @metrics.transform_values do |metric|
+        values = metric['Values']
+        values.size == 1 ? values.first : values
+      end
+
+      # Build EMF output
+      {
+        '_aws' => {
+          'Timestamp' => @timestamp || (Time.now.to_f * 1000).to_i,
+          'CloudWatchMetrics' => [
+            {
+              'Namespace' => @namespace,
+              'Dimensions' => [@dimensions.keys],
+              'Metrics' => metric_definitions
+            }
+          ]
+        }
+      }.merge(@dimensions)
+        .merge(@metadata)
+        .merge(metric_values)
+    end
+
+    # Validate metric name
+    #
+    # @param name [String] Metric name
+    # @raise [ArgumentError] if invalid
+    def validate_metric_name!(name)
+      name_str = name.to_s
+      return unless name_str.empty? || name_str.length > 255
+
+      raise ArgumentError, 'Metric name must be between 1 and 255 characters'
+    end
+
+    # Validate metric unit
+    #
+    # @param unit [String] Metric unit
+    # @raise [ArgumentError] if invalid
+    def validate_metric_unit!(unit)
+      return if UNITS.include?(unit.to_s)
+
+      raise ArgumentError, "Invalid metric unit: #{unit}. Must be one of: #{UNITS.join(', ')}"
+    end
+
+    # Validate metric value
+    #
+    # @param value [Numeric] Metric value
+    # @raise [ArgumentError] if invalid
+    def validate_metric_value!(value)
+      return if value.is_a?(Numeric)
+
+      raise ArgumentError, 'Metric value must be a number'
+    end
+
+    # Validate metric resolution
+    #
+    # @param resolution [Integer] Storage resolution
+    # @raise [ArgumentError] if invalid
+    def validate_metric_resolution!(resolution)
+      return if RESOLUTIONS.include?(resolution)
+
+      raise ArgumentError, "Invalid resolution: #{resolution}. Must be 1 or 60 seconds"
+    end
+  end
+end

data/lib/lambda_loadout/middleware.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+module LambdaLoadout
+  # Middleware for Ruby Lambda handlers
+  #
+  # Provides a clean way to wrap Lambda handlers with logging, metrics,
+  # and error handling without repetitive boilerplate code.
+  #
+  # @example Using as a wrapper
+  #   class MyHandler
+  #     include LambdaLoadout::Middleware
+  #
+  #     def initialize
+  #       @logger = LambdaLoadout::Logger.new(service: "payment")
+  #       @metrics = LambdaLoadout::Metrics.new(namespace: "MyApp", service: "payment")
+  #     end
+  #
+  #     def call(event:, context:)
+  #       with_observability(context) do
+  #         @logger.info("Processing payment", event: event)
+  #         @metrics.add_metric(name: "PaymentProcessed", unit: "Count", value: 1)
+  #
+  #         { statusCode: 200, body: "Success" }
+  #       end
+  #     end
+  #   end
+  module Middleware
+    # Execute block with full observability stack
+    #
+    # Automatically:
+    # - Injects Lambda context into logger
+    # - Captures cold start metric
+    # - Flushes metrics after execution
+    # - Handles errors with proper logging and metrics
+    #
+    # @param context [Object] Lambda context
+    # @param capture_cold_start [Boolean] Whether to capture cold start
+    # @param logger [LambdaLoadout::Logger] Logger instance (uses @logger if not provided)
+    # @param metrics [LambdaLoadout::Metrics] Metrics instance (uses @metrics if not provided)
+    # @yield Block containing handler logic
+    # @return [Object] Result of block execution
+    def with_observability(context, capture_cold_start: true, logger: nil, metrics: nil, &block)
+      logger ||= @logger
+      metrics ||= @metrics
+
+      logger&.inject_lambda_context(context)
+
+      begin
+        result = block.call
+        metrics&.add_cold_start_metric(context) if capture_cold_start
+        result
+      rescue StandardError => e
+        logger&.exception(e, message: 'Lambda execution failed')
+        metrics&.add_metric(name: 'LambdaError', unit: 'Count', value: 1)
+        raise
+      ensure
+        begin
+          metrics&.flush
+        rescue StandardError
+          nil
+        end
+      end
+    end
+  end
+
+  # Decorator-style wrapper for Lambda handlers
+  #
+  # Provides a simple DSL for wrapping Lambda handlers with observability.
+  #
+  # @example Basic usage
+  #   LambdaLoadout::Handler.configure do |config|
+  #     config.service = "payment"
+  #     config.namespace = "MyApp"
+  #   end
+  #
+  #   def lambda_handler(event:, context:)
+  #     LambdaLoadout::Handler.call(event, context) do |logger, metrics|
+  #       logger.info("Processing event")
+  #       metrics.add_metric(name: "EventProcessed", unit: "Count", value: 1)
+  #
+  #       { statusCode: 200 }
+  #     end
+  #   end
+  class Handler
+    class << self
+      attr_accessor :service, :namespace, :log_level, :capture_cold_start
+
+      # Configure global handler defaults
+      #
+      # @yield [self] Configuration block
+      # @return [void]
+      def configure
+        yield self
+      end
+
+      # Call handler with observability
+      #
+      # @param event [Hash] Lambda event
+      # @param context [Object] Lambda context
+      # @param capture_cold_start [Boolean] Override cold start capture
+      # @yield [logger, metrics] Block with logger and metrics instances
+      # @return [Object] Result of block execution
+      def call(event, context, capture_cold_start: @capture_cold_start || true, &block)
+        logger = LambdaLoadout::Logger.new(
+          service: @service,
+          level: @log_level || :info
+        )
+
+        metrics = LambdaLoadout::Metrics.new(
+          namespace: @namespace || 'LambdaLoadout',
+          service: @service
+        )
+
+        logger.inject_lambda_context(context)
+        logger.info('Lambda invocation started', event_keys: event.keys)
+
+        begin
+          result = block.call(logger, metrics)
+          metrics.add_cold_start_metric(context) if capture_cold_start
+          logger.info('Lambda invocation completed successfully')
+          result
+        rescue StandardError => e
+          logger.exception(e, message: 'Lambda invocation failed')
+          metrics.add_metric(name: 'LambdaError', unit: 'Count', value: 1)
+          metrics.add_dimension(name: 'error_type', value: e.class.name)
+          raise
+        ensure
+          begin
+            metrics.flush
+          rescue StandardError
+            nil
+          end
+        end
+      end
+    end
+  end
+end

data/lib/lambda_loadout/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module LambdaLoadout
+  VERSION = '0.0.1'
+end