Remote Debugging

    This guide covers the remote debugging of Lambda functions with Visual Studio Code or IntelliJ IDEA as an IDE. For a simple working example of this feature, check out .

    More examples and tooling support for local Lambda debugging (including support for other IDEs like PyCharm) is coming soon - stay tuned!

    Lambda functions debugging used to be a difficult task. LocalStack changes that with the same local code mounting functionality that also helps you to .

    For a simple working example of this feature, you can refer to our samples. There, the necessary code fragments for enabling debugging are already present.

    Configure LocalStack for remote Python debugging

    First, make sure that LocalStack is started with the following configuration (see the Configuration docs for more information):

    Preparing your code

    For providing the debug server, we use debugpy inside the Lambda function code. In general, all you need is the following code fragment placed inside your handler code:

    2. debugpy.listen(19891)
    3. debugpy.wait_for_client()  # blocks execution until client is attached

    For extra convenience, you can use the wait_for_debug_client function from our example. It implements the above-mentioned start of the debug server and also adds an automatic cancellation of the wait task if the debug client (i.e. VSCode) doesn’t connect.

    1. def wait_for_debug_client(timeout=15):
    2.     """Utility function to enable debugging with Visual Studio Code"""
    3.     import time, threading
    4.     import sys, glob
    5.     sys.path.append(glob.glob(".venv/lib/python*/site-packages")[0])
    7.     debugpy.listen(("0.0.0.0", 19891))
    8.     class T(threading.Thread):
    9.         daemon = True
    10.         def run(self):
    11.             time.sleep(timeout)
    12.             print("Canceling debug wait task ...")
    13.             debugpy.wait_for_client.cancel()
    14.     T().start()
    15.     print("Waiting for client to attach debugger ...")
    16.     debugpy.wait_for_client()

    To create the Lambda function, you just need to take care of two things:

    1. Deploy the function via an S3 Bucket. You need to use the magic variable __local__ as the bucket name.
    2. Set the S3 key to the path of the directory your lambda function resides in. The handler is then referenced by the filename of your lambda code and the function in that code that should be invoked.

    We can quickly verify that it works by invoking it with a simple payload:

    1. $ awslocal lambda invoke --function-name my-cool-local-function --payload '{"message": "Hello from LocalStack!"}' output.txt

    Configuring Visual Studio Code for remote Python debugging

    For attaching the debug server from Visual Studio Code, you need to add a run configuration.

    2.     "version": "0.2.0",
    3.     "configurations": [
    4.         {
    5.             "name": "Python: Remote Attach",
    6.             "type": "python",
    7.             "request": "attach",
    8.             "connect": {
    9.                 "host": "localhost",
    10.                 "port": 19891
    11.             "pathMappings": [
    12.                 {
    13.                     "localRoot": "${workspaceFolder}",
    14.                     "remoteRoot": "."
    15.                 }
    16.             ]
    17.         }
    18.     ]
    19. }

    With our function from above you have about 15 seconds (the timeout is configurable) to switch to Visual Studio Code and run the preconfigured remote debugger. Make sure to set a breakpoint in the Lambda handler code first, which can then later be inspected.

    The screenshot below shows the triggered breakpoint with our 'Hello from LocalStack!' in the variable inspection view:

    Limitations

    Due to the ports used by the debugger, you can currently only debug one Lambda at a time. Multiple concurrent invocations will not work.

    Set LAMBDA_JAVA_OPTS with jdwp settings and expose the debug port (you can use any other port of your choice):

    Note the option here, it will delay code execution until debugger is attached to debgger server. If you want to change that simply switch to suspend=n.

    Configuring IntelliJ IDEA for remote JVM debugging

    1. while [[ -z $(docker ps | grep :5050) ]]; do sleep 1; done

    Run/Debug Configurations

    This shell script should simplify the process a bit since the debugger server is not immediately available (only once lambda container is up).

    Then create a new Remote JVM Debug configuration and use the script from above as a Before launch target:

    Now to debug your lambda function, simply click on the Debug icon with Remote JVM on LS Debug configuration selected, and then invoke your lambda function.

    Configuring Visual Studio Code for remote JVM debugging

    Make sure you installed the following extensions:

    Add a new task by creating/modifying the .vscode/tasks.json file:

    1. {
    2.     "version": "2.0.0",
    3.     "tasks": [
    4.         {
    5.           "label": "Wait Remote Debugger Server",
    6.           "type": "shell",
    7.           "command": "while [[ -z $(docker ps | grep :5050) ]]; do sleep 1; done; sleep 1;"
    8.         }
    9.     ]
    10. }

    Create a new launch.json file or edit an existing one from the Run and Debug tab, then add the following configuration: