Skip to content

kv1sidisi/pg-bash-exporter

BranchesTags

Repository files navigation

PG-Bash Exporter

PG-Bash Exporter — это конфигурируемый экспортер для Prometheus, написанный на Go, который позволяет собирать кастомные метрики, выполняя любые shell-команды.

Оглавление

Введение

Часто стандартных метрик (нагрузка на процессор, использование памяти) бывает недостаточно. Возникает необходимость следить за чем-то уникальным: например, количеством активных пользователей в приложении, числом файлов в определённой папке или результатом работы специфической программы. Писать для каждой такой мелочи отдельный экспортер — долго и неудобно. Этот инструмент решает эту проблему, позволяя описать все нужные метрики и команды для их получения в одном простом конфигурационном файле.

Ключевые особенности

  • Гибкость: Позволяет собирать метрики на основе вывода любых shell-команд и скриптов.

  • Конфигурация в YAML: Все метрики настраиваются в одном YAML-файле. Поддерживается парсинг вывода одной команды на несколько метрик и создание динамических меток (labels).

  • Кэширование: Встроенный механизм кэширования для вывода команд позволяет снизить нагрузку на сервер за счет уменьшения частоты выполнения ресурсоемких скриптов.

  • Безопасность: Настраиваемый черный список команд для предотвращения выполнения потенциально опасных операций.

  • Перезагрузка конфигурации: Поддерживается перезагрузка конфигурации без перезапуска экспортера, что обеспечивает непрерывность мониторинга.

Установка

Скачивание готового файла

  1. Перейдите на страницу "релизы" в репозитории проекта.
  2. Найдите самый свежий релиз.
  3. Скачайте архив, подходящий для вашей системы (например, pg-bash-exporter-linux-amd64.tar.gz).
  4. Если у вас windows то нужно скачать pg-bash-exporter-linux-amd64.exe и пропустить дальнейшие шаги 5,6,7 и перейти в Быстрый старт для запуска.
  5. Распакуйте архив: 
    tar -xvf pg-bash-exporter-linux-amd64.tar.gz
  6. Сделайте файл исполняемым: 
    chmod +x pg-bash-exporter
  7. (Опционально) Переместите файл в директорию, которая есть в вашем PATH, чтобы запускать его из любого места: 
    sudo mv pg-bash-exporter /usr/local/bin/

Сборка из исходного кода

Этот универсальный способ, который подойдет для любой операционной системы. Вам понадобится установленный Go (версии 1.21 или новее) и Git.

  1. Клонируйте репозиторий:

    git clone https://github.com/kvisidisi/pg-bash-exporter.git

  2. Перейдите в папку проекта:

    cd pg-bash-exporter

  3. Соберите проект: Эта команда скомпилирует экспортер в один исполняемый файл с именем pg-bash-exporter.

    go build -v -o pg-bash-exporter ./cmd/exporter

После выполнения этих шагов в папке проекта появится готовый к запуску файл pg-bash-exporter.

Быстрый cтарт

Быстрый старт (Linux/macOS)

  1. Создайте файл конфигурации

    Создайте файл config.yaml со следующим содержимым. Эта конфигурация собирает одну метрику — время работы системы.

    logging:
    level: "info"

metrics:
- name: "system_uptime_seconds"
  help: "Время работы системы в секундах."
  type: "counter"
  command: "cat /proc/uptime | awk '{print $1}'"

  2. Запустите экспортер

    ./pg-bash-exporter --config config.yaml

  3. Проверьте метрики

    curl http://localhost:5252/metrics

Быстрый старт (Windows)

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

  1. Создайте файл конфигурации

    Скопируйте содержимое файла configs/config.windows.example.yaml в новый файл config.yaml в той же папке где и pg-bash-exporter-windows-amd64.exe.

  2. Запустите экспортер

    .\pg-bash-exporter-windows-amd64.exe --config .\config.yaml

  3. Проверьте метрики

    Invoke-RestMethod -Uri http://localhost:5252/metrics

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

Вся настройка экспортера происходит в одном или нескольких YAML-файлах, а также с помощью переменных окружения.

Способы конфигурации

  1. Основной файл config.yaml: Содержит описание метрик, глобальные настройки (таймауты, кеширование) и параметры логирования.
  2. Переменные окружения (или файл .env): Используются для настроек, специфичных для окружения. Переменные из .env имеют приоритет над системными.
    • LISTEN_ADDRESS: Адрес и порт для сервера (по умолчанию :5252).
    • METRICS_PATH: Путь для метрик (по умолчанию /metrics).
    • BLACKLIST_FILE_PATH: Путь к YAML-файлу с дополнительным списком запрещенных команд.

Структура config.yaml

  • global: Глобальные настройки, применяемые ко всем метрикам (например, shell, timeout, cache_ttl).
  • logging: Настройки логирования.
  • metrics: Основная секция, содержащая список всех кастомных метрик.

Полный пример конфигурационного файла со всеми доступными опциями и пояснениями можно найти здесь: configs/config.example.yaml.

Выбор оболочки (shell)

По умолчанию все команды выполняются с помощью bash. Это поведение можно изменить как глобально, так и для каждой отдельной метрики.

  • Глобальная настройка: В секции global файла config.yaml можно указать поле shell. 
    global:
  shell: "powershell"
  • Настройка для метрики: Поле shell можно указать непосредственно в настройках метрики, что переопределит глобальное значение. 
    metrics:
  - name: "windows_processes"
    help: "Количество процессов в Windows."
    type: "gauge"
    shell: "powershell"
    command: "(Get-Process).Count"

Работа с многострочным выводом: postfix_metrics и dynamic_labels

