Мониторинг Docker Compose

Мониторинг Docker Compose в Наблюдателе работает через агента — ещё один сервис в вашем docker-compose.yml. Агент сам находит контейнеры своего compose-проекта и раз в 30 секунд отправляет их метрики и статусы: CPU, память, сеть, диск, тома, health-проверки, рестарты, OOM и коды выхода. В приложениях ничего менять не нужно.

Установка занимает пару минут: создать стек, скопировать сервис агента из кабинета, выполнить одну команду.

#Как установить агента в Docker Compose

1. Откройте проект в кабинете и добавьте стек (кнопка «Добавить»). Стек — это одно окружение: один compose-проект.
2. На странице стека нажмите кнопку «Агент» → «Создать агента». Введите название и нажмите «Создать».
3. В окне «Агент создан» в блоке «Где работает стек» выберите «Docker Compose» и скопируйте «Сервис для docker-compose.yml».
4. Вставьте сервис в docker-compose.yml рядом с вашими сервисами и запустите его.

Важно. Токен агента показывается один раз. Сохраните его сразу — посмотреть его ещё раз нельзя, можно только выпустить новый.

Сервис, который выдаёт кабинет, выглядит так:

services:
  nabl-agent:
    image: velgir/nabl-agent:latest
    restart: unless-stopped
    # Как requests/limits в манифесте Kubernetes: агент не отнимет ресурсы у приложения.
    mem_limit: 256m
    cpus: 1
    environment:
      NABL_AGENT_TOKEN: <ТОКЕН_АГЕНТА>
      NABL_BASE_URL: https://app.nablserver.ru
      NABL_INTERVAL: 30
      NABL_OTLP_ENABLED: "true"
      NABL_OTLP_GRPC_ADDR: "0.0.0.0:4317"
      NABL_OTLP_HTTP_ADDR: "0.0.0.0:4318"
      NABL_AGENT_CAPTURE_HTTP_ADDR: "0.0.0.0:4319"
    expose:
      - "4317"
      - "4318"
      - "4319"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock

Если в вашем файле уже есть раздел services:, добавьте в него только блок nabl-agent. Затем выполните в каталоге с docker-compose.yml:

docker compose up -d nabl-agent

Что важно в сервисе:

Порты указаны в expose, а не в ports: публиковать их наружу не нужно. Ваши сервисы обращаются к агенту по имени nabl-agent во внутренней сети compose.

#Токен — в файл .env

Чтобы токен не попал в git, вынесите его в .env рядом с docker-compose.yml:

    environment:
      NABL_AGENT_TOKEN: ${NABL_AGENT_TOKEN}

# .env
NABL_AGENT_TOKEN=<ТОКЕН_АГЕНТА>

#Если у сервисов свои сети

Если в compose у приложений заданы свои networks:, добавьте агента в те же сети. Иначе метрики контейнеров будут приходить, но трассы и события от приложений до агента не дойдут.

  nabl-agent:
    # …
    networks:
      - backend

#Версия образа в production

latest удобен для старта. В production закрепите версию: тегом (velgir/nabl-agent:0.14.1) или по digest (velgir/nabl-agent@sha256:…). Как обновлять — в статье Обновление агента и токен.

#Как проверить, что данные пошли

Окно в кабинете показывает «Ждём первое подключение агента…», а после первой отправки — «Агент на связи — данные начали поступать». Обычно это занимает до 30 секунд.

Если окно уже закрыто, проверьте сами:

docker compose logs -f nabl-agent

В логе должна быть строка запуска с версией и режимом, например nabl-agent 0.14.1 mode=compose …, и строка mode auto: detected compose project="…" с именем вашего проекта. Строк с 401 и config: быть не должно.

В кабинете:

• на странице стека появилась вкладка «Контейнеры» со списком сервисов;
• в разделе «Агенты» у агента статус «Активен» и свежее время последней отправки.

#Что собирает агент Docker Compose

Агент собирает данные сам, без изменений в коде приложений.

Полные логи контейнеров Наблюдатель не хранит. Агент читает stdout/stderr и отправляет только распознанные ошибки. Весь лог можно смотреть вживую, пока он открыт в кабинете, — см. Живые логи. Если логи нужно хранить и искать, отправляйте их как события и логи.

С агентом 0.12 по смене образа в ленте стека появляется событие обновления, а с 0.13 — даже если образ тот же, но поменялась конфигурация сервиса.

Размер баз. Раз в 3 минуты агент выполняет в контейнерах баз короткий запрос только на чтение, чтобы узнать их размер. Если это нежелательно, добавьте агенту NABL_DB_SIZE_PROBE: "false" (агент 0.8.1+) — пропадёт только размер баз. Подробнее — в статье Как работает агент.

Что делать с этими данными дальше — смотреть графики во вкладке «Контейнеры» и настроить уведомления о падениях, OOM и нехватке памяти.

#Несколько compose-проектов на одном сервере

Агент видит только контейнеры своего compose-проекта — тех, у кого та же метка com.docker.compose.project. Имя проекта по умолчанию — имя каталога с docker-compose.yml, его можно задать флагом -p или переменной COMPOSE_PROJECT_NAME.

Поэтому:

• Каждому compose-проекту — свой стек и свой агент. Например, shop и blog в разных каталогах на одной машине — это два стека в Наблюдателе и два сервиса nabl-agent, каждый в своём docker-compose.yml со своим токеном.
• Один проект из нескольких файлов (docker compose -f base.yml -f prod.yml) — это один проект: достаточно одного агента в любом из файлов.
• Метрики самого сервера (диски, CPU хоста, swap) compose-агент не собирает. Для них поставьте на ту же машину агента сервера. Оба агента работают независимо, а стек с сервером Наблюдатель свяжет сам. С агентами 0.14 агент сервера ещё и видит сетевые соединения контейнеров — на карте появятся связи с сервисами без трассировки.

#Частые ошибки

Если причина не нашлась — загляните в решение проблем.

Совет. ИИ-ассистент через MCP может создать стек, выдать готовый сервис агента и проверить, что данные пошли. См. ИИ-ассистент.

#Как удалить агента

Удалите сервис nabl-agent из docker-compose.yml и выполните:

docker compose up -d --remove-orphans

Затем удалите агента в кабинете в разделе «Агенты», чтобы его токен перестал действовать.

#Что дальше

• Контейнеры — графики, статусы и рестарты сервисов.
• Ошибки приложений — что агент находит в логах.
• Трассировка — подключить OpenTelemetry к агенту.
• Как работает агент — доступы, нагрузка и безопасность.