AWS Lambda - Debug locally with Eclipse

I am so excited to have entered into AWS world. I am from a development background. My first question has always been "How can I debug stuff". This is because half (75% to be precise!!) of development time is spent in debugging. This question has been in my mind since I got my first AWS certification. I looked at some of the articles and found lot of useful information on debugging AWS Lambda.

In this article I am going to list all the steps I did in order to debug a Lambda written in Java on a Windows PC. Typically a lambda can be deployed in a serverless environment and invoked by an event such as S3 event. However, in order to test the Lambda locally, you would need few additional steps to setup your debug environment. I felt it is important to outline all the steps in one place start to end. I assume the reader is familiar with the AWS terms.

Prerequisite Steps

• Aws account : Must have the access_keyI_id and secret_access_key. This can be available when a new account is created. I just created a new user with admin role for now. Used that for my demo project.
• Overall Instruction found in AWS website : Installing the AWS SAM CLI on Windows - AWS Serverless Application Model (amazon.com)

Software Installation

• Java 8 or higher : https://javadl.oracle.com/webapps/download/AutoDL?BundleId=244065_89d678f2be164786b292527658ca1605
• AWS CLI : Installing, updating, and uninstalling the AWS CLI version 2 - AWS Command Line Interface (amazon.com)
• SAM CLI :https://github.com/aws/aws-sam-cli/releases/latest/download/AWS_SAM_CLI_64_PY3.msi
• DOCKER : Install Docker Desktop on Windows | Docker Documentation
• Eclipse plugin ( AWS ToolKit) :eclipse->help->install new Software , and then provide url : https://aws.amazon.com/eclipse

Validate the installations

Run the following commands to make sure you did not miss any of the software. I am not too specific about the version other than the java version(must be java 8 or above).

• "java - version"
• "sam --version"
• "docker --version"
• "aws s3 ls" - This may not return any items, if you have no s3 bucket created.

Configuration

Set your AWS credential by running "aws configure" in command window. This step will accept the login credentials and AWS region to which you need to connect from your PC. These information will be saved in c:\users\<user id>\.aws folder.

Create Maven Java Project

Use Eclipse to build a new maven Java project. This process will build a maven project with one Lambda handler class. I choose an handler for S3 event. Eclipse will ask few easy questions. Make sure the region you choose is same as in "Configuration" step.

Once the project is built, I reduced the handler method to bare minimum to get going.

public String handleRequest(S3Event event, Context context) {
	context.getLogger().log("Received event: " + event);
    return "All good";
}

Also disable the unit test classes(if any) for now to avoid the build error. Make sure the the project builds ok and creates the jar file in the target folder, when you run the Maven Install(Eclipse project->Run As->Maven Install).

As you see on the picture, the jar file "demo-1.0.0.jar" is created successfully.

Template Creation.

Now you need a template.yml for docker to understand how to run the image locally. Again, I have the minimum entries in the template.yml file. Please make sure that the file is in the project home directory. Please note that the logical name of the Lambda is "ShankarLambda"(for lack of better name). Indentation of the file is important.

AWSTemplateFormatVersion: '2010-09-09'
Transform: 'AWS::Serverless-2016-10-31'
Description: An AWS Lambda application that calls the Lambda API.
Resources:


  ShankarLambda:
    
      Type: AWS::Serverless::Function
      Properties:
        CodeUri: target/demo-1.0.0.jar
        Handler: com.amazonaws.lambda.demo.LambdaFunctionHandler::handleRequest
        Runtime: java8
        Description: Java function
        MemorySize: 512
        Timeout: 1000
        # Function's execution role
        Policies:
          - AWSLambdaBasicExecutionRole
          - AWSLambdaReadOnlyAccess
          - AWSXrayWriteOnlyAccess
          - AWSLambdaVPCAccessExecutionRole
        
       Tracing:Active

Learn to Create fake S3 Event

Run "sam local generate-event s3 put" on your command window. You will notice the command will print fake event text. We will need this command in later steps.

Pipe the event to the handler you created, to start running your handler.

My project directory is " C:\Users\sbara\eclipse-workspace\ShankarLambda", and hence I did "cd C:\Users\sbara\eclipse-workspace\ShankarLambda" to make sure all my commands are based of that folder.

Run the command : "sam local generate-event s3 put | sam local invoke ShankarLambda" in the command prompt. This process will build the image and sent to the docker. The command will also make use of the template file created in earlier step. You notice "All good" message at end of the processing.

C:\Users\sbara\eclipse-workspace\ShankarLambda>sam local generate-event s3 put | sam local invoke   ShankarLambda
Invoking com.amazonaws.lambda.demo.LambdaFunctionHandler::handleRequest (java8)
Decompressing C:\Users\sbara\eclipse-workspace\ShankarLambda\target\demo-1.0.0.jar
Skip pulling image and use local one: amazon/aws-sam-cli-emulation-image-java8:rapid-1.18.0.


Mounting C:\Users\sbara\AppData\Local\Temp\tmp8leinpu4 as /var/task:ro,delegated inside runtime container
START RequestId: 3d919cc6-27c0-40fa-a431-84010168bd4b Version: $LATEST
Received event: com.amazonaws.services.lambda.runtime.events.S3Event@cb51256END RequestId: 3d919cc6-27c0-40fa-a431-84010168bd4b
REPORT RequestId: 3d919cc6-27c0-40fa-a431-84010168bd4b  Init Duration: 0.54 ms  Duration: 18741.84 ms   Billed Duration: 18800 ms       Memory Size: 512 MB     Max Memory Used: 512 MB

"All good"


C:\Users\sbara\eclipse-workspace\ShankarLambda>

Start debugging...(Half of a developer's life, may be 75% to be accurate !!)

Make sure you are in the project directory. Mine is " C:\Users\sbara\eclipse-workspace\ShankarLambda", and hence I did "cd C:\Users\sbara\eclipse-workspace\ShankarLambda".

Run the command : "sam local generate-event s3 put | sam local invoke -d 5858 ShankarLambda" in the command prompt. The process will wait till you setup a remote debugging in your IDE(next step). Also, Please make sure you have a break point in the handlerRequest method in the Lambda class.

Eclipse debug configuration

Create eclipse remote debug configuration as displayed in the picture below and start debugging. This will allow the previous step to proceed.

My Desire to be able to Debug locally is Met. I achieved my moksha.....for now

Please note that , since the process is running in docker, your changes in Java has to be rebuilt and the whole process needs to be restarted to pickup your change.

Hope you like this article !!!. Please provide your feedback on linkedin messaging.

Reference

https://www.youtube.com/watch?v=Pk6XWPbLUYQ