pg_trace - это библиотека трассировки, которая позволяет отслеживать выполняемые запросы в реальном времени, включая их ресурсы, время выполнения и план запроса.

Особенности

Добавьте расширение в shared_preload_libraries в postgresql.conf:

shared_preload_libraries = 'pg_trace'

Создайте расширение и начните трассировку

CREATE EXTENSION pg_trace;
SELECT pg_trace_start();

Подключиться к сокету. Т.е. используя nc:

nc -U /tmp/pg_trace.sock

Выполните несколько запросов:

SELECT 1;

Вы увидите вывод, подобный этому:

{"traceid":0,"queryid":6865378226349601843,"dbid":5,"userid":10,"tuplescount":1,"start_time":1733221222489,"end_time":1733221222489,"total_time":0.00739,"startup_time":0,"sys_time":0,"user_time":0,"rows":1,"shared_blks_hit":0,"shared_blks_read":0,"shared_blks_written":0,"shared_blks_dirtied":0,"local_blks_hit":0,"local_blks_read":0,"local_blks_written":0,"local_blks_dirtied":0,"shared_blk_read_time":0,"shared_blk_write_time":0,"local_blk_read_time":0,"local_blk_write_time":0,"temp_blk_read_time":0,"temp_blk_write_time":0,"wal_records":0,"wal_fpi":0,"wal_bytes":0,"query":"select 1;"}

Взаимодействие между сервером (фоновым рабочим процессом) и клиентом (приложением, читающим трассировки) настроено в клиент/серверной манере.

Клиент подключается к серверному UNIX-сокету (он должен знать его расположение). После подключения клиент начнет получать сообщения. Каждое сообщение представляет собой один trace и содержит 2 поля:

Length - длина поля Trace. Это хранится как сериализованное целое число в формате little-endian.

Trace - ASCII кодированное JSON представление объекта Trace.

Схема JSON сообщения:

Многие поля содержат информацию о времени. В этой схеме вся информация о времени предоставляется в виде UNIX временной метки.

План предоставляется в виде JSON-объекта, сгенерированного с помощью EXPLAIN.

pg_trace.max_clients - максимальное количество клиентов, которые могут обрабатываться одновременно.

pg_trace.trace_plan_mem - объем памяти, используемой для хранения плана запроса в текстовом представлении. Указывается как объем памяти с суффиксом размера. Например, 8 kB. По умолчанию установлено на 16 kB.

pg_trace.traces_mem - объем памяти для выделения под трассировки в серверном фоновом процессе. Указывается как объем памяти с суффиксом размера. Например, 128 MB. По умолчанию устанавливается объем памяти для хранения ровно 5000 трассировок.

pg_trace.shm_queue_mem - объем памяти, выделяемой в общей памяти для буфера трассировок. Указывается как объем памяти с суффиксом размера. Например, 32 MB. По умолчанию установлено на объем памяти, достаточный для хранения ровно 32 трассировок.

pg_trace.unix_socket_path - путь к unix сокету для сервера. Если сокет уже существует, он будет удален и будет создан новый сокет. По умолчанию, /tmp/pg_trace.sock.

pg_trace.trace_timeout - тайм-аут по умолчанию для сеанса трассировки, после которого сеанс трассировки будет автоматически отключен. Это значение используется, если аргумент timeout в pg_trace_start не установлен. Указывается как время с суффиксом времени. Например, 1h. По умолчанию, 10 минут.

pg_trace.update_delay - время ожидания перед началом обработки трассировки из очереди общей памяти фоновым рабочим процессом. Это время может дать бэкэндам шанс записать больше трассировок в очередь, прежде чем фоновый рабочий процесс возьмет эксклюзивную блокировку. По умолчанию, 0 - без задержки.

pg_trace.plan_format - формат плана, который передается, когда 'plan' был запрошен при запуске трассировки сессии. Допустимые значения: text, json, yaml, xml. Если запрашивается json, будет использован объект плана в формате JSON, в противном случае (для других форматов) он будет представлен как строка плана (возможно, экранированная для JSON). По умолчанию используется формат text.

Параметры trace_timeout, update_delay и plan_format могут быть изменены с помощью обновления файла конфигурации с отправкой SIGHUP. Все остальные не могут быть изменены после запуска postgres - необходимо перезапустить сервер.

Терминология

Общая архитектура и принципы работы:

        ----------------- Trace format ----------------

                    +---------------------+
                    |   Instrumentation   |
                    |       Timings       |
                    |      Resources      |
                    +---------------------+
                    |      Query plan     |  `pg_trace.plan_max`
                    +---------------------+  



        ---------------- Architecture ----------------
                        
    +---------+           +---------+           +---------+
    | backend |           | backend |           | backend |
    +---------+           +---------+           +---------+
         \                     |                     /
          +--------------------+--------------------+
                               |
                           filtering
                               |
                               |
                               V                         `pg_trace.shm_queue_max`
                    +---------------------+     buffer         +---+---+---+          
                    | shared memory queue |--------------------| X |   |   |          
                    +---------------------+                    +---+---+---+
                               |
                               |
                               |
                               V                          `pg_trace.traces_mem`
                    +---------------------+  ring buffer  +---+---+---+---+---+
                    |  background worker  |---------------| X | X | X | X |   |
                    +---------------------+               +---+---+---+---+---+
                               |
                               |
                               |
            +------------------+------------------+
           /                   |                   \
          |                    |                    |
          V                    V                    V
          O                    O                    O
         /|\                  /|\                  /|\
         / \                  / \                  / \

                     `pg_trace.max_clients`      

Когда запрос выполняется и проходит все переданные фильтры, он отправляется в фоновый рабочий процесс, используя очередь общей памяти. Он содержит буфер размером pg_trace.shm_queue_max.

После этого фоновый рабочий копирует все трассировки из буфера очереди shm в свой собственный буфер. Трассировки хранятся в кольцевом буфере. Он выделяется при запуске сервера с размером pg_trace.traces_mem. Текущая реализация позволяет всем операциям (освобождение, поиск, вставка и т.д.) иметь сложность O(1), так что не стесняйтесь увеличивать этот параметр.

Когда добавляются новые трассировки, они отправляются клиентам. Максимальное количество клиентов, которые могут обрабатываться одновременно, устанавливается с помощью параметра pg_trace.max_clients.

Сервер реализован с использованием неблокирующих сокетов. Он использует WaitEventSet функциональность PostgreSQL для реализации этого, так что все платформы должны поддерживаться. Также это означает, что для новых клиентов используется тот же фоновый рабочий процесс для отправки данных - не стесняйтесь увеличивать количество максимальных клиентов.