# 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).