Плагин Docker

Мониторинг контейнеров Docker и ресурсов хоста с метриками CPU, памяти, сети и дискового ввода-вывода по каждому контейнеру.

Обзор

Плагин Docker собирает подробные метрики из Docker Engine, в том числе:

• Статистика контейнеров — использование CPU, использование памяти, лимиты памяти по каждому контейнеру
• Число контейнеров — запущенные, остановленные, приостановленные контейнеры
• Сетевой ввод-вывод — отправленные/принятые байты по каждому контейнеру
• Блочный ввод-вывод — операции чтения/записи на диск по каждому контейнеру
• Состояния контейнеров — статус, состояние здоровья, число перезапусков
• Информация об образах — размеры образов, образы контейнеров

Требования

Версия Docker

• Минимум: Docker 20.10
• Рекомендуется: Docker 23.0 или новее
• Протестировано с: Docker 20.10, 23.0, 24.0, 25.0

Зависимости Python

pip install docker>=6.1.0

Устанавливается автоматически при использовании PLUGINS=docker во время установки агента.

Доступ к сокету Docker

Агент должен иметь доступ к сокету Docker:

# Check socket exists
ls -la /var/run/docker.sock

# Test Docker access
docker ps

Конфигурация

Базовая конфигурация

plugins:
  docker:
    enabled: true
    socket: /var/run/docker.sock

С лимитом контейнеров

plugins:
  docker:
    enabled: true
    socket: /var/run/docker.sock
    max_containers: 50  # Limit monitored containers

Удалённый хост Docker

plugins:
  docker:
    enabled: true
    base_url: tcp://docker-host.example.com:2376
    tls: true
    tls_verify: true
    tls_ca: /path/to/ca.pem
    tls_cert: /path/to/cert.pem
    tls_key: /path/to/key.pem

Все параметры конфигурации

plugins:
  docker:
    enabled: true                           # Enable/disable plugin
    socket: /var/run/docker.sock            # Docker socket path
    base_url: unix://var/run/docker.sock    # Docker API URL
    max_containers: 100                     # Max containers to monitor
    collect_images: true                    # Collect image metrics
    collect_networks: true                  # Collect network metrics
    collect_volumes: true                   # Collect volume metrics
    timeout: 10                             # API request timeout

Переменные окружения

Конфигурацию можно переопределить с помощью переменных окружения:

export DOCKER_SOCKET="/var/run/docker.sock"
export DOCKER_MAX_CONTAINERS="100"

Настройка Docker

Предоставление доступа к сокету

По умолчанию агент работает от root и имеет доступ к сокету Docker. Дополнительная настройка не требуется.

Для агента без root (не рекомендуется):

# Add user to docker group
sudo usermod -aG docker statusradar

# Restart agent
sudo systemctl restart statusradar-agent

Примечание по безопасности: Запуск агента не от root снижает некоторые возможности мониторинга.

Права доступа к сокету Docker

Проверьте права доступа к сокету:

ls -la /var/run/docker.sock

Ожидается:

srw-rw---- 1 root docker 0 Oct 15 10:00 /var/run/docker.sock

Проверка доступа к Docker API

# Test socket access
curl --unix-socket /var/run/docker.sock http://localhost/version

# Using docker CLI
docker info
docker ps

Собираемые метрики

Метрики числа контейнеров

Метрики по каждому контейнеру

Каждый запущенный контейнер в массиве containers включает:

Расчёт процента CPU:

cpu_percent = (cpu_delta / system_cpu_delta) * num_cpus * 100

Процент памяти:

memory_percent = (memory_usage / memory_limit) * 100

Метрики на дашборде

Дашборд StatusRadar отображает:

Карточка обзора

• Total Containers — число запущенных/остановленных/приостановленных
• Resource Usage — агрегированные CPU и память
• Top Containers — наибольшие потребители ресурсов

Список контейнеров

• Имя и ID контейнера
• Статус и uptime
• Использование CPU и памяти
• Сетевой и дисковый ввод-вывод

