Мониторинг метрик PostgreSQL в ClickStack

Мониторинг метрик PostgreSQL в ClickStack

Вкратце

Отслеживайте метрики производительности PostgreSQL в ClickStack с помощью приёмника PostgreSQL в OTel. Включает демо-набор данных и преднастроенный дашборд.

​

Интеграция с существующим PostgreSQL

В этом разделе описано, как настроить существующую установку PostgreSQL для отправки метрик в ClickStack, настроив ClickStack OTel collector с приёмником PostgreSQL.

Если вы хотите протестировать интеграцию метрик PostgreSQL перед настройкой собственной среды, вы можете воспользоваться нашим предварительно настроенным демо-набором данных в следующем разделе.

Предварительные требования

• Запущенный экземпляр ClickStack
• Существующая установка PostgreSQL (версии 9.6 или выше)
• Сетевой доступ из ClickStack к PostgreSQL (порт по умолчанию — 5432)
• Пользователь PostgreSQL для мониторинга с соответствующими разрешениями

1. ​

   Убедитесь, что у пользователя мониторинга есть необходимые разрешения

   Для приёмника PostgreSQL требуется пользователь с доступом на чтение к представлениям статистики. Назначьте роль pg_monitor пользователю мониторинга:

   GRANT pg_monitor TO your_monitoring_user;
   
2. ​

   Создайте пользовательскую конфигурацию OTel collector

   ClickStack позволяет расширить базовую конфигурацию OpenTelemetry Collector, смонтировав пользовательский конфигурационный файл и задав переменную окружения.

   Создайте postgres-metrics.yaml:

   receivers:
     postgresql:
       endpoint: postgres-host:5432
       transport: tcp
       username: otel_monitor
       password: ${env:POSTGRES_PASSWORD}
       databases:
         - postgres
         - your_application_db # Замените на фактические имена ваших баз данных
       collection_interval: 30s
       tls:
         insecure: true
   
   processors:
     resourcedetection:
       detectors: [env, system, docker]
       timeout: 5s
     batch:
       timeout: 10s
       send_batch_size: 10000
   
   exporters:
     clickhouse:
       endpoint: tcp://localhost:9000
       database: default
       ttl: 96h
   
   service:
     pipelines:
       metrics/postgres:
         receivers: [postgresql]
         processors: [resourcedetection, batch]
         exporters: [clickhouse]
   

   Параметр tls: insecure: true отключает проверку SSL для разработки и тестирования. Для PostgreSQL в production-среде с включённым SSL удалите эту строку или настройте корректные сертификаты.

3. ​

   Разверните ClickStack с пользовательской конфигурацией

   Смонтируйте пользовательскую конфигурацию:

   docker run -d \
     --name clickstack-postgres \
     -p 8123:8123 -p 9000:9000 -p 4317:4317 -p 4318:4318 \
     -e HYPERDX_API_KEY=your-api-key \
     -e CLICKHOUSE_PASSWORD=your-clickhouse-password \
     -e POSTGRES_PASSWORD=secure_password_here \
     -e CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml \
     -v "$(pwd)/postgres-metrics.yaml:/etc/otelcol-contrib/custom.config.yaml:ro" \
     clickhouse/clickstack:latest
   
4. ​

   Проверьте сбор метрик

   После настройки войдите в HyperDX и убедитесь, что метрики поступают:

   1. Перейдите в Metrics explorer
   2. Найдите метрики, начинающиеся с postgresql (например, postgresql.backends, postgresql.commits)
   3. Вы должны увидеть точки данных метрик, появляющиеся с настроенным интервалом сбора

   Когда метрики начнут поступать, перейдите к разделу Панели мониторинга и визуализация, чтобы импортировать преднастроенный дашборд.

​

Демо-набор данных

Для пользователей, которые хотят протестировать интеграцию метрик PostgreSQL перед настройкой рабочих систем, мы предоставляем заранее сгенерированный датасет с реалистичными паттернами метрик PostgreSQL.

Только метрики на уровне базы данных

Этот демо-набор данных включает только метрики на уровне базы данных, чтобы объем примера оставался небольшим. Метрики таблиц и индексов собираются автоматически при мониторинге реальной базы данных PostgreSQL.

1. ​

   Скачайте пример датасета метрик

   Скачайте заранее сгенерированные файлы метрик (24 часа метрик PostgreSQL с реалистичными паттернами):

   # Скачать gauge-метрики (соединения, размер базы данных)
   curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/postgres/postgres-metrics-gauge.csv
   
   # Скачать sum-метрики (коммиты, откаты, операции)
   curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/postgres/postgres-metrics-sum.csv
   

   Датасет включает реалистичные сценарии:

   • Утренний всплеск соединений (08:00) - Наплыв входов в систему
   • Проблема с производительностью кэша (11:00) - Всплеск Blocks_read
   • Ошибка в приложении (14:00-14:30) - Доля Rollback возрастает до 15%
   • Случаи взаимной блокировки (14:15, 16:30) - Редкие взаимные блокировки
