# 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) |