This page describes how to use the Node.js Serverless Tracer with AWS Lambda functions during development. The preferred method is to use the Cisco AppDynamics AWS Lambda Extension. See Use the Cisco AppDynamics AWS Lambda Extension to Instrument Serverless APM at Runtime.

Before You Begin

After you have subscribed to Serverless APM for AWS Lambda and set up your environment variables, you can begin instrumentation. Ensure that your setup meets the following requirements:

This document contains links to Amazon Web Services (AWS) documentation. Cisco AppDynamicsmakes no representation as to the accuracy of Amazon documentation because Amazon controls its own documentation.

Install the Node.js Serverless Tracer Using npm During Development

You can instrument your ES6 lambda either using the manual instrumentation or automatic instrumentation.

Manual Instrumentation

Perform these steps based on your choice of Java Script modules.

To instrument your ES6 lambda, you can install the Node.js Serverless Tracer using these steps.

  1. Run the following command to install the Node.js serverless tracer using npm during development for ES6.

    npm install appdynamics-lambda-tracer --save 
    JS

  2. Run the following command to import the tracer:

    import tracer from "appdynamics-lambda-tracer";

tracer.init();
    JS

  3. Instrument the Function with the Node.js Serverless Tracer. The code snippet below demonstrates how to instrument a serverless function with the tracer:

    export const handler = tracer.functionWrapper(async (event) => {
  // YOUR CODE HERE
  return "Hello World";
});
    JS

To instrument your CommonJS lambda we recommend the AWS Lambda Extension. You can also install the Node.js Serverless Tracer using these steps:

  1. To install the tracer, navigate to the directory where the package.json file resides. Run the following npm command:

    npm install appdynamics-lambda-tracer --save
    JS

    The command downloads the tracer dependency into a node_modules/ folder.

  2. Initialize the Node.js Serverless Tracer below the require statement, by calling the tracer.init method.

    tracer = require('appdynamics-lambda-tracer'); 
//Initialize the tracer
tracer.init();
    JS

  3. To complete instrumentation, call tracer.mainModule(module) as the last line of your code. The code snippet below demonstrates how to instrument a serverless function with the tracer:

    // Your AWS Lambda handler function code here, for example:
exports.handler = async (event) => {
    // TODO implement
    const response = {
        statusCode: 200,
        body: JSON.stringify('Hello from Lambda!'),
    };
    return response;
};
//Complete the instrumentation
tracer.mainModule(module);
    JS

To instrument your TypeScript lambda, you can install the Node.js Serverless Tracer using these steps.

  1. Run the following command to install the Node.js serverless tracer using npm during development.

    npm install appdynamics-lambda-tracer -–save
npm install -D @types/aws-lambda esbuild
    JS

  2. Run the following command to import the tracer:

    import tracer from "appdynamics-lambda-tracer";

tracer.init();
    JS

  3. Instrument the Function with the Node.js Serverless Tracer. The code snippet below demonstrates how to instrument a serverless function with the tracer:

    export const handler = tracer.functionWrapper ( async (event: APIGatewayEvent, context: Context): Promise<APIGatewayProxyResult> => {
return {
statusCode: 200,
body: JSON.stringify({
message: 'hello world',
}),
};
});
    JS


Automatic Instrumentation

For automatic instrumentation you must configure the following environment variables.

  • APPDYNAMICS_IS_ESM_ENABLE - The value of this variable depends on the Java Script module that you are utilizing. If you are using ESM module, set the variable to true. However, if you are not using ESM module, set the variable to false.
  • APPDYNAMICS_APPLICATION_LAMBDA_HANDLER - You must define this variable to execute the lambda. Specify the handler function of the lambda in this variable.

Ensure to remove the AWS_LAMBDA_EXEC_WRAPPER environment variable.


To complete the instrumentation, perform the following steps based on your choice of Java Script modules.

 

  1. Add the Cisco AppDynamics layer in the layer section.

    arn:aws:lambda:us-west-<###>:layer:appdynamics-lambda-nodejs-<###>
    JS

  2. Update the lambda handler to  Cisco AppDynamics specific handler.

    appdynamics-lambda-nodejs-tracer.handler
    JS

  3. Add the following environment variables with other Cisco AppDynamics variables in the configuration section.

    1. APPDYNAMICS_APPLICATION_LAMBDA_HANDLER = Lambda handler

    2. APPDYNAMICS_IS_ESM_ENABLE = true


 

  1. Add the Cisco AppDynamics layer in the layer section.

    arn:aws:lambda:us-west-<###>:layer:appdynamics-lambda-nodejs-<###>
    JS

  2. Update the lambda handler to  Cisco AppDynamics specific handler.

    appdynamics-lambda-nodejs-tracer.handler
    JS

  3. Add the following environment variables with other Cisco AppDynamics variables in the configuration section.

    1. APPDYNAMICS_APPLICATION_LAMBDA_HANDLER = Lambda handler

    2. APPDYNAMICS_IS_ESM_ENABLE = false

 

  1. Add the Cisco AppDynamics layer in the layer section.

    arn:aws:lambda:us-west-<###>:layer:appdynamics-lambda-nodejs-<###>
    JS

  2. Update the lambda handler to  Cisco AppDynamics specific handler.

    appdynamics-lambda-nodejs-tracer.handler
    JS

  3. Add the following environment variables with other Cisco AppDynamics variables in the configuration section.

    1. APPDYNAMICS_APPLICATION_LAMBDA_HANDLER = Lambda handler

    2. APPDYNAMICS_IS_ESM_ENABLE = false, (true, if you are using ES Module)

By default, the Node.js Serverless Tracer automatically discovers exit calls passed over HTTP or inter-AWS Lambda calls. You need to create an exit call if your function does not use these protocols. See Node.js Serverless Tracer API.


Next Steps

You are ready to Verify the Serverless Tracer Instrumentation. 

You can also Integrate the Node.js Serverless Tracer with End User Monitoring or use the Node.js Serverless Tracer API.

Amazon Web Services, the AWS logo, AWS, and any other AWS Marks used in these materials are trademarks of Amazon.com, Inc. or its affiliates in the United States and/or other countries.