Мониторинг PostgreSQL с помощью Proto Observability

На этой странице:

• Сбор метрик PostgreSQL
  • Конфигурация PostgreSQL
    • Пользователь для мониторинга
    • pg_stat_statements (метрики запросов)
  • Конфигурация ProtoOBP агента
    • Если агент запускается в виде службы на хосте
    • Если агент запускается в виде Docker контейнера
  • Проверка
  • Собираемые метрики
    • Лейблы
      • Общие (на всех метриках)
      • Специфичные для PostgreSQL
    • Соединения и сессии
    • Транзакции
    • Доступ к данным (на уровне базы)
    • Bgwriter / checkpointer
    • WAL
    • Размер баз данных
    • Метрики на уровне таблицы
    • Метрики на уровне индекса
    • TOAST
    • Bloat (collect_bloat_metrics)
    • Активность (collect_activity_metrics)
    • Функции (collect_function_metrics)
    • Репликация
    • Метрики запросов (pg_stat_statements)
  • Ключевые метрики для дашбордов и алертов
• Сбор логов PostgreSQL
  • Конфигурация ProtoOBP агента
    • Если агент запускается в виде службы на хосте
    • Если агент запускается в виде Docker контейнера
  • Проверка

Сбор метрик PostgreSQL

Интеграция postgres подключается к PostgreSQL по обычному wire-протоколу (порт 5432), а не через JMX — поэтому образ агента используется обычный, без суффикса -jmx. Проверка читает системные представления pg_stat_*, pg_class, pg_locks, pg_settings и (опционально) pg_stat_statements, поэтому пользователю агента достаточно прав read-only.

Часть семейств метрик включается отдельными флагами в instances::

Конфигурация PostgreSQL

Пользователь для мониторинга

Создайте пользователя с правами read-only для агента ProtoOBP:

• Для PostgreSQL версии 10 и выше — встроенная роль pg_monitor уже включает pg_read_all_settings, pg_read_all_stats и pg_stat_scan_tables, то есть всё необходимое для pg_stat_* и pg_stat_statements:

  CREATE USER protoobp WITH PASSWORD '<PASSWORD>';
  GRANT pg_monitor TO protoobp;
  

• Для более старых версий PostgreSQL роли pg_monitor нет — выдайте права на представления статистики напрямую:

  CREATE USER protoobp WITH PASSWORD '<PASSWORD>';
  -- выдайте SELECT на нужные представления статистики
  -- (pg_stat_database, pg_stat_bgwriter, pg_stat_activity, …)
  GRANT SELECT ON pg_stat_database, pg_stat_bgwriter, pg_stat_activity TO protoobp;
  

GRANT USAGE ON SCHEMA <schema> TO protoobp;
GRANT SELECT ON ALL TABLES IN SCHEMA <schema> TO protoobp;
ALTER DEFAULT PRIVILEGES IN SCHEMA <schema> GRANT SELECT ON TABLES TO protoobp;

pg_stat_statements (метрики запросов)

Семейство postgresql_queries_* (метрики уровня запроса — счётчик выполнений, суммарное время, прочитанные/записанные блоки и т.п.) собирается из расширения pg_stat_statements и доступно только при включённом сборе метрик уровня SQL-запросов (dbm: true).

1. Добавьте библиотеку в shared_preload_libraries (требует рестарта сервера) — например, в postgresql.conf:

   shared_preload_libraries = 'pg_stat_statements'
   pg_stat_statements.track = all
   

   В Docker это удобно сделать флагом командной строки:

   services:
     postgresql:
       image: postgres:16
       command:
         - postgres
         - -c
         - shared_preload_libraries=pg_stat_statements
         - -c
         - pg_stat_statements.track=all
   

2. Создайте расширение в той базе, которую мониторите:

   CREATE EXTENSION IF NOT EXISTS pg_stat_statements;
   

