Частые проблемы

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

Начните с раздела «Агенты» в меню кабинета. Там видны статус каждого агента, его версия и когда он последний раз выходил на связь. Сбои агента, о которых он успел сообщить, появляются на вкладке «События» стека или «Инциденты» сервера как «ошибка агента» с кодом — например, E_KUBE_RBAC. Если вы подключили ИИ-ассистента, попросите его «проверь, почему в стеке нет данных»: он посмотрит статус агента, версию и что уже приходит, и подскажет, что исправить.

#Агент не на связи или нет данных

Как выглядит. В разделе «Агенты» у агента статус «Ожидает» (ещё ни разу не присылал данные) или «Неактивен» (на связи был, но последние 2 минуты молчит). На странице стека нет контейнеров, у сервера нет графиков.

Сначала посмотрите логи самого агента:

# Docker Compose
docker compose logs -f nabl-agent

# Kubernetes
kubectl -n <namespace> logs deploy/nabl-agent -f

# Сервер Linux
sudo systemctl status nabl-agent --no-pager
sudo journalctl -u nabl-agent -f

Дальше — по тому, что видно в логах.

#Неверный токен (ошибка 401)

Причина. В логах агента 401 или «неверный токен». Токен скопирован не полностью, заменён или агент был пересоздан, и старый токен перестал работать.

Что сделать. Токен показывается только один раз, посмотреть его снова нельзя. На странице стека или сервера нажмите кнопку «Агент» и подтвердите «Пересоздать»: появится новый токен, а старый сразу перестанет работать. Пропишите новый токен там, где установлен агент:

• Docker Compose — в NABL_AGENT_TOKEN (лучше вынести в .env), затем docker compose up -d nabl-agent;

• Kubernetes — в Secret nabl-agent, затем перезапустите Deployment:

  bashКопировать

  kubectl -n <namespace> patch secret nabl-agent -p '{"stringData":{"token":"<новый токен>"}}'
  kubectl -n <namespace> rollout restart deployment/nabl-agent

• сервер Linux — в /opt/nabl-agent/.env. Агент перечитывает этот файл перед каждой отправкой, перезапуск не нужен.

ИИ-ассистент тоже умеет выпустить новый токен: при этом агент и история сохраняются, а в ответе будет готовая команда для обновления.

#Агент не может достучаться до Наблюдателя

Причина. В логах агента — ошибки соединения или таймауты. Агент не видит адрес платформы https://app.nablserver.ru: мешает firewall, прокси или DNS.

Что сделать. Агенту нужен только исходящий HTTPS к https://app.nablserver.ru — входящие порты открывать не нужно. Проверьте, что сервер или контейнер выходит в интернет и разрешает адрес. Проверьте и переменную NABL_BASE_URL в настройках агента: там должен быть адрес платформы без опечаток.

#В Docker Compose агент работает, а контейнеров нет

Причина. Чаще всего в контейнер агента не смонтирован Docker socket (в событиях стека — «ошибка агента» с кодом E_DOCKER). Ещё одна причина — агент запущен через docker run, а не сервисом в docker-compose.yml, и не может понять, какой compose-проект ему наблюдать.

Что сделать. Убедитесь, что в сервисе агента есть том:

volumes:
  - /var/run/docker.sock:/var/run/docker.sock

