SensusAgent/docs/collectors/proxvmsystem.md

Коллектор proxvmsystem

Автор: Сергей Антропов
Сайт: https://devops.org.ru
Платформа: Linux
Тип: exec (Go-бинарник)

Описание

Коллектор proxvmsystem объединяет функциональность коллекторов system и gpu, добавляя уникальный идентификатор machine_uid для идентификации виртуальной машины или контейнера в Proxmox инфраструктуре.

Назначение

• Сбор системных метрик (CPU, RAM, сеть, диски, время синхронизации, обновления)
• Сбор информации о GPU устройствах (NVIDIA/AMD)
• Генерация уникального machine_uid на основе /etc/machine-id или /var/lib/dbus/machine-id
• Предоставление единого интерфейса для мониторинга VM/контейнеров с привязкой к уникальному идентификатору

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

proxvmsystem:
  enabled: true
  type: exec
  key: proxvmsystem
  interval: "300s"
  timeout: "60s"
  exec: "./collectors/proxvmsystem"
  platforms: [linux]

Выходные данные

Структура JSON

{
  "collector_name": "proxvmsystem",
  "machine_uid": "e7b3e8ed05a8d0c9",
  "cpu": {
    "usage_percent": 15.2,
    "cores": 4,
    "load_avg": [0.8, 1.2, 1.5]
  },
  "ram": {
    "total_gb": 16.0,
    "used_gb": 8.5,
    "free_gb": 7.5,
    "usage_percent": 53.1
  },
  "swap": {
    "total_gb": 2.0,
    "used_gb": 0.1,
    "free_gb": 1.9,
    "usage_percent": 5.0
  },
  "network": {
    "interfaces": [
      {
        "name": "eth0",
        "speed_mbps": 1000,
        "mac": "00:11:22:33:44:55",
        "ips": ["10.14.246.75/24"],
        "rx_bytes": 1024000,
        "tx_bytes": 2048000
      }
    ]
  },
  "disks": [
    {
      "device": "/dev/sda",
      "mountpoint": "/",
      "total_gb": 50.0,
      "used_gb": 25.0,
      "free_gb": 25.0,
      "usage_percent": 50.0
    }
  ],
  "time_sync": {
    "ntp_sync": true,
    "ntp_offset_ms": 0.5,
    "system_time": "2024-01-15T10:30:00Z"
  },
  "updates": {
    "available": 5,
    "security": 2,
    "last_check": "2024-01-15T09:00:00Z"
  },
  "gpu": [
    {
      "id": "0",
      "name": "NVIDIA GeForce RTX 3080",
      "driver_version": "470.86",
      "memory_total_mb": 10240,
      "memory_used_mb": 2048,
      "memory_free_mb": 8192,
      "utilization_percent": 25.0,
      "temperature_c": 65,
      "power_usage_w": 180
    }
  ],
  "gpu_summary": {
    "total_gpus": 1,
    "total_memory_mb": 10240,
    "total_utilization_percent": 25.0,
    "total_power_usage_w": 180
  },
  "execution_time_ms": 1250,
  "execution_time_seconds": 1.25
}

Поля данных

Основные поля

• collector_name (string) - имя коллектора: "proxvmsystem"
• machine_uid (string) - уникальный идентификатор машины (SHA256 хэш от machine-id)

Системные метрики

• cpu (object) - информация о процессоре

  • usage_percent (float) - загрузка CPU в процентах
  • cores (int) - количество ядер
  • load_avg (array) - средняя загрузка за 1, 5, 15 минут

• ram (object) - информация об оперативной памяти

  • total_gb (float) - общий объем RAM в GB
  • used_gb (float) - используемый объем RAM в GB
  • free_gb (float) - свободный объем RAM в GB
  • usage_percent (float) - процент использования RAM

• swap (object) - информация о swap

  • total_gb (float) - общий объем swap в GB
  • used_gb (float) - используемый объем swap в GB
  • free_gb (float) - свободный объем swap в GB
  • usage_percent (float) - процент использования swap

• network (object) - информация о сетевых интерфейсах

  • interfaces (array) - массив сетевых интерфейсов
    • name (string) - имя интерфейса
    • speed_mbps (int) - скорость в Mbps
    • mac (string) - MAC адрес
    • ips (array) - IP адреса
    • rx_bytes (int) - получено байт
    • tx_bytes (int) - отправлено байт

• disks (array) - информация о дисках

  • device (string) - устройство
  • mountpoint (string) - точка монтирования
  • total_gb (float) - общий размер в GB
  • used_gb (float) - используемый размер в GB
  • free_gb (float) - свободный размер в GB
  • usage_percent (float) - процент использования

