braintrust-to-arize
clayminer/braintrust-to-arize
Migrate LLM trace data from Braintrust into Arize, preserving trace structure and original timestamps. CLI + Claude Code skill.
Instalação
npx convez-ai clayminer/braintrust-to-arize1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
braintrust-to-arize
Migrate your trace and span data from Braintrust into Arize — preserving the full trace hierarchy and the original timestamps of every span. Built for teams switching their LLM observability from Braintrust to Arize.
It ships as both a standalone Python CLI and a Claude Code skill, so you can run it yourself or just say "migrate my Braintrust traces to Arize."
How it works
- Export — reads spans from a Braintrust project via the BTQL API
(
POST /btql), paginating through the full history. - Map — converts each Braintrust span into an OpenInference span: span kind, input/output, session/user identity, token counts, and model name.
- Backfill — writes the spans into Arize over OpenTelemetry using each span's original start/end time, rebuilding the parent/child trace tree.
Quickstart
git clone <this-repo> && cd braintrust-to-arize
pip install -r requirements.txt
cp .env.example .env # then fill in your keys
Fill in .env:
| Variable | Where to get it |
|---|---|
BRAINTRUST_API_KEY | Braintrust → Settings → API Keys |
BRAINTRUST_API_URL | optional; https://api-eu.braintrust.dev for EU |
ARIZE_API_KEY | Arize → Space Settings → API Keys |
ARIZE_SPACE_ID | Arize → Space Settings |
ARIZE_PROJECT_NAME | destination project name (created on first write) |
Then:
# See which Braintrust projects you have
python migrate.py --list-projects
# Preview what would migrate (no writes)
python migrate.py --project my-project --dry-run
# Migrate for real
python migrate.py --project my-project --arize-project my-arize-project
# Later, after logging more traces — migrates ONLY the new ones
python migrate.py --project my-project --arize-project my-arize-project
Options
| Flag | Description |
|---|---|
--list-projects | List Braintrust projects and exit |
--project <name|id> | Source Braintrust project |
--arize-project <name> | Destination Arize project (default: ARIZE_PROJECT_NAME) |
--since <ISO8601> | Only migrate spans created after this time (overrides saved progress) |
--full | Ignore saved progress and re-migrate all spans |
--limit <N> | Cap the number of spans migrated |
--dry-run | Export + summarize only; write nothing to Arize |
--no-batch | Synchronous span export (slower, safer for tiny runs) |
--flush-every <N> | Force-flush the export queue every N traces during batch writes (default 25; 0 disables) |
--no-state | Don't read or write the incremental progress file |
Incremental migration (only net-new traces)
By default the tool is incremental. After each successful migration it records a
high-water mark — the newest span timestamp it sent — in a local
.bt2arize_state.json file, keyed by source project → destination project. The next
plain re-run resumes from that mark and migrates only traces logged since, so you
can safely run it repeatedly (e.g. on a schedule) without creating duplicates.
# First run — migrates everything, saves progress
python migrate.py --project my-project --arize-project prod-traces
# Log more traces in Braintrust, then run again — only the new traces go over
python migrate.py --project my-project --arize-project prod-traces
# → "Incremental: resuming from last run — spans created after 2026-06-11T17:35:41.577Z."
Controls:
--full— ignore the saved mark and re-migrate the entire project history. (Note: this re-sends already-migrated traces; because OpenTelemetry assigns fresh span IDs, they appear as duplicates in Arize.)--since <ISO8601>— migrate from an explicit timestamp instead of the saved mark.--no-state— ignore and don't update the progress file (every run behaves like a one-off full export).
The progress file is per-checkout and git-ignored. Each source → destination pair is tracked separately, so migrating one Braintrust project into two Arize projects keeps independent marks.
Use with Claude Code
This repo includes a skill at .claude/skills/migrate-braintrust-to-arize/. With the
repo open in Claude Code, just ask:
migrate my Braintrust traces to Arize
Claude will check your .env, list your projects, run a dry run, then perform the
migration and help you verify it.
Notes & limitations
- Rate limits — Braintrust's BTQL API permits ~20 requests/minute. The client retries automatically on HTTP 429 with backoff, so large exports may pause briefly.
- Span IDs — trace grouping and parent/child structure are preserved, but literal Braintrust span IDs are not carried over (OpenTelemetry assigns its own). This has no effect on how traces render in Arize.
- Retention — Arize enforces a per-space data-retention window. Spans older than that window may ingest successfully but not be queryable. Check your retention before a large historical backfill.
- Volume / scale — export uses keyset pagination (on Braintrust's
_pagination_key), so it pulls the full history exactly regardless of size. On the write side the tool enlarges the OTelBatchSpanProcessorqueue and force-flushes every--flush-everytraces (default 25) so the buffer can't overflow and silently drop spans. Validated at 500 traces / 3,000 spans with an exact span count match in Arize. For very large migrations you can still raise--flush-every's cadence or setOTEL_BSP_MAX_QUEUE_SIZEyourself. - Scope (v1) — migrates project trace logs (spans). Scores/feedback and datasets/experiments are not yet migrated.
Development
python -m unittest discover -s tests
Tests run fully offline against a captured fixture of real Braintrust spans — no network or credentials required.
License
MIT