Monitoring AWS Lambda with AWS Lambda agent

Instana provides native tracing for AWS Lambda that replaces the (deprecated) AWS X-Ray integration. With the AWS Lambda agent, Instana monitors the AWS Lambda functions. The agent is installed as a layer in the AWS Lambda function. When you deploy the function, the agent starts collecting metrics and tracing data from the function and sends the collected data to the Instana backend.

For other supported AWS services, see the AWS documentation.

Benefits of Instana native tracing

Native tracing of AWS Lambda functions provides several advantages over X-Ray-based tracing:

  • End-to-end visibility: The execution Lambda functions now seamlessly correlate with the tracing of other components that are monitored by Instana. Calls from hosts processes to serverless and back are now linked, correlated, and analyzed as such without any additional steps.
  • Ease of analysis: Instana can now provide rich performance analysis between specific versions of the same AWS Lambda function.
  • Reduces cost: Instana completely eliminates the need of pulling costly X-Ray data from AWS.
  • Automatic and deep trace visibility: Instana can trace every invocation of your Lambda functions rather than manually instrument them with X-Ray.

Supported runtimes

AWS sensor

The AWS sensor for Lambda monitoring collects version details and metrics for all your Lambda functions, irrespective of the runtime.

AWS Lambda native tracing

AWS Lambda native tracing is available for the following runtimes:

  • Go 1.x using Go 1.8 or later
  • Java 8a12 and Java 11
  • Node.js 18.x, 16.x, 14.x, 12.x, and 10.x
  • Python 3.9, 3.8, and 3.7
  • Ruby 2.7

Setting up Lambda monitoring

To set up Instana for monitoring AWS Lambda functions, complete the following steps:

  1. Configure the AWS sensor for Lambda monitoring.
  2. Install the Instana tracer in your Lambda function.
  3. Optional: Configure additional settings for Instana Lambda tracers.

Configuring the AWS sensor for Lambda monitoring

To configure the Instana AWS sensor:

For more information, see Configuring the AWS sensor for Lambda monitoring.

Installing the Instana tracer in the AWS Lambda function

To install the Instana tracer in the AWS Lambda function, see the installation instructions for the following specific runtimes:

Optional: Configuring additional settings for the Instana Lambda tracers

You can configure the following optional environment variables that are generally supported in native Lambda tracing:

Environment variables Meaning
INSTANA_TIMEOUT Set timeout for the HTTP requests that report data to the Instana backend.
INSTANA_ENDPOINT_PROXY Set this variable to http://my-proxy.tld or http://user:password@my-proxy.tld to route the reporting of data to the Instana backend over an HTTP or HTTPS proxy (supported in Node.js, not in Python).
INSTANA_EXTRA_HTTP_HEADERS Set this variable to a semicolon-separated list of HTTP header names (for trigger types API gateway with Lambda proxy integration or application load balancer) to capture HTTP headers.
INSTANA_SERVICE_NAME Define the custom service name.
INSTANA_LOG_LEVEL Set the log level for the Instana package. Possible values are debug, info, warn, and error (default: info).
INSTANA_DEBUG Set this variable to any value to set the log level to debug.
INSTANA_DISABLE_CA_CHECK Set this variable to true to disable verifying the server certificate against the list of certificate authorities (CA) baked into Lambda runtime when it connects to the Instana backend. (Available for @instana/aws-lambda@1.93.0/layer version 25 and later)

CAUTION: Do not set INSTANA_DISABLE_CA_CHECK to true unless you use Instana on premises and are unable to operate the Instana backend with a certificate with a known root CA. Enabling this variable makes your Lambda vulnerable to MITM attacks for this connection.

Viewing Lambda function configurations, metrics, versions, and triggers

You can view all information about your Lambda functions through Instana.

To view the version details and metrics for Lambda functions, complete the following steps:

  1. In the sidebar of the Instana UI, select Infrastructure.
  2. Click a specific monitored Lambda function.

You can see a host dashboard with all the collected metrics and Lambda versions. For more information about the Lambda function versions details and metrics, see Lambda configurations, metrics, versions, and triggers.

Enabling alerts for cold starting or timeouts

You can configure Smart Alerts for excessive cold starts or timeouts on your Lambda functions. To configure a smart alert, go to the application perspective that contains the Lambda functions you want an alert on, and add a smart alert:

  1. From the navigation panel in the Instana UI, click Applications.
  2. Select your application.
  3. Click Add Smart Alert.
  4. Click Switch to Advanced Mode.
  5. In the Select Services/Endpoints field under the Scope section, add a filter for Cloud Function As A Service > Cold Start is true or Cloud Function As A Service > Suspected Timeout is true.
  6. In the Selected blueprint field under the Trigger section, select Throughput.
  7. In the threshold section, select a threshold value that fits your use case. Use 1 to include every occurrence or a higher value to have the rule violated on a particular number of cold starts or timeouts.
  8. Use the Time Threshold settings to fine-tune the alerting behavior.


Using Lambda extension

NodeJS layer version 71 and later include a Lambda extension.

This extension can improve performance of monitored Lambda functions by separating the process of sending data to the Instana backend. To take advantage of these performance improvements, upgrade the Instana layer to a version that includes the extension.

Internally, the extension works with the language library to buffer and proxy all the requests to the Instana backend. Under normal operation, the extension does not extend the lifetime of the Lambda function. The lifetime is extended only during the following instances:

  • A shutdown request to ensure all data that is held in the buffer to the backend are cleared.
  • A situation when the Lambda function crashes, and stops sending spans. Wait for 3 seconds to see whether the root span is sent before you wait for the next invocation.

If you like to disable the use of the extension, set INSTANA_DISABLE_LAMBDA_EXTENSION to TRUE in your function's environment.

Performance and runtime considerations for Lambda monitoring

Artifact size

Lambda monitoring by Instana increases the size of the deployed artifact by the size of the language's specific layer or library. To get the size of a particular layer, use the following shell commands:

   aws lambda get-layer-version --layer-name <layer_arn> --version-number <target_version> | jq .Content.Location | xargs -L 1 curl --output
unzip -l

Performance impact

The performance impact of monitoring a Lambda function with Instana is primarily driven by the time that is taken for the Lambda function to communicate with the Instana backend. At the end of each execution, the Instana provided library makes a blocking call to either Instanas AWS Lambda extension or your Instana tenant unit to report the result of the execution.

For functions that use the Lambda extension, this process takes place in the background and allows the monitored function to return its response as soon as the monitored code is ready.

For functions that are not using the Lambda extension, this process blocks the reporting of the result of the execution until the data are sent to your tenant unit.

For more information, see the extension blog post.