AWS Lambda

Beta — This feature is subject to change.

The 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	`braintrust` on npm	`>=3.0.0`
Python	`braintrust` on PyPI	`>=0.27.0`

The extension does not support Braintrust’s Ruby, Go, Java, or .NET 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.

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:

arn:aws:lambda:us-west-2:872608195481:layer:braintrust-tracing-extension:<version>

For arm64 in us-west-2:

arn:aws:lambda:us-west-2:872608195481:layer:braintrust-tracing-extension-arm64:<version>

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.

Point the SDK at the extension

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

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.

Use a project ID

When initializing your logger, pass project_id directly when possible (to find your project ID, go to Settings > General). If your logger initialization passes only a project name, also set BRAINTRUST_PROJECT_ID so the extension knows which project to use.

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
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 / 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());
}

Verify traces in Braintrust

Invoke your Lambda function, then go to Logs. If the trace does not appear after a short delay, check the function’s CloudWatch logs for Braintrust Lambda extension errors.

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.

Infrastructure-as-code examples

Use the same layer and environment-variable configuration in your infrastructure code.

CloudFormation

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>

Terraform

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.

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.

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.

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.

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.

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

braintrust.permalink(span.export(), app_url="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.

AI providers

SDKs

Developer tools

Runtime environments

Compatibility

Setup

Extension configuration

Troubleshooting

Considerations

Resources

​Compatibility

​Setup

​Extension configuration

​Troubleshooting

​Considerations

​Resources

Compatibility

Setup

Extension configuration

Troubleshooting

Considerations

Resources