Операционный гайд: runtime и метрики

Гайд описывает, где смотреть состояние MARV в проде: какие эндпоинты уже отдают готовые метрики, как читать runtime-блоки в ACP и какие флаги включают дополнительный экспорт.

Источники телеметрии

Источник	Что содержит	Как включить/получить
GET /acp/system/metrics	JSON c секциями host/cache/db/http/controllers/tasks/streams/traffic_flows	Доступно всем ACP-операторам (авторизация обязательна)
GET /acp/cron_tasks/list	Помимо списка задач содержит блок runtime с running, running_since, runs, failures, p95	Уже включено, обновляется в реальном времени
GET /acp/streams/list и /acp/traffic_flows/list	В ответе есть runtime (per-handler latencies/errors) и commit (сборка сервера)	Можно использовать для health-check’ов UI
/metrics (Prometheus)	marv_controller_*, marv_task_*, marv_http_client_* в формате Prometheus	В config.{mode}.yml выставить observability.metrics.prometheus_enabled: true

Быстрые процедуры

Проверка cron-задач

1. Открой /acp/cron_tasks/list.
2. Отсортируй по running == true, чтобы увидеть задачи, которые всё ещё исполняются (поле running_since покажет момент старта).
3. Сравни runs/failures с задачами прошлого часа; резкий рост Failures => проверить логи задачи и параметры HTTP вызова (URL, headers, payload).
4. В /acp/system/metrics → секция tasks ищи p95_duration_ms и last_error. Если p95 > SLA — возможно, задача цепляется за внешний сервис.
5. Для пост-мортема доступны сырые длительности в Prometheus (marv_task_last_duration_milliseconds и bucket’ы контроллеров).
6. У каждой задачи есть execution_scope: leader означает запуск только на лидере, all — на каждом сервере. Если таск неожиданно не исполняется, убедись, что текущий узел лидер или что scope выставлен корректно.

Мониторинг потоков и трафика

1. /acp/streams/list и /acp/traffic_flows/list возвращают runtime c count, errors, avg_ms, p95_ms. Это тот же recorder, что и в /acp/system/metrics.controllers.
2. Проверяй commit → легко понять, какая версия кода отдает страницу.
3. Если errors > 0, сразу смотри controller_metrics по маршруту (пример: /acp/system/metrics → controllers["/acp/streams/list"]).

HTTP‑клиенты и ретраи

1. http.total_requests/errors/duration_ms_sum видны в /acp/system/metrics.http.
2. Buckets задаются через observability.metrics.http_buckets_ms; они же попадут в Prometheus (marv_http_client_duration_milliseconds_sum + счетчики по bucket’ам).
3. Даже при использовании internal/infrastructure/http/retry статистика берётся с базового клиента, поэтому повторные запросы учитываются.

Трассировка запросов

1. Middleware RequestID добавляет X-Request-Id в каждый ответ и записывает его в gin.Context как request_id.
2. ControllerMetricsMiddleware прокидывает trace_id=request_id в логгер (zerolog) и в gin.Context.
3. В логах ищи trace_id=<request-id> → это тот же ID, что вернул клиенту HTTP-слой.
4. Если нужен признак страны клиента, смотри заголовок X-Client-Country-Code (проксируется из CF-IPCountry Cloudflare’а).
5. Для идентификации конкретного узла/процесса используй заголовок X-Server-Id: значение берётся из app.server.id (если не задан, контейнер сгенерирует ID сам) и синхронизируется с лидер-выборами (app.server.is_leader в runtime-конфиге показывает текущее состояние).

Настройка Prometheus

observability:
  metrics:
    prometheus_enabled: true    # включает /metrics
    http_buckets_ms: [50,100,200,500,1000,2000,5000]

После включения:

• /metrics возвращает текстовый снапшот (см. pkg/engine/prometheus.go).
• рекомендуемые алерты:
  • rate(marv_controller_errors_total[5m]) > 0 для критичных маршрутов ACP/V2.
  • marv_task_running{tag="..."} == 1 и time() - marv_task_last_run_timestamp_seconds > X — зависшие cron-задачи.
  • rate(marv_http_client_errors_total[5m]) / rate(marv_http_client_requests_total[5m]) > 0.05.

Чек-лист on-call

1. Падение UI / ACP → GET /acp/system/metrics, убедиться, что контроллерные метрики приходят, посмотреть host.uptime_seconds.
2. Жалобы на задания → /acp/cron_tasks/list + tasks секция в системных метриках.
3. Проблемы со стримами/трафиком → runtime-блоки в соответствующих списках; фильтруем по errors.
4. Внешние интеграции → HTTP секция (total_requests, кастомные buckets) + логи по trace_id.
5. Аудит версии → поле commit в ACP-ответах + version (если выставлен) в /acp/system/metrics.

Этот гайд дополняет документ по наблюдаемости и план развития метрик/CI: первый описывает, какие метрики собираются, второй — как они попадают в CI. Здесь собраны именно операционные процедуры.