Skip to main content

​
1. Sign up

If you don’t have a Braintrust account, sign up for free at braintrust.dev.

​
2. Instrument your app

In your project directory, run the Braintrust CLI setup script: 
curl -fsSL https://braintrust.dev/cli/setup.sh | sh
The CLI uses your preferred agent to detect your project language, install the Braintrust SDK, and instrument your code. If you don’t have a Braintrust API key set in your environment, it creates one for you.

​
3. View traces

Once instrumented, your app logs traces to Braintrust for every AI call. To view your traces in the Braintrust UI, open your project and go to the Logs page. Click into any trace to see:
  • Complete input prompt and model output
  • Token counts, latency, and cost
  • Model configuration (temperature, max tokens, etc.)
  • Request and response metadata
This is the value of observability — you can see every request, identify issues, and understand how your application behaves in production.

​
Instrument with wrap functions

To learn how to instrument your code using explicit wrap functions, see Trace LLM calls.

​
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 you’re looking at in the UI
  • Check your console for error messages — common issues are invalid API key, network connectivity, or firewall blocking api.braintrust.dev
  • Run with node --import braintrust/hook.mjs (not --loader, which is deprecated)
  • Verify braintrust is installed (npm list braintrust)
  • Call initLogger() with a project name before making any LLM calls
  • Verify BRAINTRUST_API_KEY is set in your environment
  • Using a bundler (Vite, Webpack, esbuild, Rollup)? Use the bundler plugin instead of --import. See TypeScript SDK documentation
  • Requires Node.js 18.19.0+ or 20.6.0+ for --import flag support (node --version)
  • Call braintrust.auto_instrument() at the start of your application, before any AI library imports or client creation
  • Verify BRAINTRUST_API_KEY is set in your environment
  • Ensure your Gemfile has gem "braintrust", require: "braintrust/setup" (note the require: option)
  • Your application must load Bundler with require 'bundler/setup' and Bundler.require (default in Rails, may need to be added in Sinatra/Rack)
  • Verify BRAINTRUST_API_KEY is set in your environment
  • Ensure you have a go.mod file (go mod init your-project-name if not)
  • Verify Orchestrion is installed (orchestrion version). If not, reinstall with go install github.com/DataDog/orchestrion@v1.6.1
  • Ensure orchestrion.tool.go exists in your project root with the correct imports
  • Build with orchestrion go build — regular go build won’t instrument your code
  • Verify BRAINTRUST_API_KEY is set in your environment
  • Requires Go 1.26 or later (go version)

​
Next steps