Skip to content
Metrana Docs

Overview

Migration brings runs that already exist in another tracker into Metrana — their metrics, their config, and enough provenance to trace each migrated run back to where it came from. It ships as a command in the metrana package:

Terminal window
metrana migrate wandb --entity my-team --project sweeps --workspace my-workspace

Weights & Biases is the first supported source. The engine is source-agnostic, so further trackers slot in without changing the command’s shape or behaviour.

Runs migrate concurrently — a worker process per run — so the same command scales from one run to an entire entity’s history without a second mode. See Migrating many runs at once.

What transfers

Section titled “What transfers”
From the source run Into Metrana
Float metric series Float series on the ML_STEP scale
Histogram metrics Histogram series, counts form
Point timestamps Preserved, so migrated curves keep their original wall clock
Run config Run attributes under config/
User-set summary values Run attributes under summary/
Tags Run tags
Notes / description Run description
Source coordinates Run attributes under the source’s own prefix, e.g. wandb/

What does not

Section titled “What does not”
  • Media and rich values — images, video, audio, tables, plots, and string values. Each unmigrated key is counted and named in the final report, so nothing disappears silently.
  • Malformed histograms — edges that are not strictly increasing, counts that are not whole numbers, or more bins than Metrana’s 512-bin limit allows. These are rejected rather than repaired or rebinned: either would quietly change the data. W&B caps its own histograms at 512 bins as well, so a W&B run has no size-rejected histograms; the check guards against malformed history and future sources whose limits are looser.
  • Summary entries that merely restate a migrated series. Metrana derives its own series summaries, so copying the source’s would only duplicate them, less accurately.
  • Artifacts and system metrics, which are not part of migration today.

Everything migrates on the ML_STEP scale. RL scales, environments, and renderings are not involved.

Resumable by design

Section titled “Resumable by design”

A migration can be interrupted at any point — a crash, a lost network, a cancelled job — and re-run with the same command. It picks up where it stopped.

There is no state file, no journal, and nothing to keep between machines. Each series resumes from the last step the target run already holds, read from the server during the run handshake, so the source of truth is Metrana itself. A local record could drift ahead of what was actually delivered and silently skip a gap; asking the server cannot.

That has a practical consequence worth knowing: re-running a completed migration is safe but not free. It re-opens each run to discover there is nothing left to do.

Reading the result

Section titled “Reading the result”

Every run reports as it starts and again as it lands — out of order, since runs finish when they finish — and the command ends with a summary of what happened:

2026-08-19T09:14:02.118374Z  INFO metrana.migrate.progress: start my-team/sweeps/a1b2c3 -> wandb-sunny-sweep
2026-08-19T09:16:44.229105Z  INFO metrana.cli: [1/3] my-team/sweeps/d4e5f6 -> wandb-brave-sweep migrated, 92160 points
2026-08-19T09:17:01.550913Z  INFO metrana.cli: [2/3] my-team/sweeps/a1b2c3 -> wandb-sunny-sweep migrated, 61440 points
2026-08-19T09:17:12.884662Z  INFO metrana.cli: [3/3] my-team/sweeps/g7h8i9 -> wandb-calm-sweep resumed, 30816 points


Migration summary
  runs migrated:     3 (1 resumed)
  runs skipped:      0
  runs failed:       0
  float points:      184320
  histogram points:  96


Warnings
  my-team/sweeps/a1b2c3 -> wandb-sunny-sweep:
    renamed 'accuracy (%)' -> 'accuracy_{%}'
    skipped 'rollout_video': unsupported value type 'dict'

While runs are still in flight a heartbeat reports what is in progress, and --verbose logs every stage each run passes through. Both are covered in Watching a migration that is still running.

The command exits 0 when every selected run completed and 1 if any failed. A failed run is left resumable — it is not closed — so re-running the command continues it rather than starting it again.

Where to go next

Section titled “Where to go next”