Quickstart

1. Preview with a dry run

Start here. --dry-run resolves the runs, enumerates their metric keys, and prints the names it would write — without creating anything or logging a single point:

metrana migrate wandb \
  --entity my-team --project sweeps \
  --workspace my-workspace \
  --dry-run

Dry run — nothing will be logged
  my-team/sweeps/a1b2c3 -> wandb-sunny-sweep (14 keys)
    renamed 'accuracy (%)' -> 'accuracy_{%}'
    renamed 'grad_norm[0]' -> 'grad_norm{0}'
  my-team/sweeps/d4e5f6 -> wandb-brave-sweep (14 keys)

This is the cheapest way to check two things before committing data: the run names you will end up with, and any metric renames or collisions. Both are explained in Name translation.

2. Migrate

Drop --dry-run:

metrana migrate wandb \
  --entity my-team --project sweeps \
  --workspace my-workspace

Runs land in a project named after the source project. Send them somewhere else with --to-project:

metrana migrate wandb \
  --entity my-team --project sweeps \
  --workspace my-workspace --to-project sweeps-imported

3. Migrate a subset

A single run, or several, by source run id:

metrana migrate wandb \
  --entity my-team --project sweeps --workspace my-workspace \
  --run a1b2c3 --run d4e5f6

Or a slice of the project, using the source tracker’s own query filter:

metrana migrate wandb \
  --entity my-team --project sweeps --workspace my-workspace \
  --filter '{"state": "finished"}'

4. If it stops

Run exactly the same command again. Each series continues from the last step already in Metrana, so completed work is not repeated and nothing is duplicated:

2026-08-19T09:14:02.118374Z  INFO metrana.cli: [1/3] my-team/sweeps/a1b2c3 -> wandb-sunny-sweep resumed, 0 points

Migration summary
  runs migrated:     3 (3 resumed)

Nothing needs to be cleaned up first, and it does not have to be the same machine.

Precision

Float points migrate at float32 by default, which is the SDK’s own default and covers any real metric signal at half the storage. Sources typically store float64, so the command says so on every run:

2026-08-19T09:14:01.884201Z  WARNING metrana.cli: Migrating float points at float32 (the SDK default).
WandB stores float64; pass --float64 to migrate at full precision at twice the storage.

Pass --float64 for a bit-faithful copy. Choose before you start: the flag sets the run’s storage precision, so switching it partway through a resumed migration leaves one run holding both.

Integer-valued series are the exception, and need no flag. A key whose points arrive as whole numbers — step counters, epochs, samples or tokens seen — migrates at float64 whatever --float64 says, because float32 starts rounding integers above 2^24 (16,777,216) and a counter that large is ordinary. The precision is decided per series from its first point, so a run can hold float32 metrics and float64 counters side by side.

Watching it run

Runs migrate concurrently, so instead of each one printing as it goes, every worker reports the stage it has reached and the parent logs them in one place. Each run logs when it starts, and every 30 seconds a heartbeat says what is still in flight and which run has been in its stage longest:

2026-08-19T09:14:02.118374Z  INFO metrana.migrate.progress: start my-team/sweeps/a1b2c3 -> wandb-sunny-sweep
2026-08-19T09:15:32.902551Z  INFO metrana.migrate.progress: 8 in flight (5 streaming, 3 initializing); longest my-team/sweeps/a1b2c3 initializing for 90s

The same run and stage repeating across heartbeats is how a migration that has stopped moving tells you so. Two flags tune this:

metrana migrate wandb ... --heartbeat 5    # in-flight status every 5s (0 turns it off)
metrana migrate wandb ... --verbose        # every stage of every run, not just the starts

Output goes through loguru in the SDK’s own format, so it interleaves cleanly with the SDK’s and the ingestion engine’s own lines. See Watching a migration that is still running for what each stage means and what a stall in one is telling you.

Tuning throughput

--flush-every sets how many source rows are migrated between durability checkpoints (default 50000). Each checkpoint blocks until everything before it is acknowledged, so it bounds how much work an interruption repeats:

metrana migrate wandb ... --flush-every 10000   # smaller batches, more checkpoints

Lower it on a flaky connection; raise it for throughput on a stable one.