docs(ops): operator runbook — kafka, outbox DLQ, db migrations + index
Карточки процедур для on-call. Self-contained: можно открыть в момент инцидента без необходимости понимать всю архитектуру. - README.md — index by symptom + быстрые гайды по 401, 500, admin-ui 502. - kafka-restart.md — pause/unpause, replicas=0 fix, force-delete, restart consumer'ов после Kafka up. - outbox-dlq.md — диагностика DLQ через UI/API/SQL, типичные причины (orphan topic, ACL, broken payload), replay через UPDATE dlq_at=NULL. - db-migrations.md — Liquibase changelog, добавление, откат, recovery failed migration через DELETE databasechangelog. Vault unseal был отдельным коммитом ранее.
This commit is contained in:
Zimin A.N.
@@ -0,0 +1,110 @@
|
||||
# Runbook: Outbox DLQ — диагностика и replay
|
||||
|
||||
**Когда использовать:**
|
||||
- Метрика `ordinis_outbox_dlq_size > 0` (Prometheus alert).
|
||||
- В UI `/outbox` → ненулевое количество в "В DLQ".
|
||||
- В логе writer: `Outbox event id=N → DLQ after 1000 attempts`.
|
||||
|
||||
## 1. Что это
|
||||
|
||||
Outbox publisher делает at-most ~1000 попыток (`ordinis.outbox.attempt-max`)
|
||||
опубликовать каждое событие в Kafka. После — событие маркируется `dlq_at`
|
||||
и исключается из polling. Без cap poller бесконечно ретраит мёртвые сообщения
|
||||
(orphan topic, broken ACL, malformed payload), забивая лог и lag-метрику.
|
||||
|
||||
## 2. Просмотр DLQ
|
||||
|
||||
### Через admin UI
|
||||
- `https://ordinis.k8s.265.nstart.cloud/outbox` → таблица со всеми DLQ
|
||||
записями: ID, eventType, topic, attemptCount, lastError, dlqAt.
|
||||
|
||||
### Через API
|
||||
```bash
|
||||
curl -sk -H "Authorization: Bearer $TOKEN" \
|
||||
--resolve ordinis.k8s.265.nstart.cloud:443:192.168.100.161 \
|
||||
"https://ordinis.k8s.265.nstart.cloud/api/v1/admin/outbox/dlq?page=0&size=50" \
|
||||
| jq '.content[] | {id, eventType, kafkaTopic, attemptCount, lastError}'
|
||||
```
|
||||
|
||||
### Напрямую в БД
|
||||
```sql
|
||||
-- через kubectl exec на postgres pod
|
||||
SELECT id, event_type, kafka_topic, dictionary_name, attempt_count,
|
||||
LEFT(last_error, 200) AS error,
|
||||
dlq_at, created_at
|
||||
FROM outbox_events
|
||||
WHERE dlq_at IS NOT NULL
|
||||
ORDER BY dlq_at DESC
|
||||
LIMIT 50;
|
||||
```
|
||||
|
||||
## 3. Типичные причины
|
||||
|
||||
| `last_error` содержит | Причина | Решение |
|
||||
|----------------------------------------------------|------------------------------------------------------|--------------------------------------|
|
||||
| `Topic <name> not present` / `UnknownTopicOrPartition` | Топик удалён / переименован / не создан Strimzi'ем | Создать topic либо удалить запись (`DELETE FROM outbox_events WHERE id=N`) |
|
||||
| `TopicAuthorizationException` / `AclAuthorization` | SASL user не имеет PRODUCE rights | Strimzi `KafkaUser` ACL — добавить permission |
|
||||
| `TimeoutException` | Kafka broker недоступен | См. [kafka-restart.md](kafka-restart.md). После up — replay (см. §4) |
|
||||
| `RecordTooLargeException` | Payload > `message.max.bytes` | Увеличить limit в Kafka либо сократить payload |
|
||||
| `JsonMappingException` / `JsonProcessingException` | Payload поломан — нечитаемая JSON | DELETE запись (нечего публиковать) + investigate writer code |
|
||||
| `SerializationException` | Kafka schema registry не разрешает (если включён) | См. schema registry config |
|
||||
|
||||
## 4. Replay — пометить как unpublished снова
|
||||
|
||||
После исправления причины (топик создан, ACL дан) — снять `dlq_at`, обнулить
|
||||
attempt_count, poller подхватит.
|
||||
|
||||
```sql
|
||||
-- одну запись
|
||||
UPDATE outbox_events
|
||||
SET dlq_at = NULL, attempt_count = 0, last_error = NULL
|
||||
WHERE id = 12345;
|
||||
|
||||
-- весь DLQ (после fix корневой причины)
|
||||
UPDATE outbox_events
|
||||
SET dlq_at = NULL, attempt_count = 0, last_error = NULL
|
||||
WHERE dlq_at IS NOT NULL;
|
||||
```
|
||||
|
||||
Через ~1 sec OutboxPoller подхватит и попытается опубликовать заново.
|
||||
|
||||
## 5. Hard delete (когда replay не нужен)
|
||||
|
||||
Если событие безнадёжно (стейл данных, удалённая запись, тестовый мусор):
|
||||
|
||||
```sql
|
||||
DELETE FROM outbox_events WHERE id = 12345;
|
||||
DELETE FROM outbox_events WHERE dlq_at IS NOT NULL AND dictionary_name = 'old_test_dict';
|
||||
```
|
||||
|
||||
⚠️ **Audit:** если событие было `RecordCreated` / `RecordUpdated` — consumer'ы
|
||||
могут не получить change. Альтум-кэш будет stale до следующего read с `?at`.
|
||||
|
||||
## 6. Подключение к staging Postgres
|
||||
|
||||
```bash
|
||||
export KUBECONFIG=/tmp/kubeconfig-161
|
||||
PG_PASS=$(kubectl get secret -n ordinis-staging ordinis-postgres-app \
|
||||
-o jsonpath='{.data.password}' | base64 -d)
|
||||
kubectl exec -it -n ordinis-staging ordinis-postgres-1 -c postgres -- \
|
||||
env PGPASSWORD="$PG_PASS" psql -h localhost -U ordinis_app -d ordinis
|
||||
```
|
||||
|
||||
## 7. Превентивные меры
|
||||
|
||||
- **Alert на `ordinis_outbox_dlq_size > 0`** — задействовать когда настроим
|
||||
Prometheus alerts (v1 closure backlog).
|
||||
- **Kafka topic provisioning** — все топики `ordinis.cuod.events.{public,internal,restricted}`
|
||||
должны быть pre-created в Strimzi `KafkaTopic` CR при разворачивании
|
||||
кластера. Если автоcreate enabled — broker создаст с дефолтами что может
|
||||
не совпадать (replication factor 1 vs 3 и т.д.).
|
||||
- **Schema validation** — outbox `payload` валидируется только Jackson'ом.
|
||||
Schema registry интеграция запланирована на v2.
|
||||
|
||||
## 8. Эскалация
|
||||
|
||||
| Проблема | Действие |
|
||||
|---|---|
|
||||
| DLQ растёт > 100/час | tech lead. Probably broken topic config or producer code |
|
||||
| DLQ есть после рестарта Kafka — ничего не replays автоматически | Manual `UPDATE outbox_events SET dlq_at=NULL` после убеждения что Kafka OK |
|
||||
| Дубликаты после replay (consumer получил оба раза) | Consumer должен быть idempotent (наш consumer-side имеет idempotency_keys) |
|
||||
Reference in New Issue
Block a user