mi
149 lines
6.8 KiB
Markdown
149 lines
6.8 KiB
Markdown
# Работа с 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.
|