Setup Install Braintrust alongside the Flue runtime, CLI, and Hono, then set your API keys. Install `@flue/runtime` and `@flue/cli` together so their versions stay aligned. ```bash pnpm theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} pnpm add braintrust @flue/runtime @flue/cli hono ``` ```bash npm theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} npm install braintrust @flue/runtime @flue/cli hono ``` ```bash title=".env" theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} BRAINTRUST_API_KEY= ANTHROPIC_API_KEY= ``` Auto-instrumentation To trace Flue workflows without modifying your application code, initialize Braintrust in your Flue app entry, then run your app with Braintrust’s import hook to patch the Flue runtime. Flue loads its app entry from `src/app.ts`, discovered through a `flue.config.ts` at the project root. Running `flue init --target node` generates this config: ```ts title="flue.config.ts" theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} import { defineConfig } from "@flue/cli/config"; export default defineConfig({ target: "node" }); ``` Call `initLogger` at the top of the app entry, before the Hono app is created, so Braintrust is ready before any workflow runs. `flue()` (from `@flue/runtime/routing`) returns the routes you mount with `app.route("/", flue())`: ```ts title="src/app.ts" theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} import { flue } from "@flue/runtime/routing"; import { initLogger } from "braintrust"; import { Hono } from "hono"; initLogger({ projectName: "my-flue-app", // Replace with your project name apiKey: process.env.BRAINTRUST_API_KEY, }); const app = new Hono(); app.route("/", flue()); export default app; ``` A workflow lives in `src/workflows/` and is named after its file, so this is the `hello` workflow. Its exported `run` function receives the `--payload` you pass at run time. This one defines an agent and sends it the question from the payload: ```ts title="src/workflows/hello.ts" theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} import { createAgent, type FlueContext } from "@flue/runtime"; const assistant = createAgent(() => ({ model: "anthropic/claude-haiku-4-5", instructions: "Answer in one short sentence.", })); export async function run({ init, payload }: FlueContext<{ question: string }>) { const harness = await init(assistant); const session = await harness.session(); const response = await session.prompt(payload.question); return { answer: response.text }; } ``` Run the `hello` workflow. The import hook patches the Flue runtime so the run is traced, and `--payload` is passed to your workflow’s `run` function: ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} NODE_OPTIONS="--import braintrust/hook.mjs" flue run hello --target node --payload '{"question":"What is the capital of France?"}' ``` The auto-instrumentation example uses plain JavaScript so `node --import` can run the file directly. The Braintrust APIs work the same in TypeScript projects — compile your TypeScript to JavaScript, then run the compiled file with the import hook. If you’re using a bundler, see [Trace LLM calls](/instrument/trace-llm-calls#auto-instrumentation) for plugin and loader setup. Manual instrumentation To trace Flue manually, register Braintrust’s observer yourself by passing `braintrustFlueObserver` to Flue’s `observe()` in your app entry. Use the same `flue.config.ts` and `src/workflows/hello.ts` as above; only the app entry changes, to register the observer. ```ts title="src/app.ts" theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} import { flue } from "@flue/runtime/routing"; import { observe } from "@flue/runtime"; import { braintrustFlueObserver, initLogger } from "braintrust"; import { Hono } from "hono"; initLogger({ projectName: "my-flue-app", // Replace with your project name apiKey: process.env.BRAINTRUST_API_KEY, }); observe(braintrustFlueObserver); const app = new Hono(); app.route("/", flue()); export default app; ``` Run your workflow normally — no import hook needed, since the observer is the instrumentation: ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} flue run hello --target node --payload '{"question":"What is the capital of France?"}' ``` What Braintrust traces Braintrust patches the Flue runtime and captures: * Workflow run spans (`workflow:`), with the run input and result. * Operation spans (`flue.prompt`, `flue.skill`, and `flue.compact`) for agent operations. * LLM turn spans (`llm:`), with messages as input, the model and request parameters as metadata, and the response as output. * Tool call spans (`tool:`), with the tool arguments as input and the tool result as output. * Subtask spans (`task:`), with the subtask prompt as input and its result as output. * Context compaction spans (`compaction:`), with message counts before and after compaction. * Token usage and cost metrics (prompt, completion, total, cached, cache-creation, and estimated cost) on LLM turns. * Errors captured on every span. Resources * [Flue documentation](https://flueframework.com/) * [@flue/runtime on npm](https://www.npmjs.com/package/@flue/runtime)