3. (Опционально, для sample-планов выполнения запросов) создайте схему protoobp и SECURITY DEFINER функцию explain_statement — она позволяет агенту получать планы выполнения запросов:

   CREATE SCHEMA IF NOT EXISTS protoobp;
   GRANT USAGE ON SCHEMA protoobp TO protoobp;
   
   CREATE OR REPLACE FUNCTION protoobp.explain_statement(
      l_query text,
      OUT explain JSON
   )
   RETURNS SETOF JSON AS
   $$
   DECLARE
      curs REFCURSOR;
      plan JSON;
   BEGIN
      OPEN curs FOR EXECUTE pg_catalog.concat('EXPLAIN (FORMAT JSON) ', l_query);
      FETCH curs INTO plan;
      CLOSE curs;
      RETURN QUERY SELECT plan;
   END;
   $$
   LANGUAGE 'plpgsql'
   RETURNS NULL ON NULL INPUT
   SECURITY DEFINER;
   

   Если такая схема уже создана под другим именем, переименовывать её не обязательно — достаточно указать pg_stat_statements_view / application_name в конфиге проверки.

Конфигурация ProtoOBP агента

Если агент запускается в виде службы на хосте

1. Создайте файл /etc/protoobp-agent/conf.d/postgres.d/conf.yaml:

   init_config:
   
   instances:
     - host: localhost
       port: 5432
       username: protoobp
       password: "<PASSWORD>"
       # По умолчанию dbname — postgres
       dbname: "<DB_NAME>"
       # Метрики уровня таблиц и индексов + postgresql.locks.
       # relation_regex: ".*" — для всех таблиц; можно ограничить списком.
       relations:
         - relation_regex: ".*"
       collect_function_metrics: true
       collect_count_metrics: true
       collect_activity_metrics: true
       collect_database_size_metrics: true
       # Включите для метрик запросов postgresql.queries.* (нужен pg_stat_statements):
       # dbm: true
   

2. Перезапустите ProtoOBP агента: systemctl restart protoobp-agent.

3. Выполните проверку работы агента и убедитесь, что в разделе postgres нет ошибок.

Если агент запускается в виде Docker контейнера

1. Добавьте autodiscovery-лейблы к Docker контейнеру с PostgreSQL.

   • в docker-compose.yaml

     labels:
       com.protoobp.ad.check_names: '["postgres"]'
       com.protoobp.ad.init_configs: "[{}]"
       com.protoobp.ad.instances: '[{"host": "%%host%%", "port": 5432, "username": "protoobp", "password": "<PASSWORD>", "dbname": "<DB_NAME>", "relations": [{"relation_regex": ".*"}], "collect_function_metrics": true, "collect_count_metrics": true, "collect_activity_metrics": true, "collect_database_size_metrics": true}]'
     

   • или в Dockerfile

     LABEL "com.protoobp.ad.check_names"='["postgres"]'
     LABEL "com.protoobp.ad.init_configs"='[{}]'
     LABEL "com.protoobp.ad.instances"='[{"host": "%%host%%", "port": 5432, "username": "protoobp", "password": "<PASSWORD>", "dbname": "<DB_NAME>", "relations": [{"relation_regex": ".*"}], "collect_function_metrics": true, "collect_count_metrics": true, "collect_activity_metrics": true, "collect_database_size_metrics": true}]'
     

2. Примените изменения лейблов для контейнера с PostgreSQL (перезапуском контейнера), а также перезапустите контейнер с агентом ProtoOBP.

3. Выполните проверку работы агента и убедитесь, что в разделе postgres нет ошибок.

Проверка

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

docker exec protoobp-agent agent status | grep -A 12 "postgres ("

Ожидаемый вывод — instance со статусом [OK] и ненулевыми Metric Samples (пример на PostgreSQL 16):

    postgres (12.5.1)
    -----------------
      Instance ID: postgres:55565625862af0c1 [OK]
      Configuration Source: container:docker://5a926dda...
      Total Runs: 32
      Metric Samples: Last Run: 74, Total: 2,246
      Events: Last Run: 0, Total: 0
      Service Checks: Last Run: 1, Total: 32
      Average Execution Time : 22ms
      metadata:
        version.major: 16
        version.minor: 13

