How to use?

Prerequisites

As a prerequisite for using this toolkit, you should obtain an access key pair from the SLAppForge Access Key Manager. For that, please visit https://www.slappforge.com/java-debug and login with your SLAppForge Sigma account. If you don’t have a Sigma account you can create one for free from here. Once logged in, you can generate an Access Key and an Access Secret.

Configuration

Adding Proxy to the Lambda function

To use this toolkit, the proxy component should be added to your NodeJS Lambda function. For that you have 2 alternatives.

Option 1

Add slappforge-lambda-debug-proxy as a NPM dependency to your Lambda function.

npm i slappforge-lambda-debug-proxy --save

Option 2

Add the Lambda Layer with the following ARN to your Lambda function.

arn:aws:lambda:us-east-1:892904900711:layer:slappforge-lambda-debug-layer:2

After adding the proxy component as a dependency using one of the options, require the package at the very end of the file that contains the Lambda handler that you want to debug. And also add a debugger line at the start of the handler function, so that the execution will be suspended at that point until the debugger is connected.

Also make sure to set a reasonable Timeout value for the Lambda function, so that you have enough time for debugging, before the Lambda function runs out of time.

exports.handler = async (event) => {
    debugger;

    // Your code comes after this
    console.log(event);
    return 'Hello World!'; 
};

require('slappforge-lambda-debug-proxy');

Configuring Lambda environment variables

Then the following environment variables must be set for the Lambda function with the appropriate values.

In addition to the above, following optional environment variables can be used to provide the Broker Server details.

Installing and running the Local Client

The Local Client module of the toolkit should be installed as a global NPM dependency on the developer machine.

npm i slappforge-debug-client -g

Then it should be invoked via a terminal providing the following arguments.

slp-debug-client -f=MyFunction -k=abcd=efgh-1234-5678 -x=abc123def456ghi789

Configuring the IDE Debugger

Configuring steps for the IDE debugger varies based on the IDE in use. This toolkit has been currently tested with Jetbrains IntelliJ IDEA and Jetbrains WebStorm IDEs. It might work with other IDEs that generally support NodeJS remote debugging.

IntelliJ IDEA / WebStorm

• Open the project containing the Lambda source code and create a new Run/Debug Configuration selecting Attach to NodeJS/Chrome as the type from left side panel
• Provide any name for the Run/Debug profile
• Configure the Host as localhost and the Port as 9249
• Select the Attach to type as Chrome or NodeJS > 6.3 started with --inspect
• Click Apply and then OK

Running the Debugger

• First start the Local Client providing the necessary parameters as mentioned here
• Then invoke the Lambda with debugging enabled. You can do this either using the Test functionality on the AWS Lambda console, or by triggering an actual event such as API Gateway request, S3 operation, etc.
• Then the Lambda execution will suspend at the debugger line waiting for a debugger to connect
• Finally invoke the Debugger from the IDE and wait for a couple of seconds for it to connect through
• Happy Debugging!