Наблюдаемость

У наблюдаемости AiHummer две поверхности: gateway отдаёт эндпоинт Prometheus GET /metrics для скрейпа базовых метрик и, опционально, пушит телеметрию по OTLP на эндпоинт OpenTelemetry, который вы настраиваете. Скрейпьте /metrics для базового мониторинга; для трейсов и подробных метрик направьте AiHummer на свой OTLP-коллектор и визуализируйте данные поставляемыми дашбордами Grafana.

[!NOTE] pprof (/debug/pprof) не экспонируется.

Эндпоинт Prometheus `/metrics`

GET /metrics отдаёт метрики в текстовом формате Prometheus без дополнительной настройки. Экспонируются только нечувствительные показатели — информация о сборке, аптайм и рантайм процесса, состояние пула соединений с БД и gauge готовности; никаких данных арендаторов, секретов и per-request меток. Для трейсов и богатых метрик используйте OTLP-push.

Push по OTLP

Включается одной переменной:

# gateway.env — экспорт телеметрии в ваш OTLP-коллектор
AIHUMMER_OTEL_ENDPOINT=http://otel-collector:4317

Когда задан AIHUMMER_OTEL_ENDPOINT, gateway отправляет телеметрию в этот коллектор. Оттуда маршрутизируйте её в свой бэкенд (Tempo, хранилище метрик, логи) и в Grafana.

Отчёты об ошибках (Bugsink / Sentry)

Gateway включает клиент отчётов об ошибках по протоколу Sentry — он работает с self-hosted Bugsink или любым Sentry-совместимым DSN. Задайте DSN, и паники и ошибки (включая фазу загрузки и фоновые воркеры) будут отправляться в ваш трекер с тегами компонента и инстанса:

# gateway.env — отчёты об ошибках (Bugsink или любой Sentry-совместимый DSN)
AIHUMMER_SENTRY_DSN=https://<key>@<ваш-bugsink-или-sentry>/<project>
AIHUMMER_SENTRY_ENVIRONMENT=production   # опционально; по умолчанию production

Обе ручки — это настройки из каталога (группа Observability), поэтому их можно задать и из веб-админки; значение из БД имеет приоритет над env. Пока DSN не задан, отчёты выключены.

Живые логи в админке

Страница «Логи» админки — живой хвост журнала gateway: новые строки подтягиваются автоматически каждые несколько секунд, с автопрокруткой у нижнего края. В тулбаре — поиск по строкам и фильтр по уровню (все / ошибки / предупреждения / инфо / debug). Ряд других страниц (Дашборд, Сессии, Каналы) тоже обновляется автоматически, а длинные списки (аудит, изменения, уведомления и т.д.) подгружаются постранично кнопкой «Показать ещё».

Полные журналы всех сервисов по-прежнему живут в systemd — aihummer logs [unit] или journalctl -u aihummer-gateway.

Дашборды Grafana

Готовые дашборды Grafana поставляются вместе с релизом. Импортируйте их в свой экземпляр Grafana, чтобы получить операционные представления без сборки панелей с нуля.

За чем следить

Это сигналы, которые говорят, что система здорова и ходы проходят:

Сигнал	Почему важно
Латентность хода	Сквозная отзывчивость ходов агента
Доля ошибок	Падающие ходы / запросы — первый признак проблем
Диспозиции доставки	Доходят ли ответы реально до каналов
Глубина outbox / DLQ	Очередь недоставленных сообщений; растущий DLQ = доставка застряла

Растущая глубина outbox или очереди мёртвых писем (DLQ) — самый явный ранний сигнал, что доставка копится; следите за ней во время выкаток и инцидентов.

Системные эндпоинты

Помимо OTLP gateway предоставляет небольшие HTTP-эндпоинты, полезные для проб, часов и клиентской диагностики:

Метод	Эндпоинт	Назначение
`GET`	`/metrics`	Метрики Prometheus (сборка, рантайм, пул БД, готовность)
`GET`	`/healthz`	Liveness + версия
`GET`	`/readyz`	Готовность (проверяет Postgres; 503 при недоступности)
`GET`	`/v1/ping`	Лёгкая проверка доступности
`GET`	`/v1/time`	Время сервера
`POST`	`/v1/client-log`	Приём клиентских лог-событий

Пробы здоровья и готовности подробно описаны в разделе systemd и health-проверки.

Куда дальше

Пробы и предстартовый чеклист для продакшена: systemd и health-проверки.
За чем следить во время скользящего обновления: Политика обновлений.

Эндпоинт Prometheus /metrics