convez.ai
Skill
clayminer

braintrust-to-arize

clayminer/braintrust-to-arize

Ver no GitHub
InicialPluginScore · de 0 a 100

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-arize

1 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

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

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

  1. Export — reads spans from a Braintrust project via the BTQL API (POST /btql), paginating through the full history.
  2. Map — converts each Braintrust span into an OpenInference span: span kind, input/output, session/user identity, token counts, and model name.
  3. 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:

VariableWhere to get it
BRAINTRUST_API_KEYBraintrust → Settings → API Keys
BRAINTRUST_API_URLoptional; https://api-eu.braintrust.dev for EU
ARIZE_API_KEYArize → Space Settings → API Keys
ARIZE_SPACE_IDArize → Space Settings
ARIZE_PROJECT_NAMEdestination 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

FlagDescription
--list-projectsList 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)
--fullIgnore saved progress and re-migrate all spans
--limit <N>Cap the number of spans migrated
--dry-runExport + summarize only; write nothing to Arize
--no-batchSynchronous 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-stateDon'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 OTel BatchSpanProcessor queue and force-flushes every --flush-every traces (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 set OTEL_BSP_MAX_QUEUE_SIZE yourself.
  • 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

Ver o original no GitHub

Bom para

Relacionados