Полный список собранных серий с тегами (двойной прогон, чтобы увидеть и rate-метрики):

docker exec protoobp-agent agent check postgres --check-rate

В выводе присутствуют ~60 уникальных метрик postgresql_* — в том числе postgresql_connections, postgresql_commits / postgresql_rollbacks, postgresql_rows_inserted / rows_updated / rows_deleted / rows_returned / rows_fetched / rows_hot_updated, postgresql_buffer_hit / postgresql_disk_read, postgresql_heap_blocks_read / heap_blocks_hit / index_blocks_read / index_blocks_hit / toast_blocks_read / toast_blocks_hit, postgresql_seq_scans / seq_rows_read / index_scans / index_rel_scans / index_rows_read / index_rows_fetched, postgresql_bgwriter_* (checkpoints_timed / checkpoints_requested / buffers_checkpoint / buffers_clean / buffers_backend / buffers_alloc / write_time / sync_time / …), postgresql_table_size / index_size / total_size / database_size, postgresql_live_rows / dead_rows, postgresql_vacuumed / autovacuumed / analyzed / autoanalyzed, postgresql_temp_bytes / temp_files, postgresql_deadlocks, postgresql_transactions_open / transactions_idle_in_transaction, postgresql_active_queries / waiting_queries / active_waiting_queries, postgresql_archiver_archived_count / failed_count, postgresql_max_connections / percent_usage_connections / before_xid_wraparound / db_count / table_count. Теги на сериях: db, schema, table, index (на per-table / per-index метриках), port, service, env, server и метки образа (docker_image, image_name, image_tag, short_image).

Собираемые метрики

Большинство метрик имеют тип gauge (мгновенное значение на момент сбора). Часть метрик — типа rate (postgresql_commits, postgresql_rollbacks, postgresql_rows_*, postgresql_buffer_hit, postgresql_disk_read, postgresql_deadlocks, postgresql_temp_bytes, postgresql_temp_files, postgresql_function_*): это скорость в секунду, рассчитанная агентом из кумулятивных счётчиков PostgreSQL. Метрики с суффиксом .count (а также postgresql_bgwriter_*, postgresql_wal_* и т.п.) — кумулятивные счётчики типа count (монотонно растут от старта сервера); для дашбордов применяйте PromQL rate(... [5m]).

Лейблы

Общие (на всех метриках)

Добавляются агентом и ProtoOBP backend’ом:

Специфичные для PostgreSQL

Соединения и сессии

Несут лейбл db.

Транзакции

Несут лейбл db.

Доступ к данным (на уровне базы)

Несут лейбл db. postgresql_disk_read и postgresql_buffer_hit — основная пара для расчёта cache hit ratio. rows_inserted / rows_updated / rows_deleted / rows_hot_updated появляются при включённом relations.

Bgwriter / checkpointer

Тип count (кумулятивные счётчики). Без лейбла db — относятся ко всему кластеру.

WAL

Размер баз данных

Метрики на уровне таблицы

Включаются параметром relations. Несут лейблы db, schema, table.

Прогресс-метрики долгих операций (несут теги db, table, phase и др.): postgresql_vacuum_heap_blks_scanned / .heap_blks_total / .heap_blks_vacuumed / .index_vacuum_count / .num_dead_tuples / .max_dead_tuples, postgresql_analyze_sample_blks_scanned / .sample_blks_total / .child_tables_done / .child_tables_total / .ext_stats_computed / .ext_stats_total, postgresql_cluster_vacuum_*, postgresql_create_index_* (PostgreSQL 12+).

Метрики на уровне индекса

Включаются параметром relations. Несут лейблы db, schema, table, index.

TOAST

Включаются параметром relations. Несут лейблы db, schema, table.

Bloat (collect_bloat_metrics)

