Integration Options for Node.js SDK
Using Layers
Without Layers
Serverless Framework
SST
AWS SAM
AWS CDK
Integrating Thundra using AWS Lambda Layers is the recommended (and easier) way to get started with Thundra. Depending on whether or not you choose to use a custom runtime, you can integrate Thundra with no code changes at all or just by wrapping your handler function.
Bundle all your Node.js Lambda function files and any additional required packages, and then upload it to the AWS Lambda console using the “Upload a.zip file” option for the code entry type. Note that Thundra dependencies are not expected to be in the artifact to be uploaded, as they come with a layer that will be utilized at a later point.
Add Thundra's Node.js layer to your Lambda function using the ARN below. Note that the ARN contains a region and a version parameter which you will need to set. Set the region value to your Lambda function's region and the version value to the layer version you want to use with your Lambda function.
arn:aws:lambda:${region}:269863060030:layer:thundra-lambda-node-layer:${version}
Latest version of the Thundra's Node.js layer:
After the Thundra layer ARN has been added, you can continue using a custom runtime or continue without using a custom runtime. Regardless of what you choose, make sure to also set the
THUNDRA_APIKEY
environment variable to the API key you get from the Thundra console.
You should only use one (either auto or manual) of the options below, not both of them!
Set the handler to
thundra_handler.wrapper
and then set the THUNDRA_AGENT_LAMBDA_HANDLER
environment variable value to your original handler (e.g., index.handler
).You can wrap your Lambda handler to integrate Thundra as shown below.
index.js
const thundra = require("@thundra/core")();
exports.handler = thundra((event, context,callback) => {
callback(null, "Hello Thundra!");
});
In the example above, the required
@thundra/core
package is already available in Thundra's Node.js layer, which we already added. Thus, you don't need to install the package and bundle it with your Lambda function.Now you can try to invoke your Lambda function and see the details of your invocation in the Thundra console!
If you do not want to use AWS Lambda Layers, you can still easily integrate Thundra to your Node.js Lambda function. All you have to do is install the
@thundra/core
package via npm
.npm install @thundra/core --save
After installing the
@thundra/core
module, you will need to wrap your Lambda handlers. Thundra will monitor your AWS Lambda function automatically, supporting callback
along with various context
functions.handler.js
const thundra = require("@thundra/core")();
exports.handler = thundra((event, context,callback) => {
callback(null, "Hello Thundra!");
});
Bundle your function and any additional required Node.js packages, and then upload it to the AWS Lambda console using the “Upload a.zip file” option for the code entry type.
In the AWS Lambda console, set the
THUNDRA_APIKEY
environment variable to the API key value you got from the Thundra console.
Now you can try to invoke your Lambda function and see the details of your invocation in the Thundra console!
npm install serverless-plugin-thundra
After installing Thundra’s serverless plugin, specify it as a plugin for your serverless environment by adding it under the plugins section of your serverless.yml file.
serverless.yml
plugins:
- serverless-plugin-thundra
Step 3: Add
THUNDRA_APIKEY
to Environment Variables Under provider
Section in serverless.yml
serverless.yml
provider:
environment:
THUNDRA_APIKEY: <YOUR-THUNDRA-API-KEY>
Step 4: Deploy
serverless deploy
Now you can try to invoke your Lambda function and see the details of your invocation in the Thundra console!
Thundra Layer ARN
arn:aws:lambda:${region}:269863060030:layer:thundra-lambda-node-layer:${version}
Latest version of the Thundra's Node.js layer:
With the Thundra layer ARN (using latest layer version is highly recommended), you can use the layer construct in your CDK code.
import { LayerVersion } from "@aws-cdk/aws-lambda";
const thundraLayer = LayerVersion.fromLayerVersionArn(this, "ThundraLayer", "<ARN>");
You can then set it for all the functions in your stack using the
addDefaultFunctionLayers
and addDefaultFunctionEnv
. Note we only want to enable this when the function is deployed, not in Live Lambda Dev as the layer will prevent the debugger from connecting.if (!scope.local) {
const thundraAWSAccountNo = 269863060030;
const thundraNodeLayerVersion = 96; // Latest version at time of writing
const thundraLayer = LayerVersion.fromLayerVersionArn(
this,
"ThundraLayer",
`arn:aws:lambda:${scope.region}:${thundraAWSAccountNo}:layer:thundra-lambda-node-layer:${thundraNodeLayerVersion}`,
);
this.addDefaultFunctionLayers([thundraLayer]);
this.addDefaultFunctionEnv({
THUNDRA_APIKEY: process.env.THUNDRA_API_KEY,
NODE_OPTIONS: "-r @thundra/core/dist/bootstrap/lambda",
});
}
- Add the
THUNDRA_APIKEY
environment variable using your Thundra API key.
Globals:
Function:
Environment:
Variables:
THUNDRA_APIKEY: <YOUR-THUNDRA-API-KEY>
- Add the Thundra layer to
Layers
in theGlobals
section. TheThundraAWSAccountNo
andThundraNodeLayerVersion
parameters are defined in the Parameters section in the following configuration:
Latest version of the Thundra's Node.js layer:
Parameters:
ThundraAWSAccountNo:
Type: Number
Default: 269863060030
ThundraNodeLayerVersion:
Type: Number
Default: 96 # Or use any other version
Globals:
Function:
Layers:
- !Sub arn:aws:lambda:${AWS::Region}:${ThundraAWSAccountNo}:layer:thundra-lambda-node-layer:${ThundraNodeLayerVersion}
…
- Change
Handler
to Thundra handler
Resources:
HelloWorldFunction:
Type: AWS::Serverless::Function
Properties:
Handler: thundra_handler.wrapper
- Pass your handler to Thundra over
THUNDRA_AGENT_LAMBDA_HANDLER
environment variable
Resources:
HelloWorldFunction:
Type: AWS::Serverless::Function
Properties:
Handler: thundra_handler.wrapper
Environment:
Variables:
THUNDRA_AGENT_LAMBDA_HANDLER: <YOUR-LAMBDA-HANDLER>
An example configuration:
Parameters:
ThundraAWSAccountNo:
Type: Number
Default: 269863060030
ThundraNodeLayerVersion:
Type: Number
Default: 96 # Or use any other version
Globals:
Function:
Timeout: 5
Environment:
Variables:
THUNDRA_APIKEY: <YOUR-THUNDRA-API-KEY>
Layers:
- !Sub arn:aws:lambda:${AWS::Region}:${ThundraAWSAccountNo}:layer:thundra-lambda-node-layer:${ThundraNodeLayerVersion}
Resources:
HelloWorldFunction:
Type: AWS::Serverless::Function
Properties:
Handler: thundra_handler.wrapper
Environment:
Variables:
THUNDRA_AGENT_LAMBDA_HANDLER: <YOUR-LAMBDA-HANDLER>
Step 2: Test / Deploy
To build and run your function locally, use the following:
sam build && sam local invoke
Then, package and deploy your function using
sam
.Now you can try to invoke your Lambda function and see the details of your invocation in the Thundra console!
- Add
THUNDRA_APIKEY
environment variable with your Thundra API key.
import {Function} from "@aws-cdk/aws-lambda";
export class YourConstructClass extends core.Construct {
const thundraApiKey = <YOUR-THUNDRA-API-KEY>;
constructor(scope: core.Construct, id: string) {
const yourFunction = new Function(this, "<YOUR-LAMBDA-HANDLER>", {
..., // other function properties
environment: {
..., // other environment variables
THUNDRA_APIKEY: thundraApiKey
}
});
}
}
- Define Thundra layer and add it to your function properties.
- And change your handler to Thundra's handler as described below.
Latest version of the Thundra's Node.js layer:
import {Aws} from "@aws-cdk/core";
import {Function, LayerVersion} from "@aws-cdk/aws-lambda";
export class YourConstructClass extends core.Construct {
const thundraApiKey = <YOUR-THUNDRA-API-KEY>;
const thundraAWSAccountNo = 269863060030;
const thundraNodeLayerVersion = 96; // or any other version
const thundraLayer = LayerVersion.fromLayerVersionArn(
this,
"ThundraLayer",
`arn:aws:lambda:${Aws.REGION}:${thundraAWSAccountNo}:layer:thundra-lambda-node-layer:${thundraNodeLayerVersion}`
);
constructor(scope: core.Construct, id: string) {
const yourFunction = new Function(<scope>, <id>, {
..., // other function properties
// Set your main handler to Thundra's handler
handler: "thundra_handler.wrapper",
environment: {
..., // other environment variables
THUNDRA_APIKEY: thundraApiKey,
// Add your handler as an environment variable
// for Thundra to call as the original handler
THUNDRA_AGENT_LAMBDA_HANDLER: "<YOUR-LAMBDA-HANDLER>",
},
layers: [
thundraLayer,
... // other layers
]
});
}
}
Aws.REGION
is a pseudo parameter that is bootstrapped from your stack's environment configuration
An example configuration:
import {Aws} from "@aws-cdk/core";
import {Code, Function, Runtime, LayerVersion} from "@aws-cdk/aws-lambda";
export class YourConstructClass extends core.Construct {
const thundraApiKey = <YOUR-THUNDRA-API-KEY>;
const thundraAWSAccountNo = 269863060030;
const thundraNodeLayerVersion = 96; // or any other version
const thundraLayer = LayerVersion.fromLayerVersionArn(
this,
"ThundraLayer",
`arn:aws:lambda:${Aws.REGION}:${thundraAWSAccountNo}:layer:thundra-lambda-node-layer:${thundraNodeLayerVersion}`
);
constructor(scope: core.Construct, id: string) {
const handler = new Function(this, "MyFunction", {
runtime: Runtime.NODEJS_14_X,
code: Code.asset("/path/to/your/resource"),
handler: "thundra_handler.wrapper",
environment: {
THUNDRA_APIKEY: thundraApiKey,
THUNDRA_AGENT_LAMBDA_HANDLER: "<YOUR-LAMBDA-HANDLER>",
},
layers: [
thundraLayer
]
});
}
}
npm run build && cdk deploy
Now you can try to invoke your Lambda function and see the details of your invocation in the Thundra console!