Admin/han-app
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
d2415fcfeb9ae630afcf1f04612aeeb0d6cd09c4
han-app/VM1_app/documentation/module-09-observability-vm1.md
T

11 KiB
Raw Blame History

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, ClamAV и Redis Safety живут на ВМ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
Redis DB0/DB1 redis
local Collector otel-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.

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

Reference in New Issue View Git Blame Copy Permalink