Активность (collect_activity_metrics)

Из pg_stat_activity. По умолчанию несут теги db, app, user.

Функции (collect_function_metrics)

Из pg_stat_user_functions. Несут теги db, schema, function.

Репликация

Доступны при наличии соответствующих представлений (на primary / standby).

Метрики запросов (pg_stat_statements)

Доступны только при dbm: true и установленном pg_stat_statements. Тип count (кумулятивные), несут теги query_signature, db, user (а duration.* — user, db, app).

Группа метрик ввода-вывода уровня кластера, доступная для PostgreSQL 16+ и только при dbm: true: postgresql_io_reads / .writes / .hits / .evictions / .extends / .fsyncs и соответствующие *_time (теги backend_type, context, object).

Ключевые метрики для дашбордов и алертов

Доступность сервера

• Отсутствие свежих серий по host/port или postgresql_running == 0 — алерт: PostgreSQL недоступен или агент не может подключиться.
• postgresql_percent_usage_connections приближается к 1.0 — пул соединений на исходе; новые клиенты получат too many connections.
• postgresql_before_xid_wraparound резко уменьшается — приближение к transaction ID wraparound (риск аварийной остановки кластера).

Транзакции и нагрузка

• rate(postgresql_commits) vs rate(postgresql_rollbacks) — высокая доля rollback’ов = проблемы в приложении или дедлоки.
• postgresql_deadlocks (rate) > 0 — алерт: пересекающиеся блокировки.
• postgresql_locks с granted=false per table — запросы стоят в ожидании блокировок.
• postgresql_transactions_idle_in_transaction стабильно > 0 — «висящие» транзакции держат блокировки и тормозят vacuum.
• postgresql_activity_xact_start_age (или transactions.duration.max) большое — долгая транзакция, удерживающая ресурсы.

Кэш и ввод-вывод

• Cache hit ratio = rate(postgresql_buffer_hit) / (rate(postgresql_buffer_hit) + rate(postgresql_disk_read)) — устойчиво < 0.95–0.99 на OLTP-нагрузке = не хватает shared_buffers или плохой план.
• postgresql_temp_bytes / postgresql_temp_files (rate) растут — сортировки и хэши не помещаются в work_mem, спиливаются на диск.
• rate(postgresql_blk_read_time) высокое (при track_io_timing=on) — узкое место в дисковом I/O.

VACUUM / bloat

• postgresql_dead_rows per table стабильно растёт при низком rate(postgresql_autovacuumed) — autovacuum не успевает (тюнинг порогов или ручной VACUUM).
• postgresql_last_autovacuum_age per table слишком большой — таблица давно не вакуумировалась.
• postgresql_table_bloat / postgresql_index_bloat (при collect_bloat_metrics) > 30–50 % — кандидаты на VACUUM FULL / REINDEX.

Контрольные точки и WAL

• Высокая доля rate(postgresql_bgwriter_checkpoints_requested) относительно rate(postgresql_bgwriter_checkpoints_timed) — контрольные точки запускаются по объёму WAL слишком часто; увеличьте max_wal_size / checkpoint_timeout.
• postgresql_bgwriter_buffers_backend доминирует над buffers_clean / buffers_checkpoint — bgwriter не справляется, бэкенды пишут грязные буферы сами.
• rate(postgresql_wal_bytes) — объём генерируемого WAL; всплески = массовые записи, влияет на репликацию и архивацию.
• postgresql_archiver_failed_count (rate) > 0 — archive_command падает, WAL-файлы копятся.

Репликация (если используется)

• postgresql_replication_delay / postgresql_replication_wal_replay_lag — лаг standby; алерт при превышении SLA.
• postgresql_replication_slot_restart_delay_bytes растёт у неактивного слота — «осиротевший» слот удерживает WAL, диск primary заполняется.
• postgresql_wal_receiver_connected с status:disconnected — standby потерял связь с primary.

Рост данных