2. ​

   Запустите ClickStack

   Запустите экземпляр ClickStack:

   docker run -d --name clickstack-postgres-demo \
     -p 8080:8080 -p 4317:4317 -p 4318:4318 \
     clickhouse/clickstack-all-in-one:latest
   

   Подождите примерно 30 секунд, пока ClickStack полностью запустится.

3. ​

   Загрузите метрики в ClickStack

   Загрузите метрики напрямую в ClickHouse:

   # Загрузить gauge-метрики
   cat postgres-metrics-gauge.csv | docker exec -i clickstack-postgres-demo \
     clickhouse-client --query "INSERT INTO otel_metrics_gauge FORMAT CSVWithNames"
   
   # Загрузить sum-метрики
   cat postgres-metrics-sum.csv | docker exec -i clickstack-postgres-demo \
     clickhouse-client --query "INSERT INTO otel_metrics_sum FORMAT CSVWithNames"
   
4. ​

   Проверьте метрики в HyperDX

   После загрузки самый быстрый способ увидеть метрики — открыть преднастроенный дашборд.

   Перейдите к разделу Панели мониторинга и визуализации, чтобы импортировать панель мониторинга и сразу просматривать множество метрик PostgreSQL.

   Отображение часового пояса

   HyperDX отображает временные метки в локальном часовом поясе вашего браузера. Демо-данные охватывают период 2025-11-10 00:00:00 - 2025-11-11 00:00:00 (UTC). Установите временной диапазон 2025-11-09 00:00:00 - 2025-11-12 00:00:00, чтобы видеть демо-метрики независимо от вашего местоположения. Когда метрики появятся, можно сузить диапазон до 24 часов для более наглядных визуализаций.

​

Панели мониторинга и визуализация

Чтобы упростить начало мониторинга PostgreSQL в ClickStack, мы предоставляем основные визуализации для метрик PostgreSQL.

1. ​

   конфигурацию панели мониторинга

2. ​

   Импортируйте преднастроенную панель мониторинга

   1. Откройте HyperDX и перейдите в раздел Dashboards
   2. Нажмите Import Dashboard в правом верхнем углу в меню с многоточием

   3. Загрузите файл postgres-metrics-dashboard.json и нажмите Finish Import
3. ​

   Просмотрите панель мониторинга

   Панель мониторинга будет создана со всеми преднастроенными визуализациями:

   Для демо-набора данных установите временной диапазон 2025-11-10 00:00:00 - 2025-11-11 00:00:00 (UTC) (скорректируйте его в соответствии с вашим локальным часовым поясом). По умолчанию у импортированной панели мониторинга временной диапазон не задан.

​

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

​

Пользовательская конфигурация не загружается

Проверьте, что переменная окружения задана:

docker exec <container-name> printenv CUSTOM_OTELCOL_CONFIG_FILE

Убедитесь, что пользовательский файл конфигурации смонтирован:

docker exec <container-name> cat /etc/otelcol-contrib/custom.config.yaml

​

В HyperDX не отображаются метрики

Убедитесь, что PostgreSQL доступен:

docker exec <clickstack-container> psql -h postgres-host -U otel_monitor -d postgres -c "SELECT 1"

Проверьте журналы OTel collector:

docker exec <container> cat /etc/otel/supervisor-data/agent.log | grep -i postgres

​

Ошибки аутентификации

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

docker exec <clickstack-container> printenv POSTGRES_PASSWORD

Проверьте учетные данные напрямую:

psql -h postgres-host -U otel_monitor -d postgres -c "SELECT version();"

​

Дальнейшие шаги

• Настройте оповещения для критических порогов (лимиты подключений, высокая частота откатов, низкий коэффициент попаданий в кэш)
• Включите мониторинг на уровне запросов с помощью расширения pg_stat_statements
• Отслеживайте несколько экземпляров PostgreSQL, дублируя конфигурацию приёмника с разными конечными точками и именами сервисов

​

Переход к промышленной эксплуатации

В этом руководстве для быстрой настройки используется встроенный в ClickStack OpenTelemetry Collector. Для промышленного развертывания мы рекомендуем запускать собственный OTel Collector и отправлять данные в конечную точку OTLP ClickStack. См. Отправка данных OpenTelemetry для конфигурации промышленного развертывания.