mdm-ordinis/docs-internal/ops/outbox-dlq.md

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

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}'

Напрямую в БД

-- через 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. После 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 подхватит.

-- одну запись
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 не нужен)

Если событие безнадёжно (стейл данных, удалённая запись, тестовый мусор):

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

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)