• postgresql_database_size per db, postgresql_total_size per table — тренд роста для capacity planning.
• postgresql_index_size существенно больше postgresql_table_size при низком postgresql_index_scans — неиспользуемые индексы.

Запросы (при dbm: true)

• topk по rate(postgresql_queries_time) per query_signature — самые «тяжёлые» нормализованные запросы.
• rate(postgresql_queries_temp_blks_written) per query_signature > 0 — запрос регулярно спиливает на диск.
• postgresql_queries_duration_max per user/db большое — конкретный пользователь/приложение крутит долгий запрос.

Сбор логов PostgreSQL

Логи PostgreSQL собираются ProtoOBP агентом и отправляются в бэкенд ProtoOBP. Здесь — только специфичные для PostgreSQL настройки. Включение логов на стороне агента (logs_enabled, logs_pobp_url) описано в Получение данных логов.

log_min_duration_statement = 250ms   # логировать медленные запросы (или 0 — все)
log_checkpoints = on
log_lock_waits = on
log_autovacuum_min_duration = 0
log_line_prefix = '%m [%p] %q%u@%d '  # запись начинается с timestamp

Конфигурация ProtoOBP агента

Если агент запускается в виде службы на хосте

Дополните уже существующий /etc/protoobp-agent/conf.d/postgres.d/conf.yaml (тот же файл, в котором лежит instances: для метрик) блоком logs::

logs:
  - type: file
    path: /var/log/postgresql/*.log
    source: postgresql
    service: postgresql
    log_processing_rules:
      - type: multi_line
        name: log_start_with_date
        pattern: \d{4}-\d{2}-\d{2}

Если включён logging_collector = on, используйте путь из log_directory (по умолчанию $PGDATA/log/*.log).

Перезапустите агента: systemctl restart protoobp-agent.

Если агент запускается в виде Docker контейнера

Шаг 1 — включите сбор логов в самом агенте через переменные окружения и смонтируйте директорию JSON-логов docker-демона:

services:
  protoobp-agent:
    environment:
      POBP_LOGS_ENABLED: "true"
      POBP_LOGS_CONFIG_USE_HTTP: "true"
      POBP_LOGS_CONFIG_LOGS_POBP_URL: <protoobp-backend>:<port>
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      # Прямое чтение JSON-лог файлов docker-демона быстрее,
      # чем тянуть их через Docker socket API.
      - /var/lib/docker/containers:/var/lib/docker/containers:ro

Шаг 2 — добавьте лейбл com.protoobp.ad.logs к контейнеру PostgreSQL. Агент подхватит stdout/stderr контейнера и пометит записи указанными source и service:

services:
  postgresql:
    labels:
      com.protoobp.ad.logs: '[{"source": "postgresql", "service": "postgresql", "log_processing_rules": [{"type": "multi_line", "name": "log_start_with_date", "pattern": "\\d{4}-\\d{2}-\\d{2}"}]}]'

Проверка

В выводе agent status в разделе Logs Agent должен быть источник с Source: postgresql, Status: OK и ненулевым BytesRead:

docker exec protoobp-agent agent status | grep -A 60 'Logs Agent'

Пример вывода:

Logs Agent
==========
    Reliable: Sending compressed logs in HTTPS to <protoobp-backend> on port 443
    BytesSent: 2.947246e+06
    LogsProcessed: 4062
    LogsSent: 4032

  docker
  ------
    - Type: file
      Path: /var/lib/docker/containers/5a926dda.../5a926dda...-json.log
      Service: postgresql
      Source: postgresql
      Status: OK
      BytesRead: 1.7736e+06
      Lines Combined: 5348
      MultiLine matches: 3902

Ненулевые Lines Combined / MultiLine matches подтверждают, что правило multi_line склеивает многострочные записи (тексты запросов, STATEMENT:-блоки) в одну. У источника типа «JSON-файл docker-контейнера» поле Status обычно OK, но даже если оно отображается как Pending — ориентируйтесь на BytesRead и LogsProcessed.