Мониторинг метрик PostgreSQL с помощью ClickStack

Кратко

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

• Настроить OTel collector для сбора метрик PostgreSQL
• Развернуть ClickStack с вашей пользовательской конфигурацией
• Использовать готовый дашборд для визуализации производительности PostgreSQL (транзакции, подключения, размер базы данных, коэффициенты попаданий в кэш)

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

Необходимое время: 10–15 минут

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

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

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

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

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

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

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

GRANT pg_monitor TO your_monitoring_user;

Создайте пользовательскую конфигурацию 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: 1024

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 с включённым SSL удалите эту строку или настройте корректные сертификаты.

Разверните 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

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

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

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

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

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

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

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

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

Загрузите пример набора метрик

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

# Скачивание gauge-метрик (соединения, размер базы данных) \{#download-gauge-metrics-connections-database-size}
curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/postgres/postgres-metrics-gauge.csv

# Скачивание sum-метрик (коммиты, откаты, операции) \{#download-sum-metrics-commits-rollbacks-operations}
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) — уровень откатов возрастает до 15%
• Инциденты взаимоблокировок (14:15, 16:30) — редкие взаимоблокировки

Запустите ClickStack

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

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

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

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

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

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

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

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

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

Перейдите к разделу Dashboards and visualization, чтобы импортировать дашборд и просмотреть множество метрик 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. Откройте HyperDX и перейдите в раздел Dashboards
2. Нажмите Import Dashboard в правом верхнем углу под иконкой с многоточием

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

Просмотр дашборда

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

Примечание

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

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

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

Убедитесь, что задана переменная окружения:

docker exec <имя-контейнера> printenv CUSTOM_OTELCOL_CONFIG_FILE

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

docker exec <имя-контейнера> 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:

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();"

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

После настройки мониторинга метрик PostgreSQL:

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

Переход в production

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