lambda_loadout 0.0.1

data/lib/lambda_loadout/error_notifier.rb

@@ -0,0 +1,248 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'cgi'
+require 'time'
+
+module LambdaLoadout
+  # ErrorNotifier sends detailed error notifications via SNS when Lambda functions fail
+  #
+  # @example Basic usage
+  #   notifier = LambdaLoadout::ErrorNotifier.new(
+  #     sns_topic_arn: ENV['ERROR_NOTIFICATION_TOPIC_ARN'],
+  #     logger: logger
+  #   )
+  #   notifier.notify(error: exception, context: context, event: event)
+  #
+  # @example With custom region
+  #   notifier = LambdaLoadout::ErrorNotifier.new(
+  #     sns_topic_arn: 'arn:aws:sns:us-west-2:123456789012:alerts',
+  #     logger: logger,
+  #     region: 'us-west-2'
+  #   )
+  class ErrorNotifier
+    attr_reader :sns_topic_arn, :logger, :region
+
+    # Initialize ErrorNotifier
+    #
+    # @param sns_topic_arn [String] ARN of SNS topic for error notifications
+    # @param logger [LambdaLoadout::Logger] Logger instance for logging notification status
+    # @param region [String, nil] AWS region (defaults to AWS_REGION env var or us-east-1)
+    def initialize(sns_topic_arn:, logger:, region: nil)
+      @sns_topic_arn = sns_topic_arn
+      @logger = logger
+      @region = region || ENV['AWS_REGION'] || 'us-east-1'
+      @sns_client = nil # Lazy initialize
+    end
+
+    # Send error notification via SNS
+    #
+    # @param error [Exception] The exception that occurred
+    # @param context [LambdaContext] AWS Lambda context object
+    # @param event [Hash] Lambda event hash
+    # @return [void]
+    def notify(error:, context:, event:)
+      return if sns_topic_arn.nil? || sns_topic_arn.empty?
+
+      begin
+        ensure_sns_client
+
+        subject = build_subject(error, context)
+        message = build_message(error, context, event)
+
+        @sns_client.publish(
+          topic_arn: sns_topic_arn,
+          subject: subject,
+          message: message
+        )
+
+        logger.info('Error notification sent',
+                    topic_arn: sns_topic_arn,
+                    error_class: error.class.name)
+      rescue StandardError => e
+        # Don't let notification errors prevent the original error from being raised
+        logger.warn('Failed to send error notification', e,
+                    topic_arn: sns_topic_arn,
+                    original_error: error.class.name)
+      end
+    end
+
+    private
+
+    # Lazy initialize SNS client
+    def ensure_sns_client
+      @ensure_sns_client ||= begin
+        require 'aws-sdk-sns'
+        Aws::SNS::Client.new(region: region)
+      end
+    end
+
+    # Build email subject line
+    def build_subject(error, context)
+      "🚨 Lambda Error: #{error.class.name} in #{context.function_name}"
+    end
+
+    # Build detailed email message body
+    def build_message(error, context, event)
+      <<~MESSAGE
+        🚨 Lambda Function Error Alert
+
+        📋 Function Details
+        ══════════════════
+        Name: #{context.function_name}
+        Environment: #{ENV['ENVIRONMENT'] || ENV['STAGE'] || 'unknown'}
+        Request ID: #{context.aws_request_id}
+        Region: #{region}
+        Timestamp: #{Time.now.utc.strftime('%Y-%m-%d %H:%M:%S UTC')}
+        Memory Limit: #{context.memory_limit_in_mb}MB
+        Remaining Time: #{context.get_remaining_time_in_millis}ms
+
+        ❌ Error Details
+        ════════════════
+        Type: #{error.class.name}
+        Message: #{truncate_message(error.message)}
+
+        🌐 Request Context
+        ══════════════════
+        #{format_request_context(event)}
+
+        📚 Stack Trace (first 15 lines)
+        ═══════════════════════════════
+        #{format_backtrace(error)}
+
+        🔍 View Full Logs
+        ═════════════════
+
+        CloudWatch Logs Insights (filtered to this error):
+        #{build_logs_insights_url(context, error)}
+
+        CloudWatch Recent Logs:
+        #{build_logs_stream_url(context)}
+
+        📊 JSON Data
+        ════════════
+        #{format_error_json(error, context, event)}
+      MESSAGE
+    end
+
+    # Truncate very long error messages
+    def truncate_message(message, max_length = 500)
+      return message if message.length <= max_length
+
+      "#{message[0...max_length]}... (truncated, #{message.length} chars total)"
+    end
+
+    # Format request context based on event type
+    def format_request_context(event)
+      if event['httpMethod'] # API Gateway
+        <<~CONTEXT.strip
+          Path: #{event['path'] || 'N/A'}
+          Method: #{event['httpMethod']}
+          Source IP: #{event.dig('requestContext', 'identity', 'sourceIp') || 'N/A'}
+          User Agent: #{event.dig('headers', 'User-Agent') || event.dig('headers', 'user-agent') || 'N/A'}
+        CONTEXT
+      elsif event['Records'] # SQS, SNS, DynamoDB Streams, etc.
+        first_record = event['Records'].first || {}
+        event_source = first_record['eventSource'] || 'Unknown'
+        <<~CONTEXT.strip
+          Event Source: #{event_source}
+          Records Count: #{event['Records'].size}
+          First Record ID: #{first_record['messageId'] || first_record['eventID'] || 'N/A'}
+        CONTEXT
+      elsif event['source'] # EventBridge
+        <<~CONTEXT.strip
+          Event Source: #{event['source']}
+          Detail Type: #{event['detail-type'] || 'N/A'}
+          Resources: #{event['resources']&.join(', ') || 'N/A'}
+        CONTEXT
+      else # Unknown event type
+        "Event Type: Unknown\nEvent Keys: #{event.keys.sort.join(', ')}"
+      end
+    end
+
+    # Format exception backtrace
+    def format_backtrace(error)
+      backtrace = error.backtrace || []
+      if backtrace.empty?
+        'No backtrace available'
+      else
+        backtrace.first(15).join("\n")
+      end
+    end
+
+    # Build CloudWatch Logs Insights deep link with pre-filled query
+    # Note: This URL format is specific to the AWS Console as of 2025
+    # If AWS changes the console URL structure, this may need updates
+    def build_logs_insights_url(context, error)
+      log_group = "/aws/lambda/#{context.function_name}"
+
+      # Use current time minus 5 minutes to capture the error
+      start_time = (Time.now - 300).to_i * 1000 # milliseconds
+      end_time = Time.now.to_i * 1000
+
+      # CloudWatch Logs Insights query to find this specific error
+      error_class_escaped = Regexp.escape(error.class.name)
+      query = "fields @timestamp, @message | filter @message like /#{error_class_escaped}/ | sort @timestamp desc | limit 20"
+
+      # URL encode the query and log group
+      encoded_query = CGI.escape(query)
+      encoded_log_group = CGI.escape(log_group)
+
+      # Deep link to CloudWatch Logs Insights with pre-filled query
+      # Format: AWS Console uses a specific encoding scheme for Logs Insights URLs
+      "https://console.aws.amazon.com/cloudwatch/home?region=#{region}#logsV2:logs-insights$3FqueryDetail$3D~(end~#{end_time}~start~#{start_time}~timeType~'ABSOLUTE~tz~'UTC~editorString~'#{encoded_query}~isLiveTail~false~source~(~'#{encoded_log_group}))"
+    end
+
+    # Build CloudWatch Logs stream deep link
+    def build_logs_stream_url(context)
+      # CloudWatch uses special encoding for forward slashes in URLs
+      encoded_log_group = "/aws/lambda/#{CGI.escape(context.function_name)}".gsub('/', '$252F')
+
+      "https://console.aws.amazon.com/cloudwatch/home?region=#{region}#logsV2:log-groups/log-group/#{encoded_log_group}/log-events"
+    end
+
+    # Format error details as JSON
+    def format_error_json(error, context, event)
+      error_data = {
+        function: context.function_name,
+        request_id: context.aws_request_id,
+        error_class: error.class.name,
+        error_message: error.message,
+        timestamp: Time.now.utc.iso8601,
+        backtrace: error.backtrace&.first(15) || [],
+        event_summary: build_event_summary(event)
+      }
+
+      JSON.pretty_generate(error_data)
+    rescue StandardError => e
+      # Fallback if JSON formatting fails
+      "{\"error\": \"Failed to format error data as JSON: #{e.message}\"}"
+    end
+
+    # Build compact event summary for JSON output
+    def build_event_summary(event)
+      if event['httpMethod']
+        {
+          type: 'API Gateway',
+          path: event['path'],
+          method: event['httpMethod']
+        }
+      elsif event['Records']
+        {
+          type: event['Records'].first&.dig('eventSource') || 'Records',
+          count: event['Records'].size
+        }
+      elsif event['source']
+        {
+          type: 'EventBridge',
+          source: event['source']
+        }
+      else
+        {
+          type: 'Unknown',
+          keys: event.keys.sort
+        }
+      end
+    end
+  end
+end

