Admin/han-app
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
7a60636fd931a9ec8137ebde38fa91c3e958f1d4
han-app/VM2_services/documentation/module-09-observability-vm2.md
T

12 KiB
Raw Blame History

module-09-vm2. Наблюдаемость ВМ2 Processing

Статус: целевая спецификация реализации наблюдаемости на ВМ2.
Канонический контракт (JSON-лог, redaction, sampling, Collector pipeline, SigNoz) — arch-07-observability.md. Его поля, labels и service.namespace здесь не переопределяются.
Контур ВМ1 в этот документ не входит: 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.

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-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 §11 / 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. Ссылки

Reference in New Issue View Git Blame Copy Permalink