AWS Lambda Native Tracing for Node.js

The Instana AutoTrace setup for Node.js allows you to trace your AWS Lambda functions is to use the Instana Lambda layer and a custom function handler. This approach requires no modification of the Lambda function code and is done purely through configuration. It is also suited to be automated or included in a Lambda deployment pipeline.

To enable tracing of Node.js Lambda functions, perform the following steps:

1. Add the Instana Lambda layer to your function.

   1. In the configuration page for your Lambda function, click on the Layers box and then on Add a layer.
   2. In the popup that opens, select Provide a layer version ARN and copy and paste the ARN for the Instana Lambda Layer that matches your region; you can find the right ARN for the Instana Lambda Layer in the Instana Lambda Layers section.

2. Configure the Lambda Handler. Set the handler to instana-aws-lambda-auto-wrap.handler if you use CommonJS . Set the handler to instana-aws-lambda-auto-wrap-esm.handler if you use ES Modules (ES6) (available from layer version 223).

   To change the setting for the Lambda handler, find the "Basic Settings" section on the configuration page.

   

   Click on edit and insert instana-aws-lambda-auto-wrap.handler into the field labeled "Handler".

   

   The Instana Lambda layer automatically triggers the default Node.js runtime handler index.handler. If you use a custom handler, specify your handler in the environment variable LAMBDA_HANDLER to notify the Instana Lambda Layer. See the next section for all environment variables that need to be set.

   The Lambda configuration page might display a warning like Lambda can't find the file instana-aws-lambda-auto-wrap.js. This might also be displayed later when returning to the configuration page. Do not let this warning distract you. The handler is contained in the Instana Lambda layer but the AWS Lambda configuration page does not take that into account.

3. Configure Environment Variables. Add the following environment variables:

   • INSTANA_ENDPOINT_URL: This is your serverless monitoring endpoint. Make sure to use the correct value for your region that starts with https://serverless-.
   • INSTANA_AGENT_KEY: Your agent key.
   • LAMBDA_HANDLER: Set your custom handler. If your main file is myModule.js, which exports the function myHandler, set the environment variable to myModule.myHandler. The default value is index.handler.

   In the following example, the original main Lambda Handler is index.js, and therefore you don't need to set the environment variable LAMBDA_HANDLER.

   In the following example, the original main Lambda Handler is server.js, and therefore you need to set the environment variable LAMBDA_HANDLER to server.handler.

   You can also obtain the correct values for these environment variables by going to your Instana installation, click ... More -> Agents -> Installing Instana Agents -> Platform: AWS -> Technology: AWS Lambda.

4. Save the Lambda function definition.

All the steps outlined earlier can be done either via the AWS web console or any of the usual AWS management tools, such as:

• the aws command line interface
• the serverless framework cli
• the AWS Cloud Development Kit

Here is an example aws CLI command that might serve as a starting point if you want to automate the Instana integration of your AWS Lambdas:

# Do not copy and paste this verbatim!
# It will overwrite any previously defined collection of layers and
# environment variables.
aws --region $YOUR_REGION lambda update-function-configuration \
  --function-name $YOUR_LAMBDA_FUNCTION_NAME \
  --layers $INSTANA_LAYER_ARN \
  --handler instana-aws-lambda-auto-wrap.handler \
  --environment ""Variables={INSTANA_ENDPOINT_URL=... , INSTANA_AGENT_KEY=... , ...}""
 

Instead of using the Instana Lambda layer, you can also choose to install the npm package @instana/aws-lambda manually:

1. Add the dependency @instana/aws-lambda to your project by executing npm install -S @instana/aws-lambda (or yarn add @instana/aws-lambda) in your project directory. This will add the package to your node_modules folder and save the dependency in your package.json file.
2. Add the environment variables INSTANA_ENDPOINT_URL and INSTANA_AGENT_KEY with the required values.
3. Modify the function's code according to the Manually wrapping the handler section.

If your team uses Container based Lambda deploys, you can use our base containers on icr.io/instana/aws-lambda-nodejs or include the following snippet in your Dockerfile and set the build time arguments to the appropriate versions.

Instana currently supports only the x86_64 architecture.

This image is not intended for use in FedRAMP-compliant environments.

# This is the container image that delivers Instana's monitoring capabilities.
# It will not become the base image for your Lambda container image, it just provides a few files.
FROM icr.io/instana/aws-lambda-nodejs:latest as instana-layer

# This is the actual base image for your Lambda container image. You can also use any other base image that is suitable
# for container image based Lambda functions.
FROM public.ecr.aws/lambda/nodejs:14

# Copy Instana's Node.js monitoring components into your Lambda container image.
COPY --from=instana-layer /opt/extensions/ /opt/extensions/
COPY --from=instana-layer /opt/nodejs/ /opt/nodejs/

# The remainder of your Dockerfile, as it was without adding the Instana layer. The following is just an example:
COPY index.js package.json package-lock.json /var/task/
WORKDIR /var/task
RUN npm install

# Override the CMD. This can also be done as a parameter override outside of the Dockerfile, for example in the AWS console.
# If you use ES modules, use CMD [ "instana-aws-lambda-auto-wrap-esm.handler" ] instead.
CMD [ "instana-aws-lambda-auto-wrap.handler" ]
 

Instead of icr.io/instana/aws-lambda-nodejs:latest, you can also use a specific version of the Instana npm module @instana/aws-lambda greater or equal to 1.137.2 (see CHANGELOG), so for example:

FROM icr.io/instana/aws-lambda-nodejs:1.140.1 as instana-layer
 

Or you can only pin the major version, while allowing for more recent minor/patch releases:

FROM icr.io/instana/aws-lambda-nodejs:1 as instana-layer
 

Edit the serverless.yml to integrate Instana tracing with the Serverless Framework. Follow the steps:

1. Copy the Layer ARN from the list, and add the ARN to the layers section of the target function definition.

2. Add environment variables INSTANA_AGENT_KEY, INSTANA_ENDPOINT_URL and LAMBDA_HANDLER. For further information, see Instana AutoTrace setup.

See the following example serverless.yml:

service: service-a

provider:
  name: aws
  runtime: nodejs16.x
  stage: dev
  region: us-east-2

functions:
  with-layer:
    environment:
      INSTANA_ENDPOINT_URL: INSTANA_ENDPOINT_URL
      INSTANA_AGENT_KEY: INSTANA_AGENT_KEY
      LAMBDA_HANDLER: src/index.handler
    layers:
      - arn:aws:lambda:us-east-2:410797082306:layer:instana-nodejs:111
    handler: instana-aws-lambda-auto-wrap.handler
 

The ARNs of the latest version of the AWS Lambda layers for the Lambda runtimes listed in Supported Runtimes are the following, per region:

That is, the pattern is arn:aws:lambda:${region}:410797082306:layer:instana-nodejs:${layer-version} (or arn:aws-cn:lambda:${region}:107998019096:layer:instana-nodejs:${layer-version} for AWS regions in China).

Make sure to always use the latest versions and update the layer version you are using in regular intervals to benefit from new features and fixes that we provide when publishing a new version of the layer.