Метрики и наблюдаемость¶
Synth отдаёт метрики в формате Prometheus и разделяет два вопроса: «процесс жив?» и «можно ли на него направлять трафик?». Этого достаточно, чтобы подключить внешний мониторинг без дополнительных агентов внутри приложения.
/health и /ready¶
| Эндпоинт | Что означает | Ответ |
|---|---|---|
GET /health |
Liveness: процесс жив и отвечает | Всегда 200; при деградации хранилища — status: "degraded" |
GET /ready |
Readiness: приложение инициализировано, миграции применены, очередь готова | 200 — готов; 503 — только на старте или при fail-closed |
Ключевое правило: деградация хранилища не снимает readiness. Инстанс на
файловом read-only фоллбеке продолжает отвечать и остаётся доступен
администратору для диагностики. Если убрать его из балансировки, оператор
потеряет единственный путь к восстановлению. Деградация видна в статусе
/health, метрике synth_storage_degraded и алерте StorageDegraded.
curl -s -o /dev/null -w 'health=%{http_code}\n' localhost:5000/health
curl -s -o /dev/null -w 'ready=%{http_code}\n' localhost:5000/ready
curl -s localhost:5000/ready | jq '{status, storage, version, startedAt}'
Ответ /ready содержит status, storage (ok или degraded), version,
startedAt и time. startedAt — метка старта процесса: по её изменению
интерфейс и скрипты отличают перезапуск от зависания.
Для Kubernetes liveness-пробой обычно служит /health, readiness-пробой —
/ready. Порт — тот же, что у API: у backend это 5000, у standalone —
4300.
/metrics¶
Эндпоинт отдаёт снимок в текстовом формате Prometheus 0.0.4 на том же порту,
что API, но вне префикса /api/v2. Через UI-nginx он не публикуется.
По умолчанию экспорт выключен: при metrics.enabled: false запрос
возвращает 404, а коллекторы не создаются.
| Способ включения | Как | Когда применяется |
|---|---|---|
| Интерфейс | Настройки → Администрирование → «Метрики», тумблер enabled |
После перезапуска |
config.yaml |
metrics.enabled: true |
При старте |
| Переменная окружения | SYNTH_METRICS_ENABLED=true |
При старте |
| Helm | --set metrics.enabled=true |
При старте |
Приоритет: SYNTH_METRICS_ENABLED > runtime-настройка в интерфейсе >
config.yaml > false. Если действует значение из окружения, тумблер в
интерфейсе заблокирован и показывает источник.
Middleware и коллекторы создаются при старте процесса, поэтому изменение
enabled применяется после перезапуска. Раздел «Метрики» показывает баннер
restartRequired и кнопку перезапуска. Токен, в отличие от выключателя,
применяется сразу: он читается на каждый запрос.
| Состояние | Ответ |
|---|---|
enabled: false |
404 NOT_FOUND — эндпоинта нет |
| Включено, токен не задан | 200, text/plain; version=0.0.4 |
| Включено, токен задан, заголовка нет или он неверный | 401 UNAUTHORIZED + WWW-Authenticate: Bearer |
| Включено, токен верный | 200 |
Токен¶
Bearer-токен нужен только для недоверенной сети: в кластере доступ обычно
ограничен NetworkPolicy и Ingress. В config.yaml токен не хранится.
Источники:
- переменная окружения
SYNTH_METRICS_TOKEN— приоритет; - файл
{dataDir}/secrets/metrics-tokenс правами0600.
Файл автоматически не создаётся: его можно создать вручную или из интерфейса.
Раздел «Метрики» позволяет задать и удалить токен — значение write-only, не
возвращается и не логируется. Если токен задан через переменную окружения,
операции записи и удаления из интерфейса отвечают 409 CONFLICT.
install -m 600 /dev/null "$SYNTH_DATA_DIR/secrets/metrics-token"
openssl rand -hex 32 > "$SYNTH_DATA_DIR/secrets/metrics-token"
curl -s -H "Authorization: Bearer $(cat "$SYNTH_DATA_DIR/secrets/metrics-token")" \
localhost:5000/metrics | head
Что смотреть¶
Полный каталог метрик — контракт дашбордов; здесь только семейства, по которым строятся основные панели и алерты.
| Семейство | Что показывает |
|---|---|
| HTTP | Число запросов, длительность, запросы в обработке, активные SSE/WS-потоки |
| Процесс и Node | Версия, память, CPU, event loop lag, uptime |
| Сессии, очередь, ходы | Активные сессии, глубина очереди, исходы ходов, идущие стримы |
| LLM | Запросы по провайдерам и моделям, ошибки, токены, повторы, стоимость |
| Хранилище | Размер каталога данных, число записей, backend, деградация |
| Вложения | Загрузки, размер принятых файлов, выдачи, сборка мусора |
| События, шедулер, webhooks, гибрид, decision | Приём событий, решения Router, дрейф cron, доставки, подключение к серверу, decision-каскад |
| Пайплайны | Прогоны, шаги, длительность, ожидание человека |
| Память | Факты, индексы, чанки, recall и его длительность |
| Исполнитель | Очередь и занятость пула, доставленные и исполненные команды, MCP-серверы |
| Служебные | synth_ready, число серий, длительность скрейпа, отброшенные серии |
Лейблы фиксированы: method, route, status, provider, model, kind,
outcome, source и несколько доменных. route — шаблон маршрута, а не сырой
путь. Идентификаторов session_id и user_id, query-строк и текстов сообщений в
лейблах нет — это и приватность, и защита от неограниченной кардинальности.
Если серия отброшена из-за предела, растёт
synth_metrics_series_dropped_total — это сигнал проверить контракт лейблов.
Скрейп¶
Минимальный prometheus.yml:
В Kubernetes можно включить аннотации pod'а или ServiceMonitor:
Не включайте аннотации при выключенных метриках: Prometheus будет получать
404, а график up — нули и ложные алерты. При включённом токене передайте его
в скрейп через Secret, иначе получите 401. Правила алертов и дашборды
поставляются вместе с Helm-чартом; базовый пример — алерт StorageDegraded по
метрике synth_storage_degraded.
Честно об ограничениях¶
В версии 0.13.4 контур наблюдаемости — метрики, readiness и поставляемые
правила алертов. SLO-минимум и структурированные JSON-логи с request_id
в неё не входят: история метрик хранится в Prometheus, а не в Synth,
трейсинга и доставки алертов через Alertmanager нет. Для разбора инцидента
используйте метрики, /ready, synth doctor и журналы процесса.
Что дальше¶
- Конфигурация — секция
metricsи приоритет источников. - Kubernetes / Helm — values для метрик, ServiceMonitor и probes.
- Обслуживание — перезапуск и проверка инстанса.