data/lib/lambda_loadout/errors.rb

@@ -0,0 +1,218 @@
+# frozen_string_literal: true
+
+module LambdaLoadout
+  # Custom error classes
+  module Errors
+    # Base error for all LambdaLoadout errors
+    class Error < StandardError; end
+
+    # Raised when metric validation fails
+    class MetricValidationError < Error; end
+
+    # Raised when EMF schema validation fails
+    class SchemaValidationError < Error; end
+
+    # Raised when configuration is invalid
+    class ConfigurationError < Error; end
+  end
+
+  # Error handler for Lambda functions
+  #
+  # Automatically captures exceptions, logs them, and creates error metrics.
+  #
+  # @example Basic usage
+  #   handler = LambdaLoadout::ErrorHandler.new(
+  #     logger: logger,
+  #     metrics: metrics,
+  #     capture_stack_trace: true
+  #   )
+  #
+  #   def lambda_handler(event:, context:)
+  #     handler.handle(context) do
+  #       # Your code that might raise errors
+  #       process_event(event)
+  #     end
+  #   end
+  class ErrorHandler
+    attr_reader :logger, :metrics
+
+    # Initialize error handler
+    #
+    # @param logger [LambdaLoadout::Logger] Logger instance
+    # @param metrics [LambdaLoadout::Metrics] Metrics instance
+    # @param capture_stack_trace [Boolean] Whether to include stack trace in logs
+    # @param error_metric_name [String] Name of error metric (default: "LambdaError")
+    def initialize(logger: nil, metrics: nil, capture_stack_trace: true, error_metric_name: 'LambdaError')
+      @logger = logger
+      @metrics = metrics
+      @capture_stack_trace = capture_stack_trace
+      @error_metric_name = error_metric_name
+    end
+
+    # Handle block execution with error capturing
+    #
+    # @param context [Object] Lambda context
+    # @yield Block to execute
+    # @return [Object] Result of block execution
+    # @raise Re-raises the original exception after logging and metrics
+    def handle(context = nil, &block)
+      block.call
+    rescue StandardError => e
+      capture_error(e, context)
+      raise
+    end
+
+    # Capture and log an error
+    #
+    # @param error [Exception] Exception to capture
+    # @param context [Object] Lambda context
+    # @param custom_fields [Hash] Additional fields to log
+    # @return [void]
+    def capture_error(error, context = nil, **custom_fields)
+      error_details = {
+        error_type: error.class.name,
+        error_message: error.message
+      }
+
+      error_details[:stack_trace] = error.backtrace&.first(20) if @capture_stack_trace
+
+      if context
+        error_details[:function_name] = context.function_name
+        error_details[:request_id] = context.aws_request_id
+      end
+
+      error_details.merge!(custom_fields)
+
+      # Log error
+      @logger&.error('Lambda execution error', **error_details)
+
+      # Add error metric
+      return unless @metrics
+
+      @metrics.add_metric(name: @error_metric_name, unit: 'Count', value: 1)
+      @metrics.add_dimension(name: 'error_type', value: error.class.name)
+    end
+  end
+
+  # Alarm configuration helper
+  #
+  # Helps define CloudWatch Alarms for metrics created via EMF.
+  # Note: This generates CloudFormation/SAM template snippets, actual alarm
+  # creation should be done via IaC (CloudFormation, Terraform, etc.)
+  #
+  # @example Generate alarm configuration
+  #   alarm = LambdaLoadout::AlarmConfig.new(
+  #     metric_name: "LambdaError",
+  #     namespace: "MyApp",
+  #     threshold: 1,
+  #     evaluation_periods: 1
+  #   )
+  #
+  #   puts alarm.to_cloudformation
+  class AlarmConfig
+    attr_reader :metric_name, :namespace, :threshold, :statistic,
+                :evaluation_periods, :period, :comparison_operator
+
+    # Initialize alarm configuration
+    #
+    # @param metric_name [String] CloudWatch metric name
+    # @param namespace [String] CloudWatch metric namespace
+    # @param threshold [Numeric] Alarm threshold
+    # @param statistic [String] Statistic type (Sum, Average, Maximum, etc.)
+    # @param evaluation_periods [Integer] Number of periods to evaluate
+    # @param period [Integer] Period in seconds
+    # @param comparison_operator [String] Comparison operator
+    def initialize(
+      metric_name:,
+      namespace:,
+      threshold: 1,
+      statistic: 'Sum',
+      evaluation_periods: 1,
+      period: 60,
+      comparison_operator: 'GreaterThanOrEqualToThreshold'
+    )
+      @metric_name = metric_name
+      @namespace = namespace
+      @threshold = threshold
+      @statistic = statistic
+      @evaluation_periods = evaluation_periods
+      @period = period
+      @comparison_operator = comparison_operator
+    end
+
+    # Generate CloudFormation YAML for alarm
+    #
+    # @param alarm_name [String] CloudFormation logical name
+    # @param sns_topic_arn [String] SNS topic ARN for notifications (optional)
+    # @param dimensions [Hash] Metric dimensions
+    # @return [String] CloudFormation YAML snippet
+    def to_cloudformation(alarm_name: "#{metric_name}Alarm", sns_topic_arn: nil, dimensions: {})
+      cf = {
+        alarm_name => {
+          'Type' => 'AWS::CloudWatch::Alarm',
+          'Properties' => {
+            'AlarmName' => alarm_name,
+            'AlarmDescription' => "Alarm for #{metric_name} in #{namespace}",
+            'MetricName' => metric_name,
+            'Namespace' => namespace,
+            'Statistic' => statistic,
+            'Period' => period,
+            'EvaluationPeriods' => evaluation_periods,
+            'Threshold' => threshold,
+            'ComparisonOperator' => comparison_operator,
+            'TreatMissingData' => 'notBreaching'
+          }
+        }
+      }
+
+      # Add dimensions if provided
+      unless dimensions.empty?
+        dims = dimensions.map { |k, v| { 'Name' => k.to_s, 'Value' => v.to_s } }
+        cf[alarm_name]['Properties']['Dimensions'] = dims
+      end
+
+      # Add SNS notification if provided
+      cf[alarm_name]['Properties']['AlarmActions'] = [sns_topic_arn] if sns_topic_arn
+
+      require 'yaml'
+      YAML.dump(cf)
+    end
+
+    # Generate Terraform HCL for alarm
+    #
+    # @param resource_name [String] Terraform resource name
+    # @param sns_topic_arn [String] SNS topic ARN for notifications (optional)
+    # @param dimensions [Hash] Metric dimensions
+    # @return [String] Terraform HCL snippet
+    def to_terraform(resource_name: metric_name.downcase, sns_topic_arn: nil, dimensions: {})
+      hcl = <<~HCL
+        resource "aws_cloudwatch_metric_alarm" "#{resource_name}" {
+          alarm_name          = "#{resource_name}"
+          alarm_description   = "Alarm for #{metric_name} in #{namespace}"
+          comparison_operator = "#{comparison_operator}"
+          evaluation_periods  = #{evaluation_periods}
+          metric_name         = "#{metric_name}"
+          namespace           = "#{namespace}"
+          period              = #{period}
+          statistic           = "#{statistic}"
+          threshold           = #{threshold}
+          treat_missing_data  = "notBreaching"
+      HCL
+
+      # Add dimensions if provided
+      unless dimensions.empty?
+        hcl += "\n  dimensions = {\n"
+        dimensions.each do |k, v|
+          hcl += "    #{k} = \"#{v}\"\n"
+        end
+        hcl += "  }\n"
+      end
+
+      # Add SNS notification if provided
+      hcl += "\n  alarm_actions = [\"#{sns_topic_arn}\"]\n" if sns_topic_arn
+
+      hcl += "}\n"
+      hcl
+    end
+  end
+end

data/lib/lambda_loadout/global.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module LambdaLoadout
+  # Module-level convenience methods for quick access
+  #
+  # Provides a simple API similar to common logging modules:
+  #   LambdaLoadout.logger.info("message")
+  #   LambdaLoadout.metrics.add_metric(...)
+  #
+  # @example Module-level usage
+  #   LambdaLoadout.configure do |config|
+  #     config.service = "my-service"
+  #     config.namespace = "MyApp"
+  #   end
+  #
+  #   LambdaLoadout.logger.info("Processing request")
+  #   LambdaLoadout.metrics.add_metric(name: "Request", unit: "Count", value: 1)
+  module Global
+    class << self
+      attr_writer :logger, :metrics
+
+      # Configuration
+      attr_accessor :service, :namespace, :log_level
+
+      # Get or create the global logger instance
+      #
+      # @return [LambdaLoadout::Logger]
+      def logger
+        @logger ||= LambdaLoadout::Logger.new(
+          service: service || ENV.fetch('POWERTOOLS_SERVICE_NAME', nil),
+          level: log_level || :info
+        )
+      end
+
+      # Get or create the global metrics instance
+      #
+      # @return [LambdaLoadout::Metrics]
+      def metrics
+        @metrics ||= LambdaLoadout::Metrics.new(
+          namespace: namespace || ENV['POWERTOOLS_METRICS_NAMESPACE'] || 'LambdaLoadout',
+          service: service || ENV.fetch('POWERTOOLS_SERVICE_NAME', nil)
+        )
+      end
+
+      # Reset global instances (useful for testing)
+      #
+      # @return [void]
+      def reset!
+        @logger = nil
+        @metrics = nil
+      end
+    end
+  end
+
+  # Configure LambdaLoadout globally
+  #
+  # @yield [Global] Configuration block
+  # @return [void]
+  #
+  # @example
+  #   LambdaLoadout.configure do |config|
+  #     config.service = "payment-api"
+  #     config.namespace = "MyApp"
+  #     config.log_level = :debug
+  #   end
+  def self.configure
+    yield Global
+  end
+
+  # Access global logger
+  #
+  # @return [LambdaLoadout::Logger]
+  def self.logger
+    Global.logger
+  end
+
+  # Access global metrics
+  #
+  # @return [LambdaLoadout::Metrics]
+  def self.metrics
+    Global.metrics
+  end
+end