AiHummer
Русский▾
ВойтиЛичный кабинет
v1.2.x▾
v1.2.xstablev1.1.xstablev1.0.xstable
{ }Swagger
Эксплуатация/Наблюдаемость

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

v1.2.x · обновлено 2026-07-21

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

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

Endpoint Prometheus /metrics

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

Отправка по OTLP

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

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

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

Обработка паник и ошибок

Отчёты об ошибках никуда наружу не отправляются: в шлюзе нет клиента внешнего трекера ошибок и нет внешнего DSN — данные о ваших ошибках не покидают ваш контур.

Устойчивость к паникам при этом полная:

  • паника в HTTP-обработчике превращается в обычный ответ с кодом ошибки (500 с конвертом AIH-…) — процесс не падает и продолжает обслуживать остальные запросы;
  • паника в фоновой горутине перехватывается и тоже не роняет шлюз.

Оба случая попадают в структурированный журнал — смотрите их на странице «Логи» (ниже) или через journalctl.

Просмотр журнала в реальном времени

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

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

Дашборды Grafana

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

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

Это сигналы, которые говорят, что система работоспособна и запросы проходят. Для каждого сигнала — нормальное значение, тревожный порог и первое действие:

Сигнал Норма Тревожный порог Первое действие
Задержка обработки запроса Стабильна для вашей модели (обычно секунды) Устойчивый рост в 2+ раза от базовой линии Проверьте провайдера модели и загрузку CPU/RAM хоста
Доля ошибок Около нуля Заметная доля падающих запросов (например, >1–5%) Откройте журнал (Логи), найдите первый повторяющийся код ошибки
Диспозиции доставки Почти все успешные Рост отказов по конкретному каналу Проверьте карточку канала: токен, доступность API канала
Ожидающие доставки Около нуля, без роста Устойчивый рост или повторяющиеся отказы Проверьте доступность каналов и разберите причины недоставки

Устойчивый рост ожидающих или повторно неуспешных доставок — самый явный ранний сигнал, что доставка копится; следите за ним во время развёртываний и инцидентов.

Системные endpoints

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

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

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

Куда дальше