han-app/VM1_app/documentation/module-09-observability-vm1.md

module-09-vm1. Наблюдаемость ВМ1 HAN Chat

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

1. Назначение и границы

Документ задаёт, что агент ВМ1 реализует в Compose, коде, тестах и алертах этой машины.

ВМ1 владеет публичным edge, api-backend, Keycloak, bitrix-local-app, SMS-контуром, Redis DB0/DB1 и локальным Collector. Message Safety, bitrix-sync и Redis Safety живут на ВМ2; KESL 12.4 и его локальный scan-broker работают на host ВМ2. ВМ1 только вызывает Safety по private HTTPS и продолжает trace.

Агент ВМ1 не добавляет scrape, дашборды и алерты сервисов ВМ2.

2. Сервисы и service.name

Компонент	service.name
edge nginx	nginx
api-backend	api-backend
bitrix-local-app	bitrix-local-app
Keycloak	keycloak
sms-service	sms-service
sms-worker	sms-worker
delivery worker	delivery-worker
safety recovery worker	safety-recovery-worker
quarantine cleanup worker	cleanup-worker
notification expiration worker	notification-expire-worker
notification draft cleanup worker	notification-draft-cleanup-worker
Redis DB0/DB1	redis
local Collector	otel-collector
host telemetry agent	otel-host-collector

SMS-метрики и алерты детализированы в module-11-idgtl-sms.md; имена зарегистрированы в arch-07 §4.

Различать экземпляр от ВМ2 через host.name / service.instance.id, не через другое service.namespace.

3. Collector на ВМ1

• отдельный экземпляр в root Compose ВМ1, собственный volume otel-queue;
• приложения ВМ1 экспортируют OTLP только в otel-collector:4317 этой машины;
• export в SigNoz 192.168.0.5:4317; hostname collector ВМ2 не используется;
• pipeline, processors, limits, otel-queue-init и fail-open — arch-07 §3, §13, §14.

Python-сервисы экспортируют structured logs через OTLP Logs SDK в Compose Collector. JSON stdout сохраняется только как bounded аварийный buffer и не собирается повторно.

Отдельный hardened host agent собирает по allow-list:

• Docker json-file для nginx, Keycloak и Redis;
• journal units docker, han-stack, han-secrets, Docker firewall, certbot и fail2ban;
• UFW log, если он включён на host.

Host agent не имеет доступа к Docker socket, исключает собственные логи и Compose Collector, хранит offsets/queue в /var/lib/han-otel/host-collector и экспортирует напрямую в тот же SigNoz. Platform events без активного span не получают искусственные trace IDs и ищутся по host/service/time window.

Scrape targets ВМ1 (кроме самого Collector): Keycloak management metrics, Redis exporter приложения, nginx exporter, сервисные /metrics api-backend и bitrix-local-app, если они не идут OTLP.

4. Instrumentation

Правила FastAPI/HTTPX/PG/Redis/S3/workers, JSON access log nginx и hostmetrics — arch-07 §8. Ниже только покрытие ВМ1.

4.1. api-backend

• server spans с route template;
• child spans: PostgreSQL App DB, Redis DB0/DB1, S3, Message Safety, Open Lines / bitrix-local-app, JWKS;
• internal calls передают traceparent, tracestate, X-Request-ID;
• ux_session_id в JSON-логах только если передан X-Ux-Session-Id;
• исключить /health/live из traces.

4.2. bitrix-local-app

• server spans handler/install/placement;
• outbound Open Lines / Bitrix client spans закрываются результатом, даже если Bitrix не вернул context;
• async outbox/inbox — span link на origin, не подмена долгого worker trace.

4.3. Keycloak

Включаются management metrics/JVM/HTTP/DB pool. Custom OTP provider публикует counters send/verify/limit/settings-cache без phone labels. Login events идут в JSON/audit с masked/HMAC destination. Public OIDC synthetic проверяется отдельно. Native tracing — arch-07 O-TBD5.

4.4. nginx ВМ1

Edge access log по arch-07 §8.4. Route class — bounded set публичных маршрутов ВМ1 (API, auth, WS, Bitrix local app, SMS callback, static). Без native OTEL module первый server span создаёт api-backend или соответствующий upstream.

4.5. Redis приложения и PostgreSQL

Exporter и ACL — arch-07 §8.2–8.3. Клиентские pool metrics публикует api-backend (и SMS, когда появится). Managed PG provider metrics — общий сигнал, не дублируется как метрика ВМ2.

4.6. Host/Docker ВМ1

CPU, memory, disk, network, restarts/OOM, Docker daemon, clock sync — arch-07 §8.5.

5. Метрики бизнес-потоков ВМ1

API и auth

• han_http_requests_total{service,route,method,status_class};
• han_http_request_duration_seconds;
• han_auth_bootstrap_total{outcome};
• han_ux_session_start_total{reason};
• han_jwks_refresh_total{outcome};
• han_rate_limit_decisions_total{scope,outcome}.

Open Lines / bitrix-local-app

