han-app/VM2_services/documentation/module-09-observability-vm2.md

# 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`, Redis Safety и локальным Collector в Compose, а также host KESL 12.4 standalone и root-owned fail-closed broker. 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` |

Host KESL и broker покрываются host/systemd metrics и сигналами Safety (database age, broker availability/latency, scan concurrency); отдельное `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, KESL broker/DNS classification без file content, socket payload/path и 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. Отдельно контролировать host KESL/broker unit state, права `/run/han-kesl/scan.sock`, database age, hourly update result и broker/KESL 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, KESL broker/database age, file/link cache и DNS dependency. `scanner_engine=kesl`; `signatures_version` представлен как hash KESL version + database date. 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; KESL/broker unit down, hourly update failure или stale database по 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, KESL broker/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, KESL broker/database age/hourly update 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).