и что агент запущен сервисом в том же docker-compose.yml, что и приложение. Если сокет монтировать нельзя по правилам безопасности, укажите в NABL_DOCKER_HOST адрес docker-socket-proxy (tcp://…) с правом на чтение containers, info и system. Подробнее — в статье о Docker Compose.

#Видны не все сервисы стека

Причина. Агент собирает только контейнеры своего compose-проекта. Сервисы, запущенные из другого каталога или с другим -p, — это другой compose-проект.

Что сделать. Создайте для другого compose-проекта отдельный стек со своим агентом. Как разложить окружения по стекам и проектам — в статье Основные понятия.

#В Kubernetes не хватает прав (RBAC)

Причина. В событиях стека — «ошибка агента» с кодом E_KUBE_RBAC. У ServiceAccount агента нет прав на чтение подов. Так бывает, если манифест правили вручную или агент смотрит несколько namespace (NABL_K8S_NAMESPACES), а права выданы только на один.

Что сделать. Примените манифест из кабинета заново. Если агент наблюдает несколько namespace или весь кластер (all), замените Role и RoleBinding на ClusterRole и ClusterRoleBinding с теми же правилами. Проверить права можно так:

kubectl auth can-i --list -n <namespace> --as=system:serviceaccount:<namespace>:nabl-agent

Подробнее — в статье о Kubernetes.

#Нет CPU и памяти подов (metrics-server)

Как выглядит. Поды, их статусы и перезапуски видны, но графиков CPU и памяти нет. В событиях стека — «ошибка агента» с кодом E_KUBE_METRICS.

Причина. CPU и память подов агент берёт из metrics.k8s.io, а его отдаёт metrics-server. В кластере его нет или он не работает. Это частый случай в kind и k3d.

Что сделать. Установите metrics-server в кластер. В minikube достаточно команды:

minikube addons enable metrics-server

Проверьте, что kubectl top pod -n <namespace> показывает значения. Как только metrics-server заработает, графики появятся сами — агента перезапускать не нужно. Статусы, перезапуски, OOM и ошибки из логов работают и без metrics-server.

#Не приходят трассы

Как выглядит. Вкладка «Трассировка» пустая, хотя приложение подключено к OpenTelemetry.

Трассы принимает только агент стека — Docker Compose или Kubernetes. Агент сервера Linux их не принимает. Если трассы шлются агенту сервера, в Наблюдателе будет пусто.

Ещё две частые ошибки. Если в compose у приложений заданы свои networks:, добавьте агента в ту же сеть. Если вы задаёте OTEL_EXPORTER_OTLP_TRACES_ENDPOINT, указывайте полный путь http://nabl-agent:4318/v1/traces; в OTEL_EXPORTER_OTLP_ENDPOINT — только базовый адрес http://nabl-agent:4318.

Сэмплер в SDK не настраивайте: Наблюдатель хранит все трассы, и с выборкой цифры будут занижены. Подробнее — в статье Трассировка.

#Не появляются ошибки приложения

Как выглядит. На вкладке «Ошибки» пусто, хотя приложение падает.

Причины и что сделать.

• Приложение пишет логи в файл. Агент читает только stdout и stderr контейнера. Выводите логи туда.
• Ошибка не распознана. Агент понимает JSON-логи с полем level = error или fatal, стеки Go, Python, Node.js и строки с ERROR, FATAL, ERR. Строки уровня WARN и обрывы соединения клиентом намеренно пропускаются.
• Kubernetes и старый агент. Ошибки из логов подов собирает агент 0.8.0 и новее. На 0.7.x видны только падения, перезапуски и OOM.
• Агент сервера. Агент сервера Linux логи приложений не читает — нужен агент стека.
• Просто рано. Новая ошибка появляется через 30–90 секунд.

Проверить можно тестовой строкой в stdout любого контейнера стека: {"level":"error","msg":"nabl test error"}. Через 1–2 минуты она должна появиться на вкладке «Ошибки». Подробнее — в статье Ошибки приложения.

#Не приходят события и логи в потоки

Как выглядит. Вкладка «Потоки» пустая или в ней нет нужного потока.

Причины и что сделать.

• Записи шлются не на тот адрес. Правильный адрес — http://nabl-agent:4319/v1/log, метод POST, тело — JSON. Из другого namespace Kubernetes — http://nabl-agent.<namespace>.svc:4319/v1/log.
• Приложение не видит агента по сети — та же проверка, что для трасс.
• Агент только что запустился и отвечает 503 pii key not ready. Повторите отправку через несколько секунд.
• Агент старше 0.8.3 терял одиночную запись в виде {"stream": "…", …поля}. Обновите агента или шлите записи списком в records.

Ответ 202 значит, что агент запись принял. Подробнее — в статье События и логи.

#Переполнен список полей потока

Как выглядит. Над записями потока появляется предупреждение, что список полей переполнен. Новые поля не попадают в фильтры, подсказки поиска и разбивку.

Причина. В потоке может быть до 300 разных полей, у одного объекта — до 30. Почти всегда список засоряют параметры или тела запросов, переданные объектом (query.limit, request_body.*): у каждого эндпоинта свои ключи, и полей становится всё больше.

Что сделать.

1. Исправьте отправку: передавайте такие значения строкой ("query": "{\"limit\":\"10\"}"), а то, по чему нужно фильтровать (status, partner), — отдельными полями. Строка остаётся строкой с агентом 0.11.0 и новее; более старый агент сам разворачивает JSON-строки в поля, поэтому его стоит обновить.
2. Уберите лишние поля из списка: кнопка «Убрать лишние поля» в предупреждении. Записи не меняются, значения по-прежнему ищутся текстом. Поле, которое приложение ещё шлёт, вернётся со следующей записью.

Поля, которые больше не приходят, уходят из списка сами через срок хранения записей — 30 дней.

#Не приходят свои метрики

Как выглядит. Источник метрик добавлен на вкладке «Метрики», а значений нет.

Причины и что сделать.

• Эндпоинт не открывается из сети агента. Метрики опрашивает агент, а не облако. Адрес должен быть внутренним — например, http://worker:9090/metrics. Проверьте его прямо из контейнера агента:

  bashКопировать

  docker compose exec nabl-agent wget -qO- http://worker:9090/metrics

• Эндпоинт требует авторизацию. Агент делает обычный GET без заголовков. Отдавайте метрики без авторизации во внутренней сети.

• Ответ не 200 или формат не распознан. Нужен текстовый формат Prometheus или JSON.

• Пришли не все метрики. За один опрос агент берёт до 200 значений и до 1 МиБ, на стек — до 200 имён метрик. Готовые наборы вроде collectDefaultMetrics() или /actuator/prometheus отдают сотни рядов, и в Наблюдатель попадут случайные первые 200. Сделайте свой небольшой эндпоинт только с нужными метриками.

Подробнее — в статье Свои метрики.

#Почему не приходят уведомления

Уведомление проходит путь: правило проекта → событие в ленте → канал уведомлений → Telegram, MAX или почта. Проверьте каждое звено.

1. Подключён ли канал. Откройте настройки проекта, вкладку «Уведомления». Канал должен быть включён, у Telegram и MAX — заданы токен бота и id чата, у почты — адреса получателей. Если каналов нет, события остаются только в ленте.
2. Доходит ли тестовое сообщение. У Telegram и MAX есть кнопка «Проверить отправку». Если тест не удался, проверьте токен бота и id чата. У групп Telegram id часто начинается с -100.
3. Пропускает ли канал этот уровень. В блоке «О чём сообщать» отмечены уровни: «Ошибка», «Предупреждение», «Успех», «Инфо». По умолчанию «Инфо» выключен, поэтому возвраты «Порог в норме» и «Метрика вернулась к норме» не приходят — только сам алерт. Проверьте и фильтр канала: он мог отсечь нужный тип событий.
4. Есть ли правило и включено ли оно. На вкладке «Правила» часть типовых правил выключена: диск, CPU и память сервера, CPU и троттлинг контейнера. Включите нужные и подберите порог.
5. Было ли событие. Посмотрите вкладку «События» стека. Если события нет, условие правила не выполнилось. Одно срабатывание — одно уведомление: пока состояние не изменилось, повторов не будет.
6. Не пришло ли оно в сводке. Первое уведомление о проблеме в стеке приходит сразу, а всё, что случилось в этом стеке следом за ним в ближайшие 30 секунд, — одним сообщением «Ещё события». Если в канал идёт больше 10 уведомлений в минуту, вместо них приходит одна сводка в минуту. Каждое событие при этом видно в ленте стека.
7. Аномалии сервисов в каналы не приходят. У правила «Аномалия сервиса» уровень «Инфо», поэтому аномалии видны в ленте и помогают найти причину, но в Telegram и на почту по умолчанию не уходят. О сервисах уведомляет правило «Цель сервиса нарушена» — когда сервис выходит за свою цель по времени ответа или ошибкам. Подробнее — Аномалии и поиск причины.
8. Не заглушена ли ошибка. Ошибка приложения в статусе «Без уведомлений» продолжает считаться, но уведомлений о ней нет. Верните их кнопкой «Вернуть уведомления».

Подробнее — в статьях Каналы уведомлений и Правила уведомлений.

#Слишком много уведомлений и ложные срабатывания

Причины и что сделать.

• Порог выставлен наугад. Посмотрите график метрики за неделю и поставьте порог чуть выше обычного пика. Окно — 5–15 минут, агрегация «минимум» или «среднее»: тогда одиночный всплеск не разбудит.
• Шумит важное, но не срочное. Понизьте уровень правила до «Предупреждение» или «Инфо», а в канал дежурного пропускайте только «Ошибку».
• Одна и та же ошибка приложения. Если это известный шум, который не будут чинить, переведите ошибку в «Без уведомлений». Это лучше, чем фильтр канала: остальные ошибки продолжат приходить.
• Аномалии. Аномалии сервисов по умолчанию в каналы не приходят. Если вы подняли уровень правила или шумят аномалии потоков и метрик, снизьте чувствительность правила. Если одна и та же аномалия за сутки начиналась 5 раз, Наблюдатель считает это нормой и перестаёт присылать её, пока она не станет реже.
• Сбой задел много сервисов разом. Отдельные сообщения не сыплются: следом за первым уведомлением приходит «Ещё события», а при потоке больше 10 сообщений в минуту — одна сводка в минуту. Если разом замолчали или снова заработали несколько источников метрик стека, приходит одно сообщение со списком.
• Проекты, созданные до ноября 2026. В них типовые правила для диска, CPU, памяти и файловых дескрипторов могли оказаться включёнными, хотя должны быть выключены. Проверьте их на вкладке «Правила».

Короткие сбои сайта уведомлений не вызывают: при неудачной проверке сайт перепроверяется через 3 секунды, а сбой засчитывается, только если ошибка держится около минуты.

ИИ-ассистент видит, какие правила срабатывали за неделю чаще всего, и предложит пороги по истории — попросите его «подбери пороги шумным правилам». Подробнее об аномалиях — в статье Аномалии.

#Монитор показывает ошибку, а сайт работает

HTTP-проверка ходит на сайт из интернета: делает GET с заголовком User-Agent: NablHealthcheck/1.0 и ждёт ответа до 8 секунд. Успехом считаются коды 2xx и 3xx, редиректы проверка проходит. В браузере сайт может открываться, а у проверки — нет. Текст причины виден на странице монитора.

Проверки несут служебную метку в адресе — параметр nabl_check. Если сайт строго проверяет параметры запроса и отвечает на метку ошибкой, Наблюдатель перестаёт её добавлять сам, настраивать ничего не нужно.

После исправления нажмите на странице монитора «Проверить сейчас», чтобы не ждать следующей проверки. Подробнее — в статье Проверки сайтов.

#Старый агент: что перестаёт работать

Как выглядит. На кнопке «Агент» стека или сервера горит «Обновите агента». Жёлтая отметка значит «доступна новая версия», красная — «версия агента несовместима с платформой» (в подсказке указана минимальная версия). На вкладках сервера может быть сообщение «Нет live-данных… Обновите агент до последней версии».

Новые возможности требуют свежего агента:

Что сделать. Нажмите «Обновите агента» — кабинет покажет команду обновления. Токен и настройки при обновлении сохраняются.

# Docker Compose (в каталоге с docker-compose.yml)
docker compose pull nabl-agent && docker compose up -d nabl-agent

# Kubernetes (если образ указан с тегом latest)
kubectl -n <namespace> rollout restart deployment/nabl-agent

# Сервер Linux
curl -fsSL https://nablserver.ru/update.sh | sudo sh

Если в production образ закреплён по digest, сначала замените digest на новый. Подробнее — в статье Обновление агента.

#Если ничего не помогло

Напишите в поддержку прямо из кабинета: категория «Не работает», текст ошибки, время и что уже пробовали. Если вы работаете через ИИ-ассистента, попросите его написать в поддержку — он сам соберёт технические подробности.

#Что дальше

• Как работает агент — какие доступы нужны агенту и что он отправляет
• Правила уведомлений — как настроить алерты без шума
• Поддержка — как написать нам и где смотреть ответ
• Вопросы и ответы — хранение данных, нагрузка, платформы