Serverless (legacy agent)

The AppOptics Python 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-python. This layer needs to be added to your Lambda function, and then the agent must be enabled via function configuration (no code change needed).

Agent Layer

The layers are listed at Index of /lambda-layers/appoptics-python/. SolarWinds strongly recommends using the most recent version available for your AWS 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-python:1' ...

Enable

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

• Using the AWS Console
• Using AWS CLI V2
• Using AWS SAM Templates

Regardless of the configuration option you choose, after successfully enabling instrumentation of the Lambda function, the function settings should look similar to the AWS Console shown in the image below, in this case for the function handler lambda_function.lambda_handler.

Using the AWS Console

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_apm.aws_lambda_wrapper.handler

Using AWS CLI V2

You can directly modify the Lambda function handler and the Lambda function environment variables by providing the --handler and --environment options to aws lambda update-function-configuration.

Example:

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

Using AWS SAM Templates

You can also add the appoptics-python layer in an AWS SAM template. Similar to the above options, all you need to do is set the Handler and the function environment by adding the following code to the Properties of your Lambda function defined in the SAM template.

HelloWorld:
    Type: AWS::Serverless::Function
    Properties:
      ...
      Handler: appoptics_apm.aws_lambda_wrapper.handler
      Layers:
        - arn:aws:lambda:<aws-region>:085151004374:layer:appoptics-python:1
      Environment:
        Variables:
          APPOPTICS_WRAP_LAMBDA_HANDLER : lambda_function.lambda_handler

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 following environment variables can be particularly useful:

• APPOPTICS_AGENT_ENABLED - set to false to disable the agent.
• APPOPTICS_DEBUG_LEVEL - to configure the logging level of the agent.
• APPOPTICS_TRANSACTION_NAME - a custom transaction name for the trace, used in place of the default or SDK-specified transaction name.

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.
• All settings for transaction-based filtering are not supported in the Lambda environment.

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, there should be a line in the logs that contains:

Invalid APPOPTICS_WRAP_LAMBDA_HANDLER:

Additional information follows that text.

If no errors are displayed, try setting the environment variable APPOPTICS_DEBUG_LEVEL=6. 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 Python agent.

Uninstall

Reverse the installation instructions to remove the AWS Lambda wrapper, removing the appoptics-python layer last. To disable the agent temporarily instead of uninstalling, define the environment variable APPOPTICS_AGENT_ENABLED=false.