Перейти к содержанию

Метрики и наблюдаемость

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 токен не хранится.

Источники:

  1. переменная окружения SYNTH_METRICS_TOKEN — приоритет;
  2. файл {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:

scrape_configs:
  - job_name: synth-backend
    metrics_path: /metrics
    scrape_interval: 15s
    static_configs:
      - targets: ["synth-backend:5000"]
scrape_configs:
  - job_name: synth-backend
    metrics_path: /metrics
    scrape_interval: 15s
    authorization:
      type: Bearer
      credentials_file: /etc/prometheus/synth-metrics-token
    static_configs:
      - targets: ["synth-backend:5000"]

В Kubernetes можно включить аннотации pod'а или ServiceMonitor:

metrics:
  enabled: true
  prometheus:
    annotations: true     # prometheus.io/scrape, port, path
metrics:
  enabled: true
  serviceMonitor:
    enabled: true
    interval: 30s

Не включайте аннотации при выключенных метриках: Prometheus будет получать 404, а график up — нули и ложные алерты. При включённом токене передайте его в скрейп через Secret, иначе получите 401. Правила алертов и дашборды поставляются вместе с Helm-чартом; базовый пример — алерт StorageDegraded по метрике synth_storage_degraded.

Честно об ограничениях

В версии 0.13.4 контур наблюдаемости — метрики, readiness и поставляемые правила алертов. SLO-минимум и структурированные JSON-логи с request_id в неё не входят: история метрик хранится в Prometheus, а не в Synth, трейсинга и доставки алертов через Alertmanager нет. Для разбора инцидента используйте метрики, /ready, synth doctor и журналы процесса.

Что дальше