Debug Serverless Applications Using AWS SAM Local - AWS Toolkit for Eclipse
PrerequisitesImport the SAM Application from AWS CodeStarDebug Lambda Function LocallyTest API Gateway LocallyAdvanced SettingsMore Info

Debug Serverless Applications Using AWS SAM Local

This tutorial guides you through debugging a serverless application project with the AWS Toolkit for Eclipse using AWS SAM Local. SAM Local is the AWS CLI tool for managing serverless applications written with the AWS Serverless Application Model (AWS SAM). See the SAM Local README for more information.

Prerequisites

To use this tutorial, you must have the AWS Toolkit for Eclipse, Docker, and AWS SAM Local installed. See the AWS SAM Local README for Docker and SAM Local installation instructions. See the Getting Started topic for instructions on installing and setting up the AWS Toolkit for Eclipse.

Note

To use the AWS SAM Local feature of the AWS Toolkit for Eclipse, your project must be a valid Maven Project with a valid pom.xml file.

After you install the required tools, open the Eclipse Preferences dialog box from the Eclipse menu. Configure the SAM Local Executable path, as shown. This enables the AWS Toolkit for Eclipse to know where to find your SAM Local installation.

SAM local dialog box

Import the SAM Application from AWS CodeStar

For this tutorial, you need a sample project in AWS CodeStar. See the Creating a Serverless Project in AWS CodeStar tutorial in the AWS CodeStar User Guide to create a sample project.

To import SAM app from AWS CodeStar

  1. On the Eclipse toolbar, open the Amazon Web Services menu (identified by the AWS homepage icon), and then choose Import AWS CodeStar Project. Or, on the Eclipse menu bar, choose File, Import, AWS, AWS CodeStar Project.

  2. Choose the region that the sample application was created in.

  3. Choose your sample project from the Project Name list.

  4. Add in your Git credentials. See the AWS CodeCommit User Guide to learn how to get Git credentials for CodeCommit.

    SAM Local import in AWS CodeStar Project Selection dialog box

  5. Choose Next.

  6. Choose Next on the Branch Selection page.

  7. Choose Finish on the Local Destination page.

Next, you can debug this serverless application locally using SAM Local within Eclipse.

Debug Lambda Function Locally

Create a debug configuration for your serverless application and use SAM Local to run the application locally.

To debug the Lambda function locally

  1. In the Eclipse Project Explorer, open HelloWorldHandler.java.

  2. Right-click in your Eclipse code window, choose Debug As, and then choose AWS SAM Local.

    SAM Local debug dialog box

  3. For this example, leave the Project and Template as they are.

  4. Choose Lambda Function in the Run as field.

  5. Choose GetHelloWorld in the Function identifier field.

  6. For this example, we will provide an Amazon S3 event. Choose Generate next to the Event input box.

    SAM Local debug dialog box

  7. Choose a region that has your Amazon S3 bucket.

  8. Enter a valid Amazon S3 bucket name.

  9. Enter a valid Amazon S3 object key, and then choose OK.

  10. On the Save As page, select the current project and enter a name for the event file. In this example, we used s3-event.json.

    SAM Local debug dialog box

  11. Choose OK to save the event file and get back to the main dialog box.

  12. Leave the advanced settings as they are. See Advanced Settings to learn more about those fields.

  13. Choose Apply, and then choose Debug.

This runs the Lambda function locally. You can set breakpoints as you would for other applications to debug the code.

Test API Gateway Locally

You can also test the HTTP request/response functionality with SAM Local.

To test API Gateway locally

  1. Right-click in your Eclipse code window, choose Debug As, Debug Configuration.

    SAM Local debug dialog box

  2. Create a new Debug Configuration for this run and name it something different.

  3. Choose API Gateway in the Run as field.

  4. Leaving all other fields as they are, your configuration should look similar to the following.

    SAM Local debug dialog box

  5. Choose Apply, and then choose Debug.

This spawns a local API gateway that you can use to test your application. The debug output will contain HTTP links that can be used to verify the request/response functionality of your code.

Example SAM Local debug output for api gateway

Advanced Settings

This section describes the advanced options available on the SAM Local Debug configurations page.

SAM Local debug dialog box advanced options

AWS Configuration

Select profile

(Required) The profile to use for AWS credentials.

(Default) The default profile

Select region

(Required) The region that the application is deployed to.

(Default) US East (Virginia)

SAM Local Configuration

Maven goals

(Required) Maven goals to execute when building the application. You must customize these goals if the default does not generate a Jar file with all the dependencies included (fat Jar). See Maven Shade Plugin in Maven Project to learn how to use the plugin to create a fat Jar.

(Default) clean package

SAM runtime

(Required) Path to the SAM executable.

(Default) /usr/local/bin/sam

Debug port

(Required) Port that the Eclipse debugger uses to connect to SAM Local.

(Default) 5858

Env vars

(Optional) Path to a JSON file that contains values for environment variables used by Lambda functions. See Environment variable files in the SAM Local user guide to learn the required syntax for this file.

(Default) Empty

Lambda Function Configuration

Code URI

(Optional) Path to the code archive file. For the example on this page, it would be the path to the .jar file.

(Default) Path in the template.yml file

Timeout

(Required) Lambda function runtime timeout.

(Default) 300

More Info

For more information about AWS SAM Local, see the AWS SAM Local user guide in GitHub. For more information about the AWS Serverless Application Model (SAM), see the AWS SAM project in GitHub.