Traceable Lambda runtime extension

The Traceable Lambda Runtime Extension enables data collection for AWS Lambda invocations by capturing the event data passed to the Lambda function and its response. It currently supports capturing Lambda events from:

• API Gateway HTTP v1

• API Gateway HTTP v2

• REST APIs

The extension uses wrapper scripts on all native Lambda runtimes except for the provided family. For a complete list of wrapper script compatible runtimes, refer to the AWS documentation:

• Lambda runtimes - AWS Lambda

• Provided runtimes

Note

The provided images are supported but require some code modifications.

Before you begin

Before proceeding with the setup, ensure you have:

• Access to an AWS account with appropriate permissions to modify Lambda functions.

• An existing Lambda function where you want to enable the Traceable Runtime Extension.

• Knowledge of your AWS region, as you will need to specify the correct Amazon Resource Name (ARN) for your Lambda layer.

Configuration

Adding the Layer

1. Log in to your AWS account.

2. Search for Lambda in the search bar.

3. Navigate to Functions from the Lambda page and click on the function name that you want to choose.

4. Click on the function name. The function page is displayed.

5. In the function settings page, click on Layers.

6. Click Add a Layer.

7. Select Specify an ARN and enter the appropriate ARN for the Traceable Runtime Extension layer:

   • x86_64 Architecture:

     arn:aws:lambda:<aws-region>:031394183954:layer:traceableai-runtime-extension-x86_64:5

   • ARM64 Architecture:

     arn:aws:lambda:<aws-region>:031394183954:layer:traceableai-runtime-extension-arm64:5

Once the layer is added, you must configure the following mandatory environment variables on the Lambda function:

Environment Variables

The following table lists additional configuration options and their default values:

AWS OS-only Runtime Support

In AWS Lambda, "OS-only" runtimes—such as provided.al2 and provided.al2023 — are custom runtimes based solely on Amazon Linux. These do not include AWS-managed language runtimes and do not support lifecycle hooks like AWS_LAMBDA_EXEC_WRAPPER. To enable Traceable's Lambda Runtime Extension in these environments, you must manually configure the runtime to forward events to the extension by modifying the AWS_LAMBDA_RUNTIME_API variable within your function code. This manual redirection achieves the same outcome as the wrapper script does in natively supported runtime.

Example: Updating a Go Lambda Function

Consider the following standard Go Lambda function:

package main

import (
	"context"
	"os"

	"github.com/aws/aws-lambda-go/events"
	"github.com/aws/aws-lambda-go/lambda"
)

func Handler(ctx context.Context, request events.APIGatewayProxyRequest) (events.APIGatewayProxyResponse, error) {
	return events.APIGatewayProxyResponse{
		StatusCode: 200,
		Body:       request.Body,
	}, nil
}

func main() {
	lambda.Start(Handler)
}

To integrate with the Traceable Lambda Runtime Extension, modify the main() function as shown below:

func main() {
	if os.Getenv("TRACEABLE_ENABLED") == "true" {
		err := os.Setenv("AWS_LAMBDA_RUNTIME_API", "127.0.0.1:9009")
		if err != nil {
			print("Error setting AWS_LAMBDA_RUNTIME_API, traceable lambda runtime extension will not be invoked", err)
		}
	}

	lambda.Start(Handler)
}

The Traceable Runtime Extension listens on 127.0.0.1:9009 by default. This port can be changed by setting the TRACEABLE_LISTENER_PORT environment variable.

You must also set the following environment variable in your Lambda configuration:

TRACEABLE_ENABLED=true

This instructs the Go Lambda SDK to forward requests to the Traceable proxy, which in turn invokes the Lambda Runtime API. This manual setup replicates what AWS_LAMBDA_EXEC_WRAPPER automates in supported runtimes.

For more information, see the AWS documentation on modifying runtime behavior.

Please get in touch with Traceable support at support@traceable.ai for further guidance on updating your OS-only Lambdas to use the Traceable Lambda Runtime Extension.