Проект разделен на два репозитория
This commit is contained in:
mi
@@ -0,0 +1,193 @@
|
||||
# module-09-vm2. Наблюдаемость ВМ2 Processing
|
||||
|
||||
> Статус: целевая спецификация реализации наблюдаемости на ВМ2.
|
||||
> Канонический контракт (JSON-лог, redaction, sampling, Collector pipeline, SigNoz) — [`arch-07-observability.md`](../../architectory/arch-07-observability.md). Его поля, labels и `service.namespace` здесь не переопределяются.
|
||||
> Контур ВМ1 в этот документ не входит: [`module-09-observability-vm1.md`](../../VM1_app/documentation/module-09-observability-vm1.md). Корреляция сквозного запроса — по `request_id` / `trace_id`.
|
||||
|
||||
## 1. Назначение и границы
|
||||
|
||||
Документ задаёт, **что агент ВМ2 реализует в Compose, коде, тестах и алертах этой машины**.
|
||||
|
||||
ВМ2 владеет nginx (public CRM webhook + private `8443`), `message-safety`, `bitrix-sync`, `clamd`/`freshclam`, Redis Safety и локальным Collector. Guest bootstrap, Keycloak, `api-backend` и `bitrix-local-app` живут на ВМ1. ВМ2 не использует Docker hostname collector ВМ1.
|
||||
|
||||
Агент ВМ2 не добавляет scrape, дашборды и алерты сервисов ВМ1.
|
||||
|
||||
## 2. Сервисы и `service.name`
|
||||
|
||||
| Компонент | `service.name` |
|
||||
|---|---|
|
||||
| nginx public/private | `nginx` |
|
||||
| `message-safety` API/worker | `message-safety` |
|
||||
| `bitrix-sync` | `bitrix-sync` |
|
||||
| Redis Safety | `redis` |
|
||||
| local Collector | `otel-collector` |
|
||||
|
||||
`clamd` / `freshclam` покрываются host/container metrics и сигналами Safety (signature age, scan lanes), отдельное `service.name` в реестр arch-07 не добавляется без явного решения.
|
||||
|
||||
Различать экземпляр от ВМ1 через `host.name` / `service.instance.id`.
|
||||
|
||||
## 3. Collector на ВМ2
|
||||
|
||||
- отдельный экземпляр в root Compose ВМ2, собственный volume `otel-queue`;
|
||||
- приложения ВМ2 экспортируют OTLP только в `otel-collector:4317` этой машины;
|
||||
- export в SigNoz `192.168.0.5:4317`; hostname collector ВМ1 запрещён;
|
||||
- pipeline, processors, limits, `otel-queue-init` и fail-open — arch-07 §3, §13, §14.
|
||||
- telemetry outage fail-open для Safety readiness, но создаёт alert; business fail-open не отменяет Safety fail-closed на содержимом.
|
||||
|
||||
Scrape targets ВМ2 (кроме самого Collector): Redis Safety exporter, nginx exporter, сервисные `/metrics` `message-safety` и `bitrix-sync`, если они не идут OTLP.
|
||||
|
||||
## 4. Instrumentation
|
||||
|
||||
Правила FastAPI/HTTPX/PG/Redis/S3/workers, JSON access log nginx и hostmetrics — arch-07 §8. Ниже только покрытие ВМ2.
|
||||
|
||||
### 4.1. `message-safety`
|
||||
|
||||
- server spans API с route template; poll `202` не маскирует финальный verdict;
|
||||
- worker spans claim/process/finalize и span links на origin `request_id` / `trace_id` caller;
|
||||
- child spans: PostgreSQL Safety schema, Redis Safety, S3 quarantine, ClamAV/DNS classification без file content и raw URL;
|
||||
- `/health/live` исключить из traces; capability/readiness — metrics и sampled logs;
|
||||
- stub mode (`400`, non-sticky) маркируется как `stub`; production SLO Safety на stub недостоверен.
|
||||
|
||||
### 4.2. `bitrix-sync`
|
||||
|
||||
- server spans webhook (после nginx allow-list);
|
||||
- worker/batch/CRM client spans; Bitrix может не вернуть context — span закрывается результатом;
|
||||
- async queue — span link, не подмена долгого worker trace;
|
||||
- query token, raw payload и download URL не попадают в attributes.
|
||||
|
||||
### 4.3. nginx ВМ2
|
||||
|
||||
Access log по arch-07 §8.4. Route class — bounded set: exact CRM webhook, ACME/redirect, private Safety. Query/body webhook не логируются. Метрика `webhook_rejected_total{receiver,reason="source_ip"}` формируется на nginx, потому что запрещённый запрос до upstream не доходит.
|
||||
|
||||
Без native OTEL module первый server span создаёт `message-safety` или `bitrix-sync`.
|
||||
|
||||
### 4.4. Redis Safety и PostgreSQL
|
||||
|
||||
Exporter и ACL — arch-07 §8.2–8.3. Клиентские pool/queue metrics публикуют Safety и `bitrix-sync`. Keys/values, file bytes и message text не экспортируются.
|
||||
|
||||
### 4.5. Host/Docker ВМ2
|
||||
|
||||
CPU, memory, disk, network, restarts/OOM, Docker daemon, clock sync — arch-07 §8.5. Отдельно контролировать `clamd` restarts, signature age и scan lane saturation.
|
||||
|
||||
## 5. Метрики бизнес-потоков ВМ2
|
||||
|
||||
### Message Safety
|
||||
|
||||
- checks/verdicts по `allow|deny|pending|error`;
|
||||
- `processing_mode`, active/used `config_version`, config activation result, `message_safety_mock_enabled` и forced outcomes по `text|file`/`allow|deny`;
|
||||
- poll duration/count buckets, timeout и recovery backlog age;
|
||||
- stub mode info и terminal `400` отдельно, пока действует test-only контракт;
|
||||
- cache hit, Redis latency, task expired/not-found.
|
||||
|
||||
### Files / S3 со стороны Safety
|
||||
|
||||
- quarantine object age/orphans;
|
||||
- checksum/MIME/size reject;
|
||||
- S3 dependency latency/error by operation and logical bucket.
|
||||
|
||||
Init/complete/promote/presigned download со стороны API — спецификация ВМ1.
|
||||
|
||||
### `bitrix-sync`
|
||||
|
||||
- queue depth/oldest age, workflow/command transitions;
|
||||
- CRM batch latency/subcommand outcome;
|
||||
- limiter/throttle, retry/DLQ;
|
||||
- webhook/reconciliation lag;
|
||||
- mapping invariants и business-alert SLA;
|
||||
- nginx `webhook_rejected_total{receiver,reason="source_ip"}`.
|
||||
|
||||
До module-07 preflight Queue/CRM SLI не включаются; dashboard показывает `sync_disabled`, а не синтетический CRM success.
|
||||
|
||||
UUID/user/session/dialog/task/message id не labels.
|
||||
|
||||
## 6. Dashboards ВМ2
|
||||
|
||||
В SigNoz, с filter `host.name` / environment ВМ2:
|
||||
|
||||
1. **nginx ingress ВМ2**: RPS, 4xx/5xx, upstream latency/status, TLS, cache, **CRM webhook** (accept/reject by source IP, method, rate limit). Без guest API/WS — это ВМ1.
|
||||
2. **message-safety**: capabilities, verdicts, `202` poll, PG queue age/leases/fencing, ClamAV/signature age, file/link cache и DNS dependency. Stub явно маркируется.
|
||||
3. **bitrix-sync**: mode/readiness, queue depth/oldest age, workflow/command transitions, CRM batch latency/subcommand outcome, limiter/throttle, retry/DLQ, webhook/reconciliation lag, mapping invariants и business-alert SLA. До cutover — `sync_disabled`.
|
||||
4. **Redis Safety**: memory/evictions/AOF/latency/clients/keyspace.
|
||||
|
||||
Сквозные Executive/SLO, Business flow и Collector health — arch-07 §10.
|
||||
|
||||
## 7. Alerts ВМ2
|
||||
|
||||
Политика SLO — arch-07 §11. Ниже alerts, которые закрывает on-call ВМ2.
|
||||
|
||||
### Paging
|
||||
|
||||
- oldest safety task >5 минут либо Safety DLQ >0;
|
||||
- Message Safety active config missing/invalid, referenced artifact unavailable или config refresh stale >5 с;
|
||||
- `message_safety_mock_enabled=1` — active page/high-severity alert без auto-resolve по времени; закрывается только после возврата в standard;
|
||||
- bitrix-sync invalid/revoked credential или обязательная configuration/grant missing;
|
||||
- bitrix-sync technical DLQ >0, mapping invariant violation или worker/limiter heartbeat stale;
|
||||
- bitrix-sync queue oldest age >30 с при healthy CRM либо sustained рост;
|
||||
- Contact webhook/reconciliation cursor lag выше двух configured intervals;
|
||||
- Redis Safety unavailable, AOF error или sustained evictions;
|
||||
- Collector ВМ2 exporter queue >80%, dropped/refused telemetry >0 sustained;
|
||||
- TLS expiry public webhook host и private `8443` <14 дней warning, <7 дней page;
|
||||
- disk/OOM/restart loop ВМ2; `clamd` restart loop / stale signatures по runbook module-05.
|
||||
|
||||
### Ticket/warning
|
||||
|
||||
- p95 Safety poll/scan regression 20% release-over-release;
|
||||
- bitrix-sync CRM last success stale, rate-limit errors выше baseline или business alert SLA overdue;
|
||||
- quarantine orphan growth;
|
||||
- cardinality/ingest growth >2× baseline на сериях ВМ2.
|
||||
|
||||
Keycloak login, guest bootstrap и edge API 5xx ВМ1 — не алерты репозитория ВМ2.
|
||||
|
||||
## 8. Docker Compose ВМ2
|
||||
|
||||
Root Compose включает `otel-collector` по arch-07 §14. Сети приложений ВМ2: `backend` + `observability`; nginx — свои public/private сети по arch-03 / [`module-03-nginx-vm2.md`](module-03-nginx-vm2.md).
|
||||
|
||||
Optional profile `observability-local` на ВМ2 по умолчанию выключен: малая VM, extra RAM/disk не закладываются.
|
||||
|
||||
## 9. Runbooks ВМ2
|
||||
|
||||
Общие (Collector not-ready, missing telemetry, remote outage, cardinality, PII) — arch-07 §16.
|
||||
|
||||
### Высокая latency сообщения (hop ВМ2)
|
||||
|
||||
1. Найти task/span по `request_id` caller.
|
||||
2. Разделить Safety API, worker lease, ClamAV/DNS, S3 quarantine, sync queue.
|
||||
3. Проверить circuit, queue age, PG leases/fencing и Redis Safety.
|
||||
4. Не повторять ambiguous scan/send без исходного idempotency key.
|
||||
5. Следовать runbook [`module-05-message-safety.md`](module-05-message-safety.md) / [`module-07-bitrix-sync.md`](module-07-bitrix-sync.md).
|
||||
6. Delay до Safety (nginx/API ВМ1) — инцидент владельца ВМ1.
|
||||
|
||||
### MOCK включён в production-like
|
||||
|
||||
1. Подтвердить `message_safety_mock_enabled=1` и paging alert.
|
||||
2. Не auto-resolve по времени.
|
||||
3. Вернуть standard через root-owned five-command helper; проверить persistent alert closed.
|
||||
4. Canary allow/deny после возврата.
|
||||
|
||||
## 10. Definition of Done ВМ2
|
||||
|
||||
Дополнительно к arch-07 §17:
|
||||
|
||||
- Collector ВМ2 validate + up в root Compose; hostname collector ВМ1 не используется;
|
||||
- инструментированы `message-safety` API/worker и `bitrix-sync`;
|
||||
- nginx JSON parsing, webhook reject metric и private `8443` correlation проверены;
|
||||
- Redis Safety, host/Collector, ClamAV signature age metrics доступны;
|
||||
- дашборды и alerts §6–§7 provisioned либо явно TBD до SigNoz packaging;
|
||||
- stub/MOCK маркируются; production Safety SLO не объявляется на stub;
|
||||
- до sync cutover dashboard `sync_disabled`;
|
||||
- canary secret/PII/message body/file content/presigned URL отсутствуют в сигналах ВМ2;
|
||||
- request с известным `request_id` находится в Safety spans; сквозной nginx ВМ1 → API → Safety — [`arch-10-deployment.md`](../../architectory/arch-10-deployment.md) §11 / [`module-10-deployment-vm2.md`](module-10-deployment-vm2.md).
|
||||
|
||||
## 11. TBD и конфликты, принадлежащие ВМ2
|
||||
|
||||
- Conflict module-05: test-only `400` / non-sticky verdict. Dashboards маркируют `stub`; production SLO Safety недостоверен.
|
||||
- Conflict module-07: до preflight/cutover показывать `sync_disabled`, не синтетический CRM success.
|
||||
- O-TBD5 в части nginx OTEL module pinned image ВМ2.
|
||||
|
||||
## 12. Ссылки
|
||||
|
||||
- Контракт: [`arch-07-observability.md`](../../architectory/arch-07-observability.md).
|
||||
- ВМ1: [`module-09-observability-vm1.md`](../../VM1_app/documentation/module-09-observability-vm1.md).
|
||||
- Указатель: [`module-09-observability.md`](module-09-observability.md).
|
||||
- Safety / sync / nginx: [`module-05-message-safety.md`](module-05-message-safety.md), [`module-07-bitrix-sync.md`](module-07-bitrix-sync.md), [`module-03-nginx-vm2.md`](module-03-nginx-vm2.md).
|
||||
- Деплой: [`module-10-deployment-vm2.md`](module-10-deployment-vm2.md).
|
||||
Reference in New Issue
Block a user