Skip to content

Conversation

roger-zhangg
Copy link
Member

Problem

The AWS SAM CLI file watcher was experiencing infinite loops during local development, particularly with LoopBack applications that create temporary .sandbox directories. This caused:

  • Extremely slow local invoke startup times (8+ minutes in some cases)
  • High CPU usage from continuous file system events
  • Poor developer experience during local development

Solution

This PR implements two key improvements:

1. Configurable Ignore Patterns for File Watching

  • Added centralized ignore patterns to prevent infinite loops from temporary files and directories
  • Environment variable control via SAM_CLI_FILE_OBSERVER_IGNORE_PATTERNS (default: enabled)
  • Smart filtering that ignores internal package changes but still detects new packages

Default ignore patterns:

*/node_modules/*/*    # Ignore changes within packages, but allow new packages
*.tmp                 # Ignore temporary files  
*.temp                # Ignore temporary files
*/.git/*              # Ignore git directories
*/__pycache__/*       # Ignore Python cache
*.pyc                 # Ignore Python compiled files
*.log                 # Ignore log files

2. Enhanced Lock Acquisition Logging

  • More specific debug messages showing what resources are being processed
  • Function and resource context in lock acquisition logs
  • Better debugging experience for file watcher issues

Usage

Default behavior (recommended):

sam local start-api

Disable ignore patterns for debugging:

SAM_USE_IGNORE_PATTERN =false sam local start-api

Windows Installation Instructions

For Windows users experiencing file watcher performance issues:

  1. Install from source (recommended for testing):

    git clone https://github.com/aws/aws-sam-cli.git
    cd aws-sam-cli

make init

./Make -Init


2. __Or install specific branch__ (if available):

```cmd
pip install git+https://github.com/aws/aws-sam-cli.git@hot-swap-fix
  1. Verify the fix is working:

    # Should show improved logging and faster startup
    sam local start-api --debug
  2. Environment variable usage in Windows:

    # PowerShell
    $env: SAM_USE_IGNORE_PATTERN ="true"
    sam local start-api
    
    # Command Prompt
    set SAM_USE_IGNORE_PATTERN =true
    sam local start-api

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

@roger-zhangg roger-zhangg requested a review from a team as a code owner July 30, 2025 01:58
"""

# Ignore patterns for file watching to avoid infinite loops and unnecessary events
DEFAULT_IGNORE_PATTERNS = [
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we provide a way for customer to provide customize ignore pattern? If none is provided, we can use the DEFAULT_IGNORE_PATTERNS.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes this should be the idea when we ship it. I will use this version to debug with customer first

@vicheey
Copy link
Contributor

vicheey commented Sep 9, 2025

DO NOT MERGE.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants