> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-8c05c8a2.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

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

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

export const TrackedLink = ({href, eventName, children, ...rest}) => {
  const handleClick = () => {
    try {
      if (typeof window !== "undefined" && window.galaxy && eventName) {
        window.galaxy.track(eventName, {
          interaction: "click"
        });
      }
    } catch (e) {}
  };
  return <a href={href} onClick={handleClick} {...rest}>
      {children}
    </a>;
};

export const Image = ({img, alt, size}) => {
  return <Frame>
      <img src={img} alt={alt} />
    </Frame>;
};

<Info>
  **Вкратце**

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

<div id="existing-postgres">
  ## Интеграция с существующим PostgreSQL
</div>

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

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

<div id="prerequisites">
  ##### Предварительные требования
</div>

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

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

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

    ```sql theme={null}
    GRANT pg_monitor TO your_monitoring_user;
    ```
  </Step>

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

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

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

    ```yaml theme={null}
    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]
    ```

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

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

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

    ```bash theme={null}
    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
    ```
  </Step>

  <Step>
    #### Проверьте сбор метрик

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

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

    Когда метрики начнут поступать, перейдите к разделу [Панели мониторинга и визуализация](#dashboards), чтобы импортировать преднастроенный дашборд.
  </Step>
</Steps>

<div id="demo-dataset">
  ## Демо-набор данных
</div>

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

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

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

<Steps>
  <Step>
    #### Скачайте пример датасета метрик

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

    ```bash theme={null}
    # Скачать 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)** - Редкие взаимные блокировки
  </Step>

  <Step>
    #### Запустите ClickStack

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

    ```bash theme={null}
    docker run -d --name clickstack-postgres-demo \
      -p 8080:8080 -p 4317:4317 -p 4318:4318 \
      clickhouse/clickstack-all-in-one:latest
    ```

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

  <Step>
    #### Загрузите метрики в ClickStack

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

    ```bash theme={null}
    # Загрузить 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"
    ```
  </Step>

  <Step>
    #### Проверьте метрики в HyperDX

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

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

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

      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 часов для более наглядных визуализаций.
    </Info>
  </Step>
</Steps>

<div id="dashboards">
  ## Панели мониторинга и визуализация
</div>

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

<Steps>
  <Step>
    #### <TrackedLink href={'/ru/examples/postgres-metrics-dashboard.json'} download="postgres-metrics-dashboard.json" eventName="docs.postgres_metrics_monitoring.dashboard_download">Скачать</TrackedLink> конфигурацию панели мониторинга
  </Step>

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

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

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8c05c8a2/mGB-7MnBG_6npuhw/images/clickstack/import-dashboard.png?fit=max&auto=format&n=mGB-7MnBG_6npuhw&q=85&s=21af53f2ddc48534745ebc3f01de39ef" alt="Кнопка импорта панели мониторинга" width="3024" height="556" data-path="images/clickstack/import-dashboard.png" />

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

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8c05c8a2/mGB-7MnBG_6npuhw/images/clickstack/postgres/import-dashboard.png?fit=max&auto=format&n=mGB-7MnBG_6npuhw&q=85&s=06633de13d9406e87da357adc9a339d8" alt="Диалог завершения импорта" width="3808" height="1910" data-path="images/clickstack/postgres/import-dashboard.png" />
  </Step>

  <Step>
    #### Просмотрите панель мониторинга

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

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8c05c8a2/mGB-7MnBG_6npuhw/images/clickstack/postgres/postgres-metrics-dashboard.png?fit=max&auto=format&n=mGB-7MnBG_6npuhw&q=85&s=c6fed08b4556d8af308767a33aa8d4fd" alt="Панель мониторинга метрик PostgreSQL" width="3808" height="1910" data-path="images/clickstack/postgres/postgres-metrics-dashboard.png" />

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

<div id="troubleshooting">
  ## Устранение неполадок
</div>

<div id="troubleshooting-not-loading">
  ### Пользовательская конфигурация не загружается
</div>

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

```bash theme={null}
docker exec <container-name> printenv CUSTOM_OTELCOL_CONFIG_FILE
```

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

```bash theme={null}
docker exec <container-name> cat /etc/otelcol-contrib/custom.config.yaml
```

<div id="no-metrics">
  ### В HyperDX не отображаются метрики
</div>

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

```bash theme={null}
docker exec <clickstack-container> psql -h postgres-host -U otel_monitor -d postgres -c "SELECT 1"
```

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

```bash theme={null}
docker exec <container> cat /etc/otel/supervisor-data/agent.log | grep -i postgres
```

<div id="auth-errors">
  ### Ошибки аутентификации
</div>

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

```bash theme={null}
docker exec <clickstack-container> printenv POSTGRES_PASSWORD
```

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

```bash theme={null}
psql -h postgres-host -U otel_monitor -d postgres -c "SELECT version();"
```

<div id="next-steps">
  ## Дальнейшие шаги
</div>

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

<div id="going-to-production">
  ## Переход к промышленной эксплуатации
</div>

В этом руководстве для быстрой настройки используется встроенный в ClickStack OpenTelemetry Collector. Для промышленного развертывания мы рекомендуем запускать собственный OTel Collector и отправлять данные в конечную точку OTLP ClickStack. См. [Отправка данных OpenTelemetry](/ru/clickstack/ingesting-data/opentelemetry) для конфигурации промышленного развертывания.