Skip to content

Commit df6ee20

Browse files
andrescrzclaude
andcommitted
docs(cutover): clarify verify.sh --from-week/--to-week are 0-based week offsets
Full forward E2E rehearsal finding: the runbook's post-EXCHANGE compare hint wrote `--to-week <last-full-week>`, which reads like a date, but verify.sh takes a 0-based integer week offset from the anchor Monday. Passing a date fails with "must be a non-negative integer". Clarify both mentions (the sealed-weeks compare tip and the feasibility bullet) so operators pass an integer offset (e.g. --to-week 3). Doc-only; found while validating the runbook against a live run. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
1 parent 4f760b4 commit df6ee20

1 file changed

Lines changed: 5 additions & 3 deletions

File tree

  • apps/opik-backend/data-migrations/traces-local-v2-cutover

apps/opik-backend/data-migrations/traces-local-v2-cutover/README.md

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -602,15 +602,17 @@ CLICKHOUSE_HOST=<host> CLICKHOUSE_PASSWORD=<pw> ./scripts/verify.sh --database o
602602
> **frozen** snapshot as of `cutover_start`, but live `traces` keeps taking writes the instant the buffer drains — so
603603
> the **current (live) week will legitimately show a mismatch** (the live table is a superset of the frozen backup by
604604
> exactly the post-cutover writes). That is expected, not a leak. To use the post-EXCHANGE compare as a real check,
605-
> either run it **immediately after the swap before writes resume**, or bound it to the **sealed historical weeks**
606-
> (`--to-week <last-full-week>`), where a mismatch *would* be a genuine problem. A leak shows up as rows present in the
605+
> either run it **immediately after the swap before writes resume**, or bound it to the **sealed historical weeks** with
606+
> `--to-week N` (a **0-based week offset** from the anchor Monday, not a date — e.g. `--to-week 3` to stop before the
607+
> current partial week), where a mismatch *would* be a genuine problem. A leak shows up as rows present in the
607608
> backup but absent from `traces`; post-cutover writes are the harmless opposite direction.
608609
609610
**Feasibility at scale.** A full pass reads every partition (heavy but bounded per week — run off-peak). When that is
610611
infeasible, sample and still get high confidence:
611612
- `--sample-mod N` compares a deterministic 1/N `id` sample — the *same* rows on both sides, so like-for-like.
612613
- `--weeks-stride S` compares every S-th weekly partition (partition-pruned, so genuinely cheaper).
613-
- `--from-week` / `--to-week` bound the range (e.g. verify the most recent weeks fully, older weeks sampled).
614+
- `--from-week` / `--to-week` bound the range by **0-based week offset** (integers from the anchor Monday, not dates;
615+
`--to-week` is inclusive) — e.g. verify the most recent weeks fully, older weeks sampled.
614616

615617
`verify.sh` exits non-zero if any window mismatches and prints the window bounds; re-run with `--drill-down` to list the
616618
keys that differ or exist on one side only (it runs the `drill-down` block of `000005_verify_migration.sql` for each

0 commit comments

Comments
 (0)