График использования CPU

• Общее использование CPU контейнерами
• Использование CPU по каждому контейнеру (топ-10)
• Лимиты CPU и троттлинг

График использования памяти

• Общее использование памяти контейнерами
• Использование памяти по каждому контейнеру (топ-10)
• Лимиты памяти

График сетевого ввода-вывода

• Всего отправленных/принятых байт
• Сетевой трафик по каждому контейнеру
• Сетевые ошибки

График блочного ввода-вывода

• Всего чтений/записей на диск
• Дисковый ввод-вывод по каждому контейнеру
• IOPS

Установка

Быстрая установка

PLUGINS='docker' \
TOKEN='your-agent-token' \
bash -c "$(curl -sL https://statusradar.dev/install-agent.sh)"

Установка на существующий агент

1. Убедитесь, что Docker установлен:

   docker --version

2. Проверьте доступ к Docker:

   docker ps

3. Установите зависимость Python:

   cd /opt/statusradar
   source venv/bin/activate  # If using venv
   pip install docker

4. Включите плагин в конфигурации:

   sudo nano /opt/statusradar/config/agent.yaml

   Добавьте:

   plugins:
     docker:
       enabled: true
       socket: /var/run/docker.sock

5. Перезапустите агент:

   sudo systemctl restart statusradar-agent

6. Проверьте:

   sudo journalctl -u statusradar-agent -n 50 --no-pager | grep docker

   Ожидается:

   INFO: Plugin docker: Metrics collected successfully
   INFO: Plugin docker: Monitoring 12 containers

Тестирование

Ручной тест плагина

cd /opt/statusradar
python3 plugins/docker_plugin.py

Ожидаемый вывод:

Plugin name: docker
Enabled: True
Available: True

Metrics Summary:
  Total containers: 15
  Running: 12
  Stopped: 3

Running containers:
  - nginx-web: CPU 2.5%, Memory 100.0 MB (19.5%), Restarts: 0
  - redis-cache: CPU 1.2%, Memory 50.5 MB (9.4%), Restarts: 0
  - postgres-db: CPU 3.1%, Memory 256.0 MB (47.6%), Restarts: 0

Проверка доступа к Docker API

# List containers
docker ps

# Get container stats
docker stats --no-stream

# Check Docker info
docker info

# Test API via socket
curl --unix-socket /var/run/docker.sock http://localhost/containers/json

Устранение неполадок

Плагин не собирает метрики

Проверка 1: Запущен ли Docker?

sudo systemctl status docker

Проверка 2: Может ли агент получить доступ к сокету Docker?

ls -la /var/run/docker.sock
docker ps

Проверка 3: Установлен ли пакет Python?

python3 -c "import docker; print(docker.__version__)"

Проверка 4: Проверьте логи агента

sudo journalctl -u statusradar-agent -n 100 --no-pager | grep docker

Распространённые ошибки

"Permission denied accessing Docker socket"

Ошибка:

ERROR: Plugin docker: Permission denied: '/var/run/docker.sock'

Причина: У агента нет доступа к сокету Docker

Решение:

По умолчанию агент работает от root и должен иметь доступ. Если запускается под другим пользователем:

# Add user to docker group
sudo usermod -aG docker statusradar

# Verify
groups statusradar

# Restart agent
sudo systemctl restart statusradar-agent

"Docker socket not found"

Ошибка:

ERROR: Plugin docker: FileNotFoundError: /var/run/docker.sock

Причины:

1. Docker не установлен
2. Docker не запущен
3. Сокет в другом расположении

Решение:

# Install Docker
curl -fsSL https://get.docker.com | sh

# Start Docker
sudo systemctl start docker
sudo systemctl enable docker

# Check socket location
find /var/run -name "docker.sock"

"No module named 'docker'"

Ошибка:

ERROR: No module named 'docker'

Решение:

pip install docker
# Or if using venv:
cd /opt/statusradar && source venv/bin/activate && pip install docker

"Too many containers"

Предупреждение:

WARNING: Plugin docker: Monitoring 150 containers, performance may be affected

Причина: Большое число контейнеров увеличивает время сбора и использование памяти

Решение:

Ограничьте число отслеживаемых контейнеров:

plugins:
  docker:
    enabled: true
    max_containers: 50  # Monitor top 50 by CPU usage

Высокое использование ресурсов

Симптом: Агент использует избыточно много CPU/памяти

Решения:

1. Уменьшите частоту сбора:

   agent:
     interval: 600  # 10 minutes instead of 5

2. Ограничьте число отслеживаемых контейнеров:

   plugins:
     docker:
       max_containers: 25

3. Отключите подробные метрики:

   plugins:
     docker:
       collect_networks: false
       collect_volumes: false

Влияние на производительность

На Docker

Минимальное влияние:

• Плагин использует Docker stats API (как docker stats)
• Операции только на чтение
• Нет вмешательства в работу контейнеров
• Лёгкий сбор метрик

Бенчмарк:

• Накладные расходы Docker: < 1% CPU на 100 контейнеров
• Нет измеримой деградации производительности

На агент

Использование ресурсов:

• База (5 контейнеров): +25 МБ, +2% CPU
• Средне (25 контейнеров): +50 МБ, +5% CPU
• Высоко (100 контейнеров): +150 МБ, +15% CPU
• Сеть: +5 КБ за сбор

Время сбора:

• 10 контейнеров: 0.5 секунды
• 50 контейнеров: 2 секунды
• 100 контейнеров: 4 секунды

Сценарии использования

1. Мониторинг ресурсов контейнеров

Отслеживайте:

• Использование CPU по каждому контейнеру
• Использование памяти по каждому контейнеру
• Лимиты и ограничения ресурсов

Оповещение при:

• Контейнере, использующем > 80% CPU
• Контейнере, приближающемся к лимиту памяти
• Троттлинге CPU

2. Обнаружение разрастания контейнеров

Отслеживайте:

• Общее число контейнеров
• Остановленные/зомби-контейнеры
• Частоту создания контейнеров

Оповещение при:

• Слишком большом числе остановленных контейнеров (> 50)
• Быстро растущем числе контейнеров

3. Анализ сетевого трафика

Отслеживайте:

• Сетевой ввод-вывод по каждому контейнеру
• Сетевые ошибки
• Использование полосы пропускания

Оповещение при:

• Большом числе сетевых ошибок
• Неожиданных шаблонах трафика
• Насыщении полосы пропускания

4. Мониторинг дискового ввода-вывода

Отслеживайте:

• Чтение/запись на диск по каждому контейнеру
• IOPS по каждому контейнеру
• Ошибки блочного ввода-вывода

Оповещение при:

• Высоком дисковом вводе-выводе (узкое место ввода-вывода)
• Избыточных записях на диск (проблемы с логированием)

5. Отслеживание состояния контейнеров

Отслеживайте:

• Статус контейнеров (running/stopped/failed)
• Число перезапусков
• Uptime контейнеров

Оповещение при:

• Циклах перезапуска контейнеров
• Падениях контейнеров
• Сбоях проверок состояния

Лучшие практики

1. Ограничьте число отслеживаемых контейнеров

Для хостов с большим числом контейнеров:

plugins:
  docker:
    max_containers: 50  # Monitor top 50 by resource usage

Преимущества:

• Меньшее использование ресурсов агентом
• Более быстрый сбор
• Фокус на важных контейнерах

2. Используйте метки контейнеров

Маркируйте контейнеры для лучшей организации:

docker run -d \
  --label app=web \
  --label environment=production \
  --label monitor=true \
  nginx

3. Устанавливайте лимиты ресурсов

Всегда устанавливайте лимиты ресурсов контейнеров:

# docker-compose.yml
services:
  app:
    image: myapp
    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 1G
        reservations:
          memory: 512M