Одной из самых мощных возможностей экспортера является способность обрабатывать команды, которые возвращают несколько строк, и превращать каждую строку в уникальную метрику. Это делается с помощью комбинации постфиксных метрик (postfix_metrics) и динамических меток (dynamic_labels).

Проблема: Дублирование метрик

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

$ ss -ant | awk 'NR>1 {print $1}' | sort | uniq -c
      1 ESTAB
     10 LISTEN

Если вы попытаетесь собрать эти данные с помощью простой конфигурации, вы столкнетесь с проблемой. Экспортер попытается создать две метрики с одинаковым именем network_connections_by_state, что вызовет ошибку в Prometheus.

Решение: postfix_metrics и dynamic_labels

Для предотвращения дублирования метрик необходимо обеспечить их уникальность. Это достигается с помощью динамических меток, которые используют часть вывода команды в качестве значения для метки (label).

Например, для команды ss можно использовать название состояния (ESTAB, LISTEN) как значение для метки state.

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

metrics:
  - name: "network_connections_by_state"
    help: "Количество сетевых соединений по состояниям."
    type: "gauge"
    # Команда возвращает 2 колонки: [количество, состояние]
    command: "ss -ant | awk 'NR>1 {print $1}' | sort | uniq -c"
    # Указываем, что значение метрики находится в первой колонке (индекс 0)
    field: 0
    dynamic_labels:
      # Создаем метку с именем "state"
      - name: "state"
        # Указываем, что значение для этой метки нужно брать из второй колонки (индекс 1)
        field: 1

Что получится в итоге?

С такой конфигурацией экспортер вернет Prometheus две разные, уникальные метрики:

# HELP network_connections_by_state Количество сетевых соединений по состояниям.
# TYPE network_connections_by_state gauge
network_connections_by_state{state="ESTAB"} 1
network_connections_by_state{state="LISTEN"} 10

Теперь у вас есть отдельные временные ряды для каждого состояния, и вы можете строить по ним графики и настраивать алерты.

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

Внутренние метрики экспортера

Экспортер собирает собственные метрики для мониторинга своей работы. Все они начинаются с префикса pg_bash_exporter_.

  • pg_bash_exporter_checks_total (counter) Счетчик общего количества запросов метрик от Prometheus.

  • pg_bash_exporter_check_duration_seconds (histogram) Время, затраченное на сбор всех метрик из конфигурационного файла.

  • pg_bash_exporter_command_errors_total{metric_name="..."} (counter) Счетчик ошибок выполнения команд для каждой метрики. Разделен по меткам metric_name.

  • pg_bash_exporter_cache_hits_total (counter) Количество раз, когда результат выполнения команды был взят из кеша.

  • pg_bash_exporter_cache_misses_total (counter) Количество раз, когда результат выполнения команды не был найден в кеше.

  • pg_bash_exporter_config_reloads_total (counter) Счетчик успешных перезагрузок конфигурации по сигналу SIGHUP.

  • pg_bash_exporter_config_reload_errors_total (counter) Счетчик ошибок при перезагрузке конфигурации.

  • pg_bash_exporter_command_duration_seconds{metric_name="..."} (histogram) Время выполнения каждой отдельной команды. Разделен по меткам metric_name.

  • pg_bash_exporter_concurrent_commands (gauge) Количество одновременно выполняющихся команд.

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

Флаги командной строки и переменные окружения

Для просмотра всех доступных флагов и переменных окружения выполните команду:

./pg-bash-exporter --help
  • --config: Указывает путь к конфигурационному файлу. Также может быть задан через переменную окружения CONFIG_PATH.
  • --validate-config: Проверяет конфигурационный файл на синтаксические ошибки без запуска экспортера.

Перезагрузка конфигурации

Экспортер поддерживает два способа перезагрузки конфигурации без перезапуска процесса:

  1. Через HTTP-эндпоинт (рекомендуемый, кросс-платформенный): Отправьте GET-запрос на эндпоинт /reload.

    curl http://localhost:5252/reload

    Для Windows (PowerShell):

    Invoke-RestMethod -Uri http://localhost:5252/reload

    В ответ сервер вернет статус 200 OK в случае успеха или 500 Internal Server Error с описанием ошибки.

  2. Через системный сигнал (Linux/macOS): Отправьте процессу сигнал SIGHUP.

    kill -HUP $(pgrep -f pg-bash-exporter)

Интеграция с Prometheus

Для сбора метрик добавьте следующую конфигурацию в prometheus.yml:

- job_name: 'bash_exporter'
  static_configs:
    - targets: ['localhost:5252'] # Укажите здесь адрес вашего экспортера

Запуск в Docker Compose

Для тестирования и разработки предоставляется готовый стенд, включающий экспортер, Prometheus и Grafana.

Требования: Установленный и запущенный Docker.

Запуск:

  1. Перейдите в директорию demo:

    cd demo

  2. Выполните команду:

    docker compose up --build -d

Сервисы:

  • Prometheus: http://localhost:9090
  • Grafana: http://localhost:3000 (логин/пароль: admin/admin)
  • Экспортер: http://localhost:5252

В Grafana будет предварительно настроен источник данных Prometheus и дашборд Bash Exporter Metrics.

Остановка:

Для остановки и удаления контейнеров выполните команду в директории demo:

docker compose down

Документация для пользователей

About

A configurable Prometheus Exporter written in Go that collects custom metrics by executing user-defined bash scripts.

Resources

Readme
Activity

Stars

19 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases 2

v1.0.0 Latest
Jul 19, 2025
+ 1 release

Packages

 
 
 

Contributors

Languages