• time_sync (object) - информация о синхронизации времени

  • ntp_sync (bool) - синхронизация с NTP
  • ntp_offset_ms (float) - смещение от NTP в миллисекундах
  • system_time (string) - системное время

• updates (object) - информация об обновлениях

  • available (int) - количество доступных обновлений
  • security (int) - количество обновлений безопасности
  • last_check (string) - время последней проверки

GPU метрики

• gpu (array) - информация о GPU устройствах

  • id (string) - ID GPU
  • name (string) - название GPU
  • driver_version (string) - версия драйвера
  • memory_total_mb (int) - общая память в MB
  • memory_used_mb (int) - используемая память в MB
  • memory_free_mb (int) - свободная память в MB
  • utilization_percent (float) - загрузка GPU в процентах
  • temperature_c (int) - температура в градусах Цельсия
  • power_usage_w (int) - потребление энергии в ваттах

• gpu_summary (object) - агрегированная информация о GPU

  • total_gpus (int) - общее количество GPU
  • total_memory_mb (int) - общая память всех GPU в MB
  • total_utilization_percent (float) - средняя загрузка GPU
  • total_power_usage_w (int) - общее потребление энергии

Метаданные

• execution_time_ms (int) - время выполнения коллектора в миллисекундах
• execution_time_seconds (float) - время выполнения коллектора в секундах

Генерация machine_uid

Коллектор генерирует уникальный идентификатор machine_uid на основе machine-id системы:

1. Чтение machine-id: Пытается прочитать из /etc/machine-id или /var/lib/dbus/machine-id
2. Генерация хэша: Создает SHA256 хэш от machine-id
3. Усечение: Берет первые 16 символов хэша для компактности

func getMachineIDFromHost() string {
    paths := []string{
        "/etc/machine-id",
        "/var/lib/dbus/machine-id",
    }
    
    for _, path := range paths {
        if data, err := os.ReadFile(path); err == nil {
            machineID := strings.TrimSpace(string(data))
            if machineID != "" {
                hash := sha256.Sum256([]byte(machineID))
                return hex.EncodeToString(hash[:])[:16]
            }
        }
    }
    
    return ""
}

Зависимости

Системные команды

• df - информация о дисках
• ntpq - информация о NTP синхронизации
• timedatectl - информация о времени системы
• apt - информация об обновлениях (Ubuntu/Debian)
• yum - информация об обновлениях (CentOS/RHEL)

GPU команды

• nvidia-smi - информация о NVIDIA GPU
• rocm-smi - информация об AMD GPU

Файлы системы

• /proc/stat - статистика CPU
• /proc/meminfo - информация о памяти
• /proc/loadavg - средняя загрузка системы
• /sys/class/net/<iface>/speed - скорость сетевых интерфейсов
• /etc/machine-id - уникальный идентификатор машины
• /var/lib/dbus/machine-id - альтернативный путь к machine-id

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

Запуск коллектора

# Прямой запуск
./collectors/proxvmsystem

# С переменными окружения
COLLECTOR_TIMEOUT=60s ./collectors/proxvmsystem

Интеграция с агентом

Коллектор автоматически запускается агентом согласно конфигурации в config.yaml.

Ограничения

• Работает только на Linux системах
• Требует права на чтение системных файлов
• GPU метрики доступны только при наличии соответствующих драйверов
• Время выполнения может варьироваться в зависимости от количества GPU и системных ресурсов

Логирование

Коллектор выводит отладочную информацию в stderr для диагностики проблем:

• Ошибки чтения системных файлов
• Проблемы с выполнением команд
• Ошибки парсинга данных

Примеры использования

Мониторинг VM в Proxmox

# Получение machine_uid VM
ssh vm-host "./collectors/proxvmsystem" | jq '.machine_uid'

# Сравнение с данными от proxvms коллектора на Proxmox ноде
ssh proxmox-node "./collectors/proxvms" | jq '.vms[] | select(.machine_uid == "e7b3e8ed05a8d0c9")'

Мониторинг производительности

# Загрузка CPU и GPU
./collectors/proxvmsystem | jq '{cpu: .cpu.usage_percent, gpu: .gpu_summary.total_utilization_percent}'

# Использование памяти
./collectors/proxvmsystem | jq '{ram: .ram.usage_percent, swap: .swap.usage_percent}'

Связанные коллекторы

• system - базовые системные метрики
• gpu - информация о GPU устройствах
• proxvms - информация о VM/контейнерах Proxmox
• proxnode - информация о Proxmox нодах
• proxcluster - информация о Proxmox кластере