docs: split integrator guide (Diplodoc) vs internal docs + add build-docs CI
Чёткое разделение audiences:
- docs/ — consumer-facing only, Diplodoc-built. Public contract для
интеграторов (Альтум, BI, third-party).
- docs-internal/ — operator runbooks, status snapshots, legacy tech pages.
НЕ в Diplodoc build, НЕ публикуются.
Изменения:
- Move docs/{ops,status,tech} → docs-internal/{ops,status,tech}
- docs/toc.yaml: убраны секции Operations, Архитектура (legacy), Status
- docs/index.md: убран tab "оператор / on-call", focus на integrators
- docs/README.md: rewritten — scope только integrator guide, editorial
guidelines (no leak internal architecture, stable API contract)
- .yfm: убран явный ignore status/* (теперь не нужно — папка переехала)
- docs-internal/README.md: index для внутренней документации с rationale
разделения
Scrubbing implementation details из Diplodoc страниц:
- events.md: убраны Strimzi/cluster.142 references, OutboxPoller детали,
internal alert names (OrdinisOutboxLagHigh, OrdinisOutboxDLQNonEmpty),
metric names (nsi_outbox_*). Заменены на consumer-observable contract.
- webhooks.md: убраны metric names (nsi_webhook_ssrf_rejected_total),
alert table (OrdinisWebhookHighFailureRate и т.д.). Retry policy
переписана на user-side perspective.
- errors.md: убран alert name OrdinisReadApiErrorBudgetBurnFast, Tempo
endpoint URL, internal connection details.
- x-references.md: OrphanReferenceScanner → general "Ordinis периодически
детектирует". Убраны metric/alert names. Cascade roadmap без link на
internal design doc.
- auth.md: убран file path ScopeContext.java.
- bundle-cuod.md: убран Maven module path.
- caching.md: cascade design link заменён на text reference.
CI:
- .gitlab-ci.yml: новый job build-docs (stage: build) — Node 20 alpine,
pnpm install --frozen-lockfile + pnpm build, artifact docs/_dist на
неделю. Triggers: auto на docs/**, либо manual web. Готов к follow-up
pages-deploy job когда host решён.
- Новый pattern .docs-changes для rules.
Build verified clean: 13 HTML pages, 6.9M, no broken links/refs.
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