Мониторинг логов PostgreSQL с помощью ClickStack

Кратко

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

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

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

Оценочное время: 10–15 минут

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

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

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

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

• Запущенный экземпляр ClickStack
• Установленный PostgreSQL версии 9.6 или новее
• Доступ для изменения конфигурационных файлов PostgreSQL
• Достаточный объем свободного дискового пространства для файлов журналов

Настройка логирования PostgreSQL

PostgreSQL поддерживает несколько форматов логов. Для структурированного парсинга с OpenTelemetry рекомендуется формат CSV, который обеспечивает согласованный и легко парсируемый вывод.

Файл postgresql.conf обычно расположен по пути:

• Linux (apt/yum): /etc/postgresql/{version}/main/postgresql.conf
• macOS (Homebrew): /usr/local/var/postgres/postgresql.conf или /opt/homebrew/var/postgres/postgresql.conf
• Docker: Конфигурация обычно настраивается через переменные окружения или смонтированный файл конфигурации

Добавьте или измените следующие параметры в postgresql.conf:

# Требуется для логирования в CSV
logging_collector = on
log_destination = 'csvlog'

# Рекомендуется: логирование подключений
log_connections = on
log_disconnections = on

# Опционально: настройте в соответствии с потребностями мониторинга
#log_min_duration_statement = 1000  # Логировать запросы длительностью более 1 секунды
#log_statement = 'ddl'               # Логировать DDL-операторы (CREATE, ALTER, DROP)
#log_checkpoints = on                # Логировать активность контрольных точек
#log_lock_waits = on                 # Логировать ожидания блокировок

Примечание

В данном руководстве используется формат csvlog PostgreSQL для надёжного структурированного парсинга. Если вы используете форматы stderr или jsonlog, необходимо соответствующим образом скорректировать конфигурацию коллектора OpenTelemetry.

После внесения этих изменений перезапустите PostgreSQL:

# Для systemd
sudo systemctl restart postgresql

# Для Docker
docker restart

Проверьте, что логи записываются:

# Расположение логов по умолчанию в Linux
tail -f /var/lib/postgresql/{version}/main/log/postgresql-*.log

# macOS Homebrew
tail -f /usr/local/var/postgres/log/postgresql-*.log

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

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

Создайте файл postgres-logs-monitoring.yaml со следующей конфигурацией:

