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

---

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 Variable	Description	Default Value
AWS_LAMBDA_EXEC_WRAPPER	Path to the Traceable runtime wrapper script	/opt/traceableai.sh
TA_ENDPOINT	URL of the Traceable Platform Agent (TPA), including scheme and port	http://tpa.host.or.ip:5442

Environment Variables

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

Environment Variable	Description	Default Value
TA_SERVICE_NAME	Name of the service reported to Traceable	Name of the Lambda function
TA_LOG_LEVEL	Log level for the runtime extension	info
TA_TIMEOUT_MS	Timeout for export requests to TPA (in milliseconds)	500
TA_MAX_BATCH_SIZE	In async mode the base batch size to use, modified based on jitter.	20
TA_MAX_BATCH_JITTER_SIZE	Used to modify the batch size to prevent load balanced concurrent exports	5
TA_CA_CERT_FILE	Path to a CA certificate file if TPA uses an untrusted certificate	None
TA_CA_CERT_B64	Base64-encoded CA certificate file, alternative to TA_CA_CERT_FILE	None
TA_INSECURE_SKIP_VERIFY	Disables TLS verification (only used if TA_CA_CERT is specified)	true
TA_EXPORT_FREQUENCY_MS	Export frequency (in milliseconds) if batch size is not met.	2000

---

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 [e-mail] for further guidance on updating your OS-only Lambdas to use the Traceable Lambda Runtime Extension.