> ## Documentation Index
> Fetch the complete documentation index at: https://docs.braintrust.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# AWS Lambda

> Reduce request-path logging latency from AWS Lambda functions with the Braintrust Lambda Extension

> [!WARNING]
>
> The Braintrust Lambda extension is in [public preview](https://docs.braintrust.dev/feature-lifecycle.md) and can change before reaching general availability.

The [Braintrust Lambda extension](https://github.com/braintrustdata/braintrust-lambda-extension) runs alongside your AWS Lambda function and accepts Braintrust trace batches locally, reducing the amount of time that the Braintrust SDK's `flush()` method spends in the request path.

Use the extension when your Lambda function already logs traces to Braintrust, calls the SDK's `flush()` method before returning, and needs to reduce trace delivery latency.

## Compatibility

The extension supports project-log tracing from these Braintrust SDKs:

| SDK | Package | Supported versions |
| - | - | - |
| [TypeScript / JavaScript](https://github.com/braintrustdata/braintrust-sdk-javascript) | [`braintrust`](https://www.npmjs.com/package/braintrust) on npm | `>=3.0.0` |
| [Python](https://github.com/braintrustdata/braintrust-sdk-python) | [`braintrust`](https://pypi.org/project/braintrust/) on PyPI | `>=0.27.0` |

The extension does not support Braintrust's [Ruby](https://github.com/braintrustdata/braintrust-sdk-ruby), [Go](https://github.com/braintrustdata/braintrust-sdk-go), [Java](https://github.com/braintrustdata/braintrust-sdk-java), or [.NET](https://github.com/braintrustdata/braintrust-sdk-dotnet) SDKs.

## Setup

Start with a Lambda function that already logs traces to Braintrust with a supported SDK. Add the extension, point the SDK at the local listener, and keep `flush()` in your handler.

**1. Attach the extension layer**

Add the published layer ARN for your function's AWS region and architecture. Replace `<version>` with the version from the Braintrust Lambda Extension release.

For `x86_64` in `us-west-2`:

```text theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
arn:aws:lambda:us-west-2:872608195481:layer:braintrust-tracing-extension:<version>
```

For `arm64` in `us-west-2`:

```text theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
arn:aws:lambda:us-west-2:872608195481:layer:braintrust-tracing-extension-arm64:<version>
```

> [!NOTE]
>
> The extension layer is published only in `us-west-2`. For container-image Lambda functions, copy the extension executable into `/opt/extensions/braintrust-lambda-extension` instead of attaching a layer.

**2. Point the SDK at the extension**

Set these environment variables on the Lambda function so Braintrust trace data goes to the extension:

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
BRAINTRUST_APP_URL=http://127.0.0.1:49891
BRAINTRUST_API_URL=http://127.0.0.1:49891
BRAINTRUST_PROJECT_ID=<project-id>
```

The extension uses the API key from inbound SDK requests. You do not need to set `BRAINTRUST_API_KEY` as a Lambda environment variable if your application already provides the key to the SDK. You can set `BRAINTRUST_API_KEY` on the Lambda function as a fallback, but passing credentials through the SDK keeps the key out of the function configuration.

**3. Use a project ID**

When initializing your logger, pass `project_id` directly when possible (to find your project ID, go to \*\* Settings\*\* > [\*\* Project\*\*](https://www.braintrust.dev/app/~/configuration/general)). If your logger initialization passes only a project name, also set `BRAINTRUST_PROJECT_ID` so the extension knows which project to use.

**4. Flush at the end of the handler**

Keep the explicit `flush()` call at the end of your handler. With the extension attached, `flush()` waits for a local handoff instead of waiting for remote Braintrust delivery.

```python Python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
# Python
import braintrust

logger = braintrust.init_logger(project_id="<project ID>")

def handler(event, context):
    try:
        with logger.start_span(name="request") as span:
            span.log(input=event)
            return {"statusCode": 200}
    finally:
        braintrust.flush()
```

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
// TypeScript / JavaScript
import { initLogger, flush } from "braintrust";

const logger = initLogger({ projectId: "<project ID>" });

export async function handler(event: unknown) {
  return await logger
    .traced(
      async (span) => {
        span.log({ input: event });
        return { statusCode: 200 };
      },
      { name: "request" },
    )
    .finally(() => flush());
}
```

**5. Verify traces in Braintrust**

Invoke your Lambda function, then go to [\*\* Logs\*\*](https://www.braintrust.dev/app/~/logs). If the trace does not appear after a short delay, check the function's CloudWatch logs for Braintrust Lambda extension errors.

**6. Validate latency improvement**

Time `flush()` before and after attaching the extension. If you track Lambda performance, also compare function `Duration`, which can include extension work after the handler returns.

> [accordion] Infrastructure-as-code examples
>
> Use the same layer and environment-variable configuration in your infrastructure code.
>
> ```yaml CloudFormation theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
> Resources:
>   SearchFunction:
>     Type: AWS::Lambda::Function
>     Properties:
>       Architectures:
>         - x86_64
>       Layers:
>         - arn:aws:lambda:us-west-2:872608195481:layer:braintrust-tracing-extension:<version>
>       Environment:
>         Variables:
>           BRAINTRUST_APP_URL: http://127.0.0.1:49891
>           BRAINTRUST_API_URL: http://127.0.0.1:49891
>           BRAINTRUST_PROJECT_ID: <project-id>
> ```
>
> ```hcl Terraform theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
> resource "aws_lambda_function" "search" {
>   architectures = ["x86_64"]
>   layers = [
>     "arn:aws:lambda:us-west-2:872608195481:layer:braintrust-tracing-extension:<version>",
>   ]
>
>   environment {
>     variables = {
>       BRAINTRUST_APP_URL = "http://127.0.0.1:49891"
>       BRAINTRUST_API_URL = "http://127.0.0.1:49891"
>       BRAINTRUST_PROJECT_ID = "<project-id>"
>     }
>   }
> }
> ```

## Extension configuration

The extension supports these environment variables for local intake, trace delivery, and buffering.

| Variable | Default | Purpose |
| - | - | - |
| `BRAINTRUST_LAMBDA_EXTENSION_PORT` | `49891` | Port where the extension listens for SDK requests from the Lambda function. |
| `BRAINTRUST_LAMBDA_SPOOL_DIR` | `/tmp/braintrust-lambda-extension` | Local directory where the extension stores trace batches before delivery to Braintrust. |
| `BRAINTRUST_LAMBDA_UPSTREAM_URL` | Unset | Override the Braintrust data-plane URL that receives delivered traces. |
| `BRAINTRUST_LAMBDA_UPSTREAM_APP_URL` | `https://www.braintrust.dev` | Override the app/control-plane URL used for API-key login. Leave the default for most deployments. |
| `BRAINTRUST_ORG_NAME` | Unset | Select the Braintrust organization when an API key belongs to more than one organization. |
| `BRAINTRUST_LAMBDA_REQUEST_TIMEOUT_SECONDS` | `1.5` | Timeout for each request the extension sends to Braintrust. |
| `BRAINTRUST_LAMBDA_POST_RUNTIME_TIMEOUT_SECONDS` | `2` | How long the extension can keep trying to deliver traces after the handler returns. |
| `BRAINTRUST_LAMBDA_FSYNC` | `1` | Write each trace batch durably to local storage before telling the SDK it was received. |
| `BRAINTRUST_LAMBDA_DISABLE_SDK_OVERFLOW` | `1` | Prevent the SDK from sending oversized payloads to the unsupported `/logs3/overflow` endpoint. Leave enabled unless Braintrust support recommends changing it. |

To further reduce latency, you can adjust the way the SDK hands traces to the extension:

* Set `BRAINTRUST_SYNC_FLUSH=1` so `flush()` sends queued traces to the local extension itself instead of coordinating with the SDK's background publisher.
* Set `BRAINTRUST_NUM_RETRIES=0` to skip SDK retries for the local handoff. After the extension receives a payload, the extension handles retries to Braintrust.

Leave SDK retries enabled if you want the SDK to retry the handoff before the extension has accepted the payload.

## Troubleshooting

Use Lambda logs and Braintrust logs together when checking the extension.

> [accordion] Traces do not appear in Braintrust
>
> * Verify the function has the extension layer attached for the correct architecture.
> * Verify `BRAINTRUST_APP_URL` and `BRAINTRUST_API_URL` are set to `http://127.0.0.1:49891`.
> * Verify your function still calls `flush()` before returning.
> * Verify the Lambda execution environment allows outbound HTTPS traffic. If the function is attached to a VPC, confirm the selected subnets have internet access.

> [accordion] Logger initialization fails
>
> * Pass `project_id` directly to your logger when possible.
> * If your logger initialization uses a project name, set `BRAINTRUST_PROJECT_ID` on the Lambda function.

> [accordion] flush() still takes too long
>
> * Confirm the SDK is pointing at the local extension, not the remote Braintrust data plane.
> * Review the SDK settings in [extension configuration](#extension-configuration).

> [accordion] Large payloads fail
>
> The SDK can send oversized payloads to a separate upload endpoint, `/logs3/overflow`. The extension does not support that endpoint.
>
> By default, `BRAINTRUST_LAMBDA_DISABLE_SDK_OVERFLOW=1` prevents the SDK from using `/logs3/overflow`, so payloads stay on the upload path the extension can receive and retry. Leave this setting enabled unless Braintrust support recommends changing it.
>
> This setting keeps payloads on the extension-supported upload path, but it does not guarantee that every oversized payload can be delivered.

> [accordion] Generated Braintrust links point to localhost
>
> The extension setup points `BRAINTRUST_APP_URL` at `http://127.0.0.1:49891`, so SDK helpers that build Braintrust UI links from `BRAINTRUST_APP_URL` can return localhost URLs.
>
> Python and JavaScript/TypeScript support passing the Braintrust app URL when generating a permalink:
>
> ```python Python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
> braintrust.permalink(span.export(), app_url="https://www.braintrust.dev")
> ```
>
> ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
> import { permalink } from "braintrust";
>
> const link = await permalink(await span.export(), {
>   appUrl: "https://www.braintrust.dev",
> });
> ```

## Considerations

When using the extension, keep the following things in mind:

* A successful `flush()` confirms that the extension accepted trace batches in the Lambda execution environment, not that Braintrust has durably ingested them.
* The extension retries delivery while the execution environment is active or reused for a later warm invocation, but undelivered batches can be lost if AWS destroys the execution environment before delivery succeeds.
* Extension work after the handler returns can still contribute to Lambda `Duration` and billing metrics.
* Attaching the extension layer adds cold-start work.
* The extension only supports trace logging from a project logger. It does not proxy prompt loading, datasets, attachments, experiment logging, or arbitrary Braintrust API calls.
* Keep the default `BRAINTRUST_LAMBDA_DISABLE_SDK_OVERFLOW=1` setting unless Braintrust support recommends changing it. The extension does not support the SDK's separate upload path for oversized log payloads.

## Resources

* [Trace application logic](https://docs.braintrust.dev/instrument/trace-application-logic.md)
* [View logs](https://docs.braintrust.dev/observe/view-logs.md)
* [GitHub: Braintrust Lambda Extension](https://github.com/braintrustdata/braintrust-lambda-extension)
* [AWS Lambda extensions documentation](https://docs.aws.amazon.com/lambda/latest/dg/lambda-extensions.html)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.