--- title: "Traceable Lambda runtime extension" slug: "lambda-runtime-extension" description: "Enable observability in AWS Lambda with the Traceable Lambda Runtime Extension. Capture event data, monitor API interactions, and enhance security with seamless integration. " updated: 2025-04-08T17:44:39Z published: 2025-04-08T17:44:39Z --- > ## Documentation Index > Fetch the complete documentation index at: https://traceabledocs.document360.io/llms.txt > Use this file to discover all available pages before exploring further. # 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](https://docs.aws.amazon.com/lambda/latest/dg/lambda-runtimes.html) - [Provided runtimes](https://docs.aws.amazon.com/lambda/latest/dg/runtimes-provided.html) > [!NOTE] > 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.![](https://cdn.document360.io/24f14f07-13d1-4684-8fae-6d8f811768ee/Images/Documentation/traceable_python_lambda_search_lambda(1).png) 3. Navigate to **Functions** from the Lambda page and click on the function name that you want to choose. ![](https://cdn.document360.io/24f14f07-13d1-4684-8fae-6d8f811768ee/Images/Documentation/traceable_python_lambda_select_function(2).png) 4. Click on the function name. The function page is displayed. 5. In the function settings page, click on **Layers**. ![](https://cdn.document360.io/24f14f07-13d1-4684-8fae-6d8f811768ee/Images/Documentation/traceable_python_lambda_click_layers(2).png) 6. Click **Add a Layer**. ![](https://cdn.document360.io/24f14f07-13d1-4684-8fae-6d8f811768ee/Images/Documentation/traceable_python_lambda_add_layers(1).png) 7. Select **Specify an ARN** and enter the appropriate ARN for the Traceable Runtime Extension layer: - **x86_64 Architecture**: ```plaintext arn:aws:lambda::031394183954:layer:traceableai-runtime-extension-x86_64:5 ``` - **ARM64 Architecture**: ```plaintext arn:aws:lambda::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: ```go 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: ```go 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: ```plaintext 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](https://docs.aws.amazon.com/lambda/latest/dg/runtimes-modify.html#runtime-wrapper). Please get in touch with Traceable support at [support@traceable.ai](mailto:support@traceable.ai) for further guidance on updating your OS-only Lambdas to use the Traceable Lambda Runtime Extension.