Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

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

View as MarkdownEdit this pageReport an issueSet up docs MCP

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

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

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

Предварительные требования
  • Запущенный экземпляр 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:

# Required for CSV logging
logging_collector = on
log_destination = 'csvlog'

# Recommended: Connection logging
log_connections = on
log_disconnections = on

# Optional: Tune based on your monitoring needs
#log_min_duration_statement = 1000  # Log queries taking more than 1 second
#log_statement = 'ddl'               # Log DDL statements (CREATE, ALTER, DROP)
#log_checkpoints = on                # Log checkpoint activity
#log_lock_waits = on                 # Log lock contention

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

# For systemd
sudo systemctl restart postgresql

# For Docker
docker restart

Проверьте, что записи журнала создаются:

# Default log location on 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 # Adjust to match your PostgreSQL installation
    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 exporter через выделенный конвейер

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

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

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

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

services:
  clickstack:
    # ... existing configuration ...
    environment:
      - CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml
      # ... other environment variables ...
    volumes:
      - ./postgres-logs-monitoring.yaml:/etc/otelcol-contrib/custom.config.yaml:ro
      - /var/lib/postgresql:/var/lib/postgresql:ro
      # ... other volumes ...
Вариант 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 \
  clickhouse/clickstack-all-in-one:latest

Проверка журналов в 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" \
  clickhouse/clickstack-all-in-one:latest

Проверьте журналы в HyperDX

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

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

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

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

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

Скачать файл конфигурации панели мониторинга.

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

  1. Откройте HyperDX и перейдите в раздел Dashboards
  2. Нажмите Import Dashboard в правом верхнем углу в меню с многоточием
Кнопка импорта панели мониторинга
  1. Загрузите файл postgresql-logs-dashboard.json и нажмите Finish Import
Завершение импорта

Откройте панель мониторинга

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

Панель мониторинга журналов

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

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

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

docker exec <container-name> printenv CUSTOM_OTELCOL_CONFIG_FILE

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

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

Журналы не отображаются в HyperDX

Проверьте, что в фактической конфигурации есть ваш ресивер filelog:

docker exec <container> cat /etc/otel/supervisor-data/effective.yaml | grep -A 10 filelog

Проверьте журналы collector на наличие ошибок:

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 для всестороннего мониторинга базы данных
  • Создайте пользовательские панели мониторинга для шаблонов запросов, характерных для вашего приложения
  • Настройте log_min_duration_statement, чтобы выявлять медленные запросы в соответствии с вашими требованиями к производительности

Переход в продакшн

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

Navigation