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

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

Вкратце

Собирайте и визуализируйте журналы сервера PostgreSQL (в формате CSV) в ClickStack с помощью ресивера OTel filelog. Включает демо-набор данных и преднастроенную панель мониторинга.

​

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

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

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

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

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

1. ​

   Настройте логирование 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 Collector.

   После внесения этих изменений перезапустите 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
   
2. ​

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

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

   Настройка 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:
       # ... существующая конфигурация ...
       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 \
     clickhouse/clickstack-all-in-one:latest
   

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

4. ​

   Проверка журналов в HyperDX

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

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

​

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

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

1. ​

   Скачайте пример набора данных

   Скачайте пример файла журнала:

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

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

   Создайте файл 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
   
3. ​

   Запустите 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
   
4. ​

   Проверьте журналы в 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. ​

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

2. ​

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

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

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

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

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

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