Serverless (legacy agent)

The AppOptics Node.js agent offers automatic instrumentation for AWS Lambda functions, including any Supported components (legacy agent) used in your function. Ensure that prerequisites described in tracing are set up before proceeding.

Install

The agent is provided as a Lambda layer named appoptics-node. This layer needs to be added to your Lambda function, and then the agent must be enabled either via function configuration (no code change needed) or manually with a few lines of code in your function handler.

Agent Layer

The layers are listed at https://files.appoptics.com/lambda-layers/appoptics-node. SolarWinds strongly recommends using the most recent version available for your region.

You can add the layer to your Lambda function using standard AWS SDK or CLI tools (see AWS Lambda Layers in the Amazon Web Services documentation) or via the AWS Management Console (see Configuring functions in the AWS Lambda console in the Amazon Web Services documentation).

An example of adding an agent layer to your function (in the us-east-1 region) using the AWS CLI v2:

aws lambda update-function-configuration --function-name <your-function-name> --layers 'arn:aws:lambda:us-east-1:085151004374:layer:appoptics-node:10' ...

Enable

After adding the layer to your Lambda function, you can enable the agent in one of the ways described below.

Using Configuration

Enable the agent by making a few configuration changes to your function:

1. Set the environment variable APPOPTICS_WRAP_LAMBDA_HANDLER to the function’s configured “Handler” setting.

2. Change “Handler” setting to appoptics-auto-lambda.handler

An example using the AWS CLI v2:

aws lambda update-function-configuration --function-name <your-function-name> --handler 'appoptics-auto-lambda.handler' --environment 'Variables={APPOPTICS_WRAP_LAMBDA_HANDLER=<current-handler>,...}'

An example of what this looks like in the AWS Management Console for Lambda (see Configuring functions in the AWS Lambda console in the Amazon Web Services documentation for more information):

You may see a message in the Lambda console UI that says Lambda can't find the file appoptics-auto-lambda.js. Make sure that your handler upholds the format: file-name.method. This is a limitation with the console UI and is safe to ignore.

Using Wrapper Function

Instead of enabling by using configuration changes, you can manually wrap your Lambda function with a convenience wrapper provided by the Node.js agent. It requires just a few lines of code:

1. Add const ao = require(‘appoptics-apm’); as the first require in your function code.
2. Use the function ao.wrapLambdaHandler() to wrap the handler you export to Lambda.

For example, if this is your function code to start with:

async function myHandlerEchoEvent (event, context) {
  return {statusCode: 200, body: JSON.stringify(event)};
}

module.exports.handler = myHandlerEchoEvent;

Change it to:

// require the agent - contained in appoptics-node layer
const ao = require('appoptics-apm');

async function myHandlerEchoEvent (event, context) {
  return {statusCode: 200, body: JSON.stringify(event)};
}

// wrap user handler and export the wrapped function.
module.exports.handler = ao.wrapLambdaHandler(myHandlerEchoEvent);

Configuration

With a few exceptions, the standard agent configuration settings are supported in the AWS Lambda environment and can be set as Lambda function environment variables. See Using AWS Lambda environment variables in the Amazon Web Services documentation for more information about environment variables.

The folllowing environment variables can be particularly useful:

• APPOPTICS_ENABLED -- set to false to disable the agent
• APPOPTICS_LOG_SETTINGS -- the default value is error,warn. To show more information, set the value to error,warn,debug,info.

The exceptions are described below.

• APPOPTICS_SERVICE_KEY - not required since the AppOptics API Token is set during forwarder install, and the Service Name is set during the subscription filter configuration.
• APPOPTICS_HOSTNAME_ALIAS - ignored in the Lambda environment; it should be set during the subscription filter configuration
• APPOPTICS_EC2_METADATA_TIMEOUT - not available in the Lambda environment
• APPOPTICS_PROXY - proxy is not available in the Lambda environment
• APPOPTICS_RUNTIME_METRICS - runtime metrics are not supported in the Lambda environment
• APPOPTICS_TRIGGER_TRACE - trigger trace is not supported in the Lambda environment
• All settings for transaction-based filtering are not supported in the Lambda environment.

The agent supports the following configuration setting only in the AWS Lambda environment:

• APPOPTICS_TRANSACTION_NAME -- A custom transaction name for the trace, which will be used in preference over the default or SDK-specified transaction name.

Troubleshooting

Make sure prerequisites described in tracing are set up and check for trace data in the CloudWatch Logs log group for your Lambda function.

If there was an error finding the function specified by the environment variable APPOPTICS_WRAP_LAMBDA_HANDLER (when enabling via configuration), there should be a line in the logs that contains:

failed to load APPOPTICS_WRAP_LAMBDA_HANDLER:

Additional information follows that text.

If no errors are displayed, try setting the environment variable APPOPTICS_LOG_SETTINGS=error,warn,debug,info. That will cause additional information to be logged, which could help solve the problem. Include information from those logs when you e-mail AppOptics support for help troubleshooting Lambda tracing functions with the Node.js agent.

Uninstall

Reverse the installation instructions to remove the AWS Lambda wrapper, removing the appoptics-node layer last. Alternatively, define the environment variable APPOPTICs_ENABLED=false to disable the agent temporarily instead.