4. Отслеживайте плотность контейнеров

Рекомендация: Не перегружайте хост

Max containers = (Host RAM - 2GB) / Average container RAM

Пример:

• Хост: 16 ГБ RAM
• Средний контейнер: 256 МБ
• Максимум: (16 - 2) / 0.25 = 56 контейнеров

5. Регулярная очистка

Удаляйте неиспользуемые контейнеры и образы:

# Remove stopped containers
docker container prune -f

# Remove unused images
docker image prune -a -f

# Remove unused volumes
docker volume prune -f

6. Используйте проверки состояния

Определяйте проверки состояния в Dockerfile:

HEALTHCHECK --interval=30s --timeout=3s \
  CMD curl -f http://localhost/ || exit 1

Расширенная конфигурация

Docker через TCP

Мониторинг удалённого хоста Docker:

plugins:
  docker:
    enabled: true
    base_url: tcp://docker-host.example.com:2376
    timeout: 15

Docker с TLS

Защищённое соединение с Docker API:

plugins:
  docker:
    enabled: true
    base_url: tcp://docker-host.example.com:2376
    tls: true
    tls_verify: true
    tls_ca: /etc/docker/certs/ca.pem
    tls_cert: /etc/docker/certs/cert.pem
    tls_key: /etc/docker/certs/key.pem

Фильтрация контейнеров (будущая функция)

В настоящее время отслеживаются все контейнеры. Будущие версии будут поддерживать:

plugins:
  docker:
    filters:
      labels:
        - monitor=true
      names:
        - "prod-*"

Примеры конфигураций

Хост для разработки

plugins:
  docker:
    enabled: true
    socket: /var/run/docker.sock
    max_containers: 20

Production-хост контейнеров

plugins:
  docker:
    enabled: true
    socket: /var/run/docker.sock
    max_containers: 100
    collect_images: true
    collect_networks: true

Узел Docker Swarm

plugins:
  docker:
    enabled: true
    socket: /var/run/docker.sock
    max_containers: 200  # Higher limit for swarm

Удалённый хост Docker

plugins:
  docker:
    enabled: true
    base_url: tcp://10.0.0.5:2376
    tls: true
    tls_verify: true
    tls_ca: /path/to/ca.pem
    tls_cert: /path/to/cert.pem
    tls_key: /path/to/key.pem
    timeout: 20

Ограничения

Текущие ограничения

1. Нет фильтрации контейнеров — отслеживаются все контейнеры (решается лимитом max_containers)
2. Нет поддержки Kubernetes — используйте мониторинг для K8s
3. Нет специфичных для Swarm метрик — будет в будущей версии
4. Влияние на производительность при 100+ контейнерах

Масштабируемость

Рекомендуемые лимиты:

• Малые хосты (< 4 ГБ RAM): максимум 25 отслеживаемых контейнеров
• Средние хосты (4–16 ГБ RAM): максимум 50 отслеживаемых контейнеров
• Большие хосты (> 16 ГБ RAM): максимум 100 отслеживаемых контейнеров

Для крупных развёртываний:

• Используйте несколько агентов
• Разворачивайте агент на каждом хосте Docker
• Используйте мониторинг оркестрации контейнеров (Prometheus и т.д.)

Устранение проблем производительности

Медленный сбор

Симптом: Сбор занимает > 5 секунд

Решения:

1. Уменьшите max_containers
2. Увеличьте интервал сбора
3. Проверьте производительность демона Docker

Отладка:

# Time collection manually
time python3 /opt/statusradar/plugins/docker_plugin.py

# Check Docker API response time
time curl --unix-socket /var/run/docker.sock http://localhost/containers/json

Высокое использование памяти

Симптом: Агент использует > 500 МБ RAM

Решения:

1. Уменьшите max_containers
2. Отключите сбор образов/сети
3. Увеличьте пространство swap

Следующие шаги

• Просмотреть все плагины
• Системные требования
• Руководство по конфигурации агента
• Руководство по устранению неполадок