Download Complete Guide

What is AWS SAM?

AWS Serverless Application Model (SAM) is an open-source framework for building serverless applications. It provides:

• Simplified YAML syntax for defining serverless resources
• CLI tool for local testing and debugging
• Built-in best practices for deployment
• Seamless integration with AWS CloudFormation

Learn more in our beginner’s guide to AWS SAM.

Local Debugging with SAM CLI

Debugging Lambda functions locally accelerates development and reduces deployment cycles.

Step 1: Install SAM CLI

# For macOS using Homebrew
brew tap aws/tap
brew install aws-sam-cli

# Verify installation
sam --version

Step 2: Initialize Debug Session

sam build --debug
sam local invoke -d 5858 MyFunction

{
  "type": "aws-sam",
  "request": "direct-invoke",
  "name": "Debug Lambda",
  "invokeTarget": {
    "target": "code",
    "projectRoot": "${workspaceFolder}"
  },
  "lambda": {
    "runtime": "python3.9",
    "handler": "app.lambda_handler"
  }
}

Cloud Debugging Techniques

When local testing isn’t enough, debug deployed functions using these methods:

1. CloudWatch Logs Integration

# Tail logs in real-time
sam logs -n MyFunction --tail

2. Remote Debugging

Attach debugger to live Lambda using AWS Toolkits:

1. Add aws_sam debug configuration
2. Set breakpoints in your code
3. Run sam sync --watch --debug
4. Invoke function to trigger debugger

3. X-Ray Tracing

Enable in template.yaml:

Resources:
  MyFunction:
    Type: AWS::Serverless::Function
    Properties:
      Tracing: Active

View traces in AWS X-Ray console to identify bottlenecks.

Common Debugging Scenarios

Timeout Errors

Troubleshooting steps:

1. Check configured timeout value
2. Monitor memory usage in CloudWatch
3. Add logging before external calls
4. Use context.getRemainingTimeInMillis()

Permission Issues

Resolve with:

# Check execution role
aws lambda get-function-configuration --function-name MyFunction

# Test permissions with:
sam local invoke --event event.json

Cold Start Problems

Mitigation strategies:

• Reduce deployment package size
• Use Provisioned Concurrency
• Initialize connections outside handler
• Use Lambda SnapStart for Java

Learn more about cold start optimization.

Advanced Debugging Techniques

1. Step Functions Local Testing

sam local start-step-function --template template.yaml

2. Container Image Support

Debug Lambda container images locally:

sam local invoke -t template.yaml --debug-port 5858 
  --docker-network host MyFunction

3. Custom Debugging Containers

Create Dockerfile.debug:

FROM public.ecr.aws/lambda/python:3.9

# Install debugging tools
RUN yum install -y gdb

# Install debugpy
RUN pip install debugpy

Reference in template.yaml:

Properties:
  ImageUri: myfunction:debug
  ImageConfig:
    Command: ["/var/lang/bin/python", "-m", "debugpy", ...]

Debugging Best Practices

• ✅ Use structured JSON logging
• ✅ Implement correlation IDs for tracing
• ✅ Test with production-like event payloads
• ✅ Set up log aggregation
• ✅ Create reusable debug configurations
• ❌ Avoid committing debug code to production
• ❌ Don’t disable timeout during debugging

DEBUG_MODE = os.environ.get('DEBUG', 'false') == 'true'

if DEBUG_MODE:
    import debugpy
    debugpy.listen(("0.0.0.0", 5858))
    debugpy.wait_for_client()

Mastering Lambda Debugging

Effective debugging with SAM CLI transforms your serverless development experience. By combining local debugging techniques with cloud monitoring tools, you can:

1. Reduce debugging time by up to 70%
2. Catch errors before deployment
3. Understand complex execution flows
4. Optimize performance proactively

Continue your serverless journey with our guide to testing applications locally with SAM.

Download Full Guide