• message submitted → delivered end-to-end latency;
• local app outbound result/retry/ambiguous/DLQ;
• inbox depth/oldest age/forward retries/duplicate;
• OAuth time-to-expiry/refresh result;
• connector desired/observed state;
• Bitrix 429, circuit state, setup failure.

Files / S3 со стороны API

• init/complete/promote/delete;
• presigned download issued;
• S3 dependency latency/error by operation and logical bucket.

Quarantine object age, checksum/MIME/size reject и Safety file pipeline — спецификация ВМ2.

Frontend synthetic

• public config/content;
• OIDC discovery/authorization page;
• WS handshake;
• test-user end-to-end flow в отдельной тестовой identity без реального PII.

SMS metrics/alerts — module-11-idgtl-sms.md §10.3.8, после добавления в arch-07.

UUID/user/session/dialog/task/message id не labels.

6. Dashboards ВМ1

В SigNoz, с filter host.name / environment ВМ1:

1. nginx ingress ВМ1: RPS, 4xx/5xx, upstream latency/status, 429, WS, TLS, cache. Без CRM webhook — это ВМ2.
2. api-backend: routes, DB/Redis pools, JWKS, circuits, outbox/safety backlog со стороны caller, S3.
3. bitrix-local-app: install/OAuth, connector, outbound/inbox/DLQ, API/Bitrix latency.
4. Keycloak: login/OTP/lockout, sessions/tokens, provider settings cache, JVM/DB.
5. Redis приложения: memory/evictions/AOF/latency/clients/keyspace.
6. PostgreSQL/S3 в части App DB и бакетов, которыми пользуется ВМ1.

Сквозные Executive/SLO, Business flow и Collector health — arch-07 §10; ВМ1 поставляет свои сигналы, не владеет панелями ВМ2.

7. Alerts ВМ1

Политика SLO — arch-07 §11. Ниже alerts, которые закрывает on-call ВМ1.

Paging

• edge/API 5xx >5% 5 минут;
• text delivery failure >5% 10 минут (сигнал ВМ1: accept/submit/Open Lines; Safety hop подтверждается с ВМ2);
• oldest outbox/inbox >5 минут либо DLQ >0 у bitrix-local-app;
• Keycloak login failures infrastructure class >10% 5 минут;
• Redis приложения unavailable, AOF error или sustained evictions;
• Collector ВМ1 exporter queue >80%, dropped/refused telemetry >0 sustained;
• TLS expiry публичного host ВМ1 <14 дней warning, <7 дней page;
• disk/OOM/restart loop ВМ1.

Ticket/warning

• p95 regression 20% release-over-release на protected read / text send;
• settings/JWKS cache stale;
• OAuth local app expires <24h без успешного refresh;
• cardinality/ingest growth >2× baseline на сериях ВМ1.

Safety mock, Safety config stale, bitrix-sync DLQ/credentials — не алерты репозитория ВМ1.

8. Docker Compose ВМ1

Root Compose включает otel-collector по arch-07 §14. Сети приложений ВМ1: backend + observability (SMS worker — как в arch-03).

Optional profile observability-local на ВМ1 по умолчанию выключен; включение — O-TBD6.

9. Runbooks ВМ1

Общие (Collector not-ready, missing telemetry, remote outage, cardinality, PII) — arch-07 §16.

Высокая latency сообщения (hop ВМ1)

1. Открыть trace по request_id.
2. Разделить nginx, API, Safety client span, S3, local app, Bitrix.
3. Если delay внутри Safety poll/scan — передать инцидент владельцу ВМ2, не менять collector ВМ1.
4. Проверить circuit, outbox age, DB pool и Redis приложения.
5. Не повторять ambiguous message без исходного idempotency key.
6. Следовать runbook module-01-api-backend.md / module-06-bitrix-local-app.md.

10. Definition of Done ВМ1

Дополнительно к arch-07 §17:

• Collector ВМ1 validate + up в root Compose;
• инструментированы FastAPI/HTTPX/PG/Redis/S3 workers api-backend и bitrix-local-app;
• Keycloak metrics доступны;
• nginx JSON parsing и trace correlation edge ВМ1 проверены;
• Redis приложения и host/Collector metrics доступны;
• дашборды и alerts §6–§7 provisioned либо явно TBD до SigNoz packaging;
• canary secret/PII отсутствует в сигналах ВМ1;
• synthetic: public config, OIDC, WS handshake;
• request с X-Request-ID находится в nginx ВМ1, API и client span Safety; продолжение на ВМ2 не блокирует DoD ВМ1, но сквозной gate — arch-10-deployment.md §11 / module-10-deployment-vm1.md.

11. TBD и конфликты, принадлежащие ВМ1

• O-TBD6: нужен ли local observability profile на ВМ1.
• O-TBD5 в части Keycloak native tracing и nginx OTEL module pinned image ВМ1.
• Production SLO Keycloak/API остаются initial ops policy, пока product owner не утвердил O-TBD2.

12. Ссылки

• Контракт: arch-07-observability.md.
• ВМ2: module-09-observability-vm2.md.
• Указатель: module-09-observability.md.
• Edge nginx: module-03-nginx-vm1.md.
• Деплой: module-10-deployment-vm1.md.