receivers:
  filelog/postgres:
    include:
      - /var/lib/postgresql/*/main/log/postgresql-*.csv # Укажите путь в соответствии с вашей установкой PostgreSQL
    start_at: end
    multiline:
      line_start_pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}'
    operators:
      - type: csv_parser
        parse_from: body
        parse_to: attributes
        header: 'log_time,user_name,database_name,process_id,connection_from,session_id,session_line_num,command_tag,session_start_time,virtual_transaction_id,transaction_id,error_severity,sql_state_code,message,detail,hint,internal_query,internal_query_pos,context,query,query_pos,location,application_name,backend_type,leader_pid,query_id'
        lazy_quotes: true
        
      - type: time_parser
        parse_from: attributes.log_time
        layout: '%Y-%m-%d %H:%M:%S.%L %Z'
      
      - type: add
        field: attributes.source
        value: "postgresql"
      
      - type: add
        field: resource["service.name"]
        value: "postgresql-production"

service:
  pipelines:
    logs/postgres:
      receivers: [filelog/postgres]
      processors:
        - memory_limiter
        - transform
        - batch
      exporters:
        - clickhouse

Эта конфигурация:

• Считывает CSV‑логи PostgreSQL из стандартного расположения
• Обрабатывает многострочные записи логов (ошибки часто занимают несколько строк)
• Разбирает формат CSV со всеми стандартными полями журнала PostgreSQL
• Извлекает временные метки, чтобы сохранить исходное время логов
• Добавляет атрибут source: postgresql для последующей фильтрации в HyperDX
• Направляет логи в экспортер ClickHouse через отдельный pipeline

Примечание

• Определяйте новые приёмники и конвейеры только в пользовательской конфигурации
• Процессоры (memory_limiter, transform, batch) и экспортёры (clickhouse) уже определены в базовой конфигурации ClickStack — достаточно просто ссылаться на них по имени
• Оператор csv_parser извлекает все стандартные поля CSV‑логов PostgreSQL и преобразует их в структурированные атрибуты
• Эта конфигурация использует start_at: end, чтобы избежать повторного приёма логов при перезапуске коллектора. Для тестирования измените на start_at: beginning, чтобы сразу увидеть ранее собранные логи.
• Измените путь в параметре include так, чтобы он соответствовал расположению каталога журналов PostgreSQL

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

Чтобы включить пользовательскую конфигурацию коллектора в существующем развертывании ClickStack, необходимо:

1. Смонтируйте файл пользовательской конфигурации по пути /etc/otelcol-contrib/custom.config.yaml
2. Задайте переменную окружения CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml
3. Смонтируйте директорию с журналами PostgreSQL, чтобы коллектор мог их считывать

Вариант 1: Docker Compose

Обновите конфигурацию развёртывания ClickStack:

services:
  clickstack:
    # ... существующая конфигурация ...
    environment:
      - CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml
      # ... другие переменные окружения ...
    volumes:
      - ./postgres-logs-monitoring.yaml:/etc/otelcol-contrib/custom.config.yaml:ro
      - /var/lib/postgresql:/var/lib/postgresql:ro
      # ... другие тома ...

Вариант 2: Docker Run (образ «всё в одном»)

Если вы используете универсальный образ с docker run:

docker run --name clickstack \
  -p 8080:8080 -p 4317:4317 -p 4318:4318 \
  -e CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml \
  -v "$(pwd)/postgres-logs-monitoring.yaml:/etc/otelcol-contrib/custom.config.yaml:ro" \
  -v /var/lib/postgresql:/var/lib/postgresql:ro \
  docker.hyperdx.io/hyperdx/hyperdx-all-in-one:latest

Примечание

Убедитесь, что коллектор ClickStack имеет необходимые права для чтения файлов журналов PostgreSQL. В production-среде используйте монтирование только для чтения (:ro) и следуйте принципу минимальных привилегий.

Проверка логов в HyperDX

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

1. Перейдите на экран поиска
2. Установите параметр Source в значение Logs
3. Отфильтруйте по source:postgresql, чтобы увидеть логи, относящиеся к PostgreSQL
4. Вы увидите структурированные записи журнала с полями user_name, database_name, error_severity, message, query и т. д.

Демонстрационный набор данных

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

Загрузка демонстрационного набора данных

Загрузите пример файла логов:

curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/postgres/postgresql.log

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

Создайте файл с именем postgres-logs-demo.yaml со следующей конфигурацией:

cat > postgres-logs-demo.yaml << 'EOF'
receivers:
  filelog/postgres:
    include:
      - /tmp/postgres-demo/postgresql.log
    start_at: beginning  # Читать с начала для демонстрационных данных
    multiline:
      line_start_pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}'
    operators:
      - type: csv_parser
        parse_from: body
        parse_to: attributes
        header: 'log_time,user_name,database_name,process_id,connection_from,session_id,session_line_num,command_tag,session_start_time,virtual_transaction_id,transaction_id,error_severity,sql_state_code,message,detail,hint,internal_query,internal_query_pos,context,query,query_pos,location,application_name,backend_type,leader_pid,query_id'
        lazy_quotes: true
        
      - type: time_parser
        parse_from: attributes.log_time
        layout: '%Y-%m-%d %H:%M:%S.%L %Z'
      
      - type: add
        field: attributes.source
        value: "postgresql-demo"
      
      - type: add
        field: resource["service.name"]
        value: "postgresql-demo"

service:
  pipelines:
    logs/postgres-demo:
      receivers: [filelog/postgres]
      processors:
        - memory_limiter
        - transform
        - batch
      exporters:
        - clickhouse
EOF

Запуск ClickStack с демонстрационной конфигурацией

Запустите ClickStack с демонстрационными логами и конфигурацией:

docker run --name clickstack-demo \
  -p 8080:8080 -p 4317:4317 -p 4318:4318 \
  -e CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml \
  -v "$(pwd)/postgres-logs-demo.yaml:/etc/otelcol-contrib/custom.config.yaml:ro" \
  -v "$(pwd)/postgresql.log:/tmp/postgres-demo/postgresql.log:ro" \
  docker.hyperdx.io/hyperdx/hyperdx-all-in-one:latest

Проверка логов в HyperDX

После запуска ClickStack:

1. Откройте HyperDX и войдите в свою учетную запись (при необходимости сначала создайте её)
2. Перейдите в раздел Search и выберите источник Logs
3. Установите диапазон времени: 2025-11-09 00:00:00 - 2025-11-12 00:00:00

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

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

Дашборды и визуализация

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

Скачать конфигурацию дашборда

Импорт готового дашборда

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

3. Загрузите файл postgresql-logs-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 | head -10

В HyperDX не отображаются логи

Проверьте, что в итоговую конфигурацию включён ваш приёмник filelog:

docker exec <контейнер> cat /etc/otel/supervisor-data/effective.yaml | grep -A 10 filelog

Проверьте наличие ошибок в логах коллектора:

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

Если вы используете демонстрационный набор данных, убедитесь, что файл журнала доступен:

docker exec <container> cat /tmp/postgres-demo/postgresql.log | wc -l

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

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

• Настройте оповещения для критических событий (сбоев подключения, медленных запросов, всплесков ошибок)
• Коррелируйте логи с метриками PostgreSQL для всестороннего мониторинга базы данных
• Создавайте пользовательские дашборды для характерных для приложения шаблонов запросов
• Настройте log_min_duration_statement для выявления медленных запросов с учётом ваших требований к производительности

Использование в продакшене

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