> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/web-application-and-api-protection-waap/data-collection/serverless/traceable-lambda-runtime-extension.md).

# 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)

***

## 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.![](/files/UiAnX2W05ZNiO7wWISVE)
3. Navigate to **Functions** from the Lambda page and click on the function name that you want to choose. ![](/files/8P7b3dddrO8b3evC8HDV)
4. Click on the function name. The function page is displayed.
5. In the function settings page, click on **Layers**. ![](/files/VGEGxPNJX8BxETrU4h1z)
6. Click **Add a Layer**. ![](/files/f4y2Fv4ni63iNyINsq1E)
7. Select **Specify an ARN** and enter the appropriate ARN for the Traceable Runtime Extension layer:
   * **x86\_64 Architecture**:

     ```language-plaintext
     arn:aws:lambda:<aws-region>:031394183954:layer:traceableai-runtime-extension-x86_64:5
     ```
   * **ARM64 Architecture**:

     ```language-plaintext
     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:

```language-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:

```language-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:

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