# Работа с SigNoz для HAN Chat

Это эксплуатационный runbook UI: фильтры, ежедневная проверка и разбор
инцидентов. Раскатка ВМ3, lockdown и обновление стека — только в
[RUNBOOK.ru.md](RUNBOOK.ru.md).

## Базовые фильтры

Во всех разделах начинайте с:

```text
service.namespace = han-chat
deployment.environment = production-like
```

Для сравнения релизов используйте `service.version`. Не смешивайте production
и smoke/local данные в одном запросе без фильтра окружения.

MVP service names:

```text
api-backend
sms-service
sms-worker
```

Для worker ищите ручные spans `sms.claim`, `sms.process`, `sms.provider`,
`sms.save_result`. Health routes исключены до tail sampling.

## Ежедневная проверка

1. **Services** — появились ли ожидаемые сервисы, нет ли резкого роста error
   rate или p95 latency.
2. **Traces** — последние ошибки и медленные запросы, путь от HTTP endpoint до
   БД/Redis/внешнего API.
3. **Logs** — события рядом с trace по `trace_id`, ошибки и повторы workers.
4. **Metrics** — насыщение ресурсов, очереди, SMS и фоновые задачи.
5. **Alerts** — firing/acknowledged alerts и причины, а не только факт firing.

Пока приложения не инструментированы, эти представления будут неполными; см.
ограничение в `BACKEND_OTLP.md`.

## Разбор инцидента

Начните с узкого временного диапазона вокруг события:

1. найдите пользовательский `request_id` из ответа API или журнала;
2. в Logs ищите точное значение `request_id`;
3. откройте связанный trace по `trace_id`;
4. найдите первый ошибочный или самый долгий span, а не последний симптом;
5. сравните с предыдущей версией по `service.version`;
6. проверьте зависимости: PostgreSQL, Redis, Keycloak, S3, SMS provider,
   Bitrix;
7. сохраните ссылку на запрос SigNoz и зафиксируйте UTC-интервал инцидента.

Не добавляйте в SigNoz телефон, email, токены, cookie, содержимое сообщений,
полные SQL statements и query string. Collector удаляет известные
чувствительные атрибуты, но новые поля должны проходить отдельную проверку.

## Рекомендуемые представления после инструментации

**API**

- request rate, error rate, p50/p95/p99 duration;
- разрез по нормализованному `http.route`, не по сырому URL;
- 401/403 отдельно от 5xx;
- latency PostgreSQL, Redis, Keycloak и S3;
- количество активных WebSocket/SSE соединений и reconnect.

**SMS**

- `sms_send_total` по результату/provider;
- provider latency;
- uncertain deliveries и callback lag;
- возраст pending-заявок и размер journal;
- валидность runtime settings.

**Workers**

- длительность и результат job;
- глубина очереди, oldest item age;
- retries/dead-letter/recovery;
- lag cleanup/delivery/safety/notification jobs.

**Инфраструктура**

- CPU, RAM, filesystem usage VM SigNoz;
- ClickHouse inserts/query latency, parts и disk usage;
- dropped/refused spans, exporter failures и queue size Collector;
- restarts и health контейнеров.

## Первые алерты

Точный состав панелей и acceptance-критерии зафиксированы в
`MVP_DASHBOARDS_ALERTS.md`.

Создавайте алерты только после получения базовой линии, чтобы избежать шума:

- API 5xx rate выше согласованного порога 5–10 минут;
- p95 latency выше SLO 10 минут;
- нет телеметрии от production-сервиса 5–10 минут при ожидаемом трафике;
- Collector exporter failures/dropped telemetry больше нуля;
- очередь workers или oldest item age растёт;
- SMS uncertain/callback lag превышает бизнес-порог;
- диск VM SigNoz заполнен более чем на 75% и 85%;
- любой критичный контейнер перезапускается или unhealthy.

Для каждого alert укажите severity, owner, runbook URL и минимальное время
устойчивого нарушения. Не оповещайте по единичной ошибке.

## Sampling и интерпретация

Collector сейчас применяет probabilistic sampling 10% только к traces.
Метрики и логи не sampled этим processor. Следствия:

- единичный запрос может не попасть в Traces;
- абсолютное число traces нельзя считать числом запросов;
- ошибки тоже могут быть отброшены, потому что tail/error-aware sampling пока
  не настроен;
- SLO и alerting следует строить на метриках, а не на подсчёте sampled traces.

Для production рекомендуется перейти к tail sampling: сохранять 100% ошибок и
медленных traces, а успешные быстрые запросы — выборочно.

## Обслуживание SigNoz

Проверка:

```bash
cd /opt/signoz
sudo ./scripts/30-verify-signoz.sh
sudo docker compose -f pours/deployment/compose.yaml logs --since=30m
df -h
docker system df
```

Перед обновлением:

1. временно разрешить исходящий интернет;
2. сделать snapshot диска;
3. проверить свободное место;
4. выполнить `scripts/20-deploy-signoz.sh`;
5. повторить smoke-тест и проверить сохранность старых данных;
6. отключить внешний доступ.

Не выполняйте `docker compose down -v`, `docker volume prune` или
`docker system prune --volumes`: эти команды могут удалить телеметрию и
метаданные SigNoz.