mi
219 lines
12 KiB
Markdown
219 lines
12 KiB
Markdown
# module-09-vm1. Наблюдаемость ВМ1 HAN Chat
|
||
|
||
> Статус: целевая спецификация реализации наблюдаемости на ВМ1.
|
||
> Канонический контракт (JSON-лог, redaction, sampling, Collector pipeline, SigNoz) — [`arch-07-observability.md`](../../architectory/arch-07-observability.md). Его поля, labels и `service.namespace` здесь не переопределяются.
|
||
> Контур ВМ2 в этот документ не входит: [`module-09-observability-vm2.md`](../../VM2_services/documentation/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` |
|
||
| 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`](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`](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-01-api-backend.md) / [`module-06-bitrix-local-app.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`](../../architectory/arch-10-deployment.md) §11 / [`module-10-deployment-vm1.md`](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`](../../architectory/arch-07-observability.md).
|
||
- ВМ2: [`module-09-observability-vm2.md`](../../VM2_services/documentation/module-09-observability-vm2.md).
|
||
- Указатель: [`module-09-observability.md`](module-09-observability.md).
|
||
- Edge nginx: [`module-03-nginx-vm1.md`](module-03-nginx-vm1.md).
|
||
- Деплой: [`module-10-deployment-vm1.md`](module-10-deployment-vm1.md).
|