Runbook: `IndexRoutingLegacyFallback`

Source of truth: tools/observability/alerts/angarabase_alerts.yaml. Backed by: RM-0.6.3.8 S5 + S7. Synergy alert: binds Track 1 storage-correctness counter to Track 2 alerting layer.

Что означает

angarabase_index_routing_legacy_total{db="<db>"} > 0 post-upgrade — на этом instance существуют secondary индексы, чьи catalog записи (IndexDef.index_db_name) ещё не содержат owning DB. Они корректно работают через legacy fallback на base.adb, но это означает:

индекс физически живёт в base.adb вместо <db>.adb,
backup только <db>.adb потеряет такой индекс на restore,
RFC-2026-087 §4.1 invariant (per-DB co-location of pages) нарушен.

Severity

warning. Не critical — данные не теряются и индекс работает, но требует миграции.

Why this alert fires after upgrade

RM-0.6.3.8 ввёл per-DB IndexStore page routing. Бинарь до RM-0.6.3.8 создавал IndexDef без поля index_db_name. После upgrade такие индексы расшифровываются с index_db_name = None и попадают на legacy путь, инкрементируя этот counter.

Initial response

# Какие БД содержат legacy индексы
curl -sf http://127.0.0.1:9898/metrics | rg index_routing_legacy_total

# Список индексов на проблемной БД
psql -d <db> -c "SELECT schemaname, tablename, indexname FROM pg_indexes \
                 WHERE schemaname NOT IN ('pg_catalog','information_schema');"

Mitigation: DROP + CREATE INDEX

Для каждого затронутого индекса выполнить (в окне обслуживания):

\c <db>
DROP INDEX IF EXISTS public.<index_name>;
CREATE INDEX <index_name> ON public.<table> (<col>);

После повторного создания counter перестаёт расти (старая запись IndexDef заменяется новой с корректным index_db_name = Some("<db>"), страницы пишутся в <db>.adb).

Verification

# Counter не должен расти после миграции
watch -n 30 'curl -sf http://127.0.0.1:9898/metrics | rg index_routing_legacy_total'

И проверить размер per-DB файла:

ls -lh <datadir>/<db>.adb
ls -lh <datadir>/base.adb   # должен ужаться после переезда индексов

Escalation

Не требуется — это плановая миграция, не инцидент. Если counter растёт без upgrade’а — это баг, эскалировать.

Связанные

Backup and restore — почему legacy индексы ломали backup
Upgrade and migration
RFC-2026-087 §4.1 + Addendum §S2 (RM-0.6.3.8)

Keyboard shortcuts

AngaraBook