Module: LambdaLoadout

Defined in:
lib/lambda_loadout.rb,
lib/lambda_loadout/errors.rb,
lib/lambda_loadout/global.rb,
lib/lambda_loadout/logger.rb,
lib/lambda_loadout/metrics.rb,
lib/lambda_loadout/version.rb,
lib/lambda_loadout/middleware.rb,
lib/lambda_loadout/error_notifier.rb

Overview

LambdaLoadout - AWS Lambda Powertools for Ruby

A Ruby implementation of AWS Lambda Powertools providing:

  • Structured logging with Lambda context enrichment

  • CloudWatch Metrics via Embedded Metric Format (EMF)

  • Automatic error tracking and alerting

  • Lambda middleware for easy integration

Examples:

Basic usage

require 'lambda_loadout'

logger = LambdaLoadout::Logger.new(service: "payment")
metrics = LambdaLoadout::Metrics.new(namespace: "MyApp", service: "payment")

def lambda_handler(event:, context:)
  LambdaLoadout.with_logging_and_metrics(logger, metrics, context) do
    logger.info("Processing payment")
    metrics.add_metric(name: "PaymentProcessed", unit: "Count", value: 1)

    { statusCode: 200, body: "Success" }
  end
end

Defined Under Namespace

Modules: Errors, Global, Middleware Classes: AlarmConfig, Error, ErrorHandler, ErrorNotifier, Handler, Logger, Metrics

Constant Summary collapse

VERSION = 
'0.0.1'

Class Method Summary collapse

Class Method Details

.cold_start? ⇒ Boolean

Get cold start status

Returns:

  • (Boolean) —

    true if this is a cold start



95
96
97
98
99
100
 
# File 'lib/lambda_loadout.rb', line 95

def self.cold_start?
  @cold_start ||= true
  current_cold_start = @cold_start
  @cold_start = false
  current_cold_start
end

.configure {|Global| ... } ⇒ void

This method returns an undefined value.

Configure LambdaLoadout globally

Examples:

LambdaLoadout.configure do |config|
  config.service = "payment-api"
  config.namespace = "MyApp"
  config.log_level = :debug
end

Yields:

  • (Global) —

    Configuration block



66
67
68
 
# File 'lib/lambda_loadout/global.rb', line 66

def self.configure
  yield Global
end

.in_lambda? ⇒ Boolean

Check if running in AWS Lambda environment

Returns:

  • (Boolean) —

    true if running in Lambda



88
89
90
 
# File 'lib/lambda_loadout.rb', line 88

def self.in_lambda?
  !ENV['AWS_LAMBDA_FUNCTION_NAME'].nil?
end

.logger ⇒ LambdaLoadout::Logger

Access global logger

Returns:



73
74
75
 
# File 'lib/lambda_loadout/global.rb', line 73

def self.logger
  Global.logger
end

.metrics ⇒ LambdaLoadout::Metrics

Access global metrics

Returns:



80
81
82
 
# File 'lib/lambda_loadout/global.rb', line 80

def self.metrics
  Global.metrics
end

.with_logging_and_metrics(logger, metrics, context, event: nil, capture_cold_start: true, error_notification_config: nil) { ... } ⇒ Object

Helper method to wrap Lambda handler with logging and metrics

Examples:

With error notifications

LambdaLoadout.with_logging_and_metrics(
  logger, metrics, context, event: event,
  error_notification_config: { sns_topic_arn: ENV['ERROR_NOTIFICATION_TOPIC_ARN'] }
) do
  # Your Lambda code here
end

Parameters:

  • logger (LambdaLoadout::Logger) —

    Logger instance

  • metrics (LambdaLoadout::Metrics) —

    Metrics instance

  • context (Object) —

    Lambda context

  • event (Hash) (defaults to: nil) —

    Lambda event (optional, required for error notifications)

  • capture_cold_start (Boolean) (defaults to: true) —

    Whether to capture cold start metric

  • error_notification_config (Hash, nil) (defaults to: nil) —

    Error notification configuration

    • :sns_topic_arn [String] SNS topic ARN for error notifications

    • :region [String] AWS region (optional, defaults to AWS_REGION env var)

Yields:

  • Block containing Lambda handler logic

Returns:

  • (Object) —

    Result of the block



56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
 
# File 'lib/lambda_loadout.rb', line 56

def self.with_logging_and_metrics(logger, metrics, context, event: nil, capture_cold_start: true,
                                  error_notification_config: nil, &block)
  logger.inject_lambda_context(context)

  begin
    result = block.call
    metrics.add_cold_start_metric(context) if capture_cold_start
    result
  rescue StandardError => e
    logger.error('Lambda execution failed', e)
    metrics.add_metric(name: 'LambdaError', unit: 'Count', value: 1)

    # Send error notification if configured
    if error_notification_config && error_notification_config[:sns_topic_arn]
      notifier = ErrorNotifier.new(
        sns_topic_arn: error_notification_config[:sns_topic_arn],
        logger: logger,
        region: error_notification_config[:region]
      )

      notifier.notify(error: e, context: context, event: event || {})
    end

    raise
  ensure
    metrics.flush
  end
end