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

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

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

В этом разделе описано, как настроить существующую установку PostgreSQL для отправки метрик в ClickStack, настроив ClickStack OTel collector с приёмником 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: 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 удалите эту строку или настройте корректные сертификаты.

Разверните 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 и убедитесь, что метрики поступают:

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

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

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

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

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

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

Скачайте заранее сгенерированные файлы метрик (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) - Редкие взаимные блокировки

Запустите 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 полностью запустится.

Загрузите метрики в 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"

Проверьте метрики в 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.

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

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

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

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

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

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

Для демо-набора данных установите временной диапазон 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 для конфигурации промышленного развертывания.

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

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

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

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

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

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

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

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

​Запустите ClickStack

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Запустите ClickStack

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

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

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

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

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

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

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

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

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

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

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

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