Skip to main content

​
Setup

In your project directory, give this prompt to your coding agent:
# Trace an AI application with Braintrust

Set up Braintrust tracing in this working directory. Follow these steps in order.

## Step 1: Set up Braintrust access

Check whether `BRAINTRUST_API_KEY` is set in the environment. If it is, skip this step.

If it isn't, ask the user to do the following, then stop and wait for the user to confirm. Do not guess, invent, or hardcode an API key.

1. Sign up or sign in at https://www.braintrust.dev/signup
2. Create an API key at https://www.braintrust.dev/app/~/configuration/org/api-keys
3. Set `BRAINTRUST_API_KEY` (the value starts with `sk-`) as an environment variable in the shell the user will run the app from, for example `export BRAINTRUST_API_KEY="sk-..."`. If the app loads a `.env` file, add it there instead. The user should not commit the key to version control.

Once the user confirms, continue. If the key isn't visible in your own environment, that's expected when the user set it in a separate shell or in a `.env` file that only the app loads. Don't block on it.

## Step 2: Detect the SDK

Look at the workspace and determine the right Braintrust SDK(s) to use. If the project spans more than one language, instrument each one. If the project is a monorepo, check the git root to get oriented, but only instrument applications in or below the current working directory.

## Step 3: Follow the SDK's configure tracing guide

For each SDK, read the matching page and follow its "Configure tracing" section. Do not follow any other Braintrust setup docs.

| SDK | Guide |
| --- | ------|
| Python | https://www.braintrust.dev/docs/sdks/python/install-and-instrument.md |
| TypeScript | https://www.braintrust.dev/docs/sdks/typescript/install-and-instrument.md |
| Go | https://www.braintrust.dev/docs/sdks/go/install-and-instrument.md |
| Java | https://www.braintrust.dev/docs/sdks/java/install-and-instrument.md |
| Ruby | https://www.braintrust.dev/docs/sdks/ruby/install-and-instrument.md |
| C# | https://www.braintrust.dev/docs/sdks/csharp/install-and-instrument.md |

## Step 4: Install and configure the SDK

- Install the SDK with the package manager the project already uses. Use the latest version: look it up and install that version rather than pinning to `latest`. Verify the install succeeded.
- Prefer auto-instrumentation over manual wrappers.
- Set the project name in the SDK initialization to the repository or application name. If the user has a specific Braintrust project in mind, use that instead.

## Rules

- Add only tracing. Do not add evals or anything else.
- Make only the code changes needed to add tracing. Do not run application code, and do not break or meaningfully modify existing code.
- Do not use the Braintrust CLI (`bt`).

Full documentation: https://www.braintrust.dev/docs/llms.txt
This sets up access to Braintrust, then uses a coding agent to inspect your project, install the Braintrust SDK, and configure tracing.No coding agent installed? Install and instrument manually.

​
Verify tracing

Run your app and make an AI call. A trace will show up in your Logs within seconds. Click into any trace to see the complete input and output, token counts, latency, cost, model configuration, and metadata.
If traces appear in Braintrust, you’ve successfully set up tracing.
If your traces don’t appear in Braintrust, see Troubleshoot below.

​
Troubleshoot

  • Verify BRAINTRUST_API_KEY is set and starts with sk- (echo $BRAINTRUST_API_KEY).
  • Check that the project name in your code matches the project in the UI.
  • Check your console for errors. Common causes are an invalid API key, network connectivity, or a firewall blocking api.braintrust.dev.
See the troubleshooting guide for your SDK: Python, TypeScript, Go, Java, Ruby, or C#.

​
Next steps