Структурированное JSON-логирование

pg_doorman пишет структурированные JSON-логи при запуске с --log-format Structured. Каждая строка — самодостаточный JSON-объект с timestamp, уровнем, местом в исходниках и сообщением, готовый к приёму в Loki, Elasticsearch, Datadog или любой пайплайн логов, ожидающий JSON.

Включение

Три равноценных способа:

# Флаг командной строки
pg_doorman -F Structured /etc/pg_doorman/pg_doorman.yaml

# Длинная форма
pg_doorman --log-format Structured /etc/pg_doorman/pg_doorman.yaml

# Переменная окружения
LOG_FORMAT=Structured pg_doorman /etc/pg_doorman/pg_doorman.yaml

По умолчанию — Text (человекочитаемый). Флаг --log-format принимает значения Text, Structured или Debug; последнее на данный момент является алиасом для Text.

Формат вывода

{"timestamp":"2026-04-25T08:32:14.512Z","level":"INFO","file":"src/app/server.rs","line":357,"message":"Server is up at 0.0.0.0:6432"}
{"timestamp":"2026-04-25T08:32:14.514Z","level":"INFO","file":"src/pool/mod.rs","line":421,"message":"Pool 'mydb' initialized: 1 user, pool_size=40"}
{"timestamp":"2026-04-25T08:32:18.103Z","level":"WARN","file":"src/server/protocol_io.rs","line":189,"message":"Backend connection lost: connection reset by peer"}

Поля:

ПолеТипПримечания
timestampстрока RFC 3339UTC, точность до миллисекунд.
levelстрокаERROR, WARN, INFO, DEBUG, TRACE.
fileстрокаФайл исходника, который пишет лог.
lineцелоеНомер строки.
messageстрокаЧеловекочитаемое сообщение.

Вложенных полей и меток на событие нет — логгер pg_doorman сериализует обычные события макроса log в JSON. Для богатых метаданных (счётчики на пул, события на клиент) используйте Prometheus-метрики. См. Prometheus reference.

Уровень логирования

Задаётся через general.log_level в конфиге или переопределяется при старте:

general:
  log_level: "info"

pg_doorman -l debug -F Structured /etc/pg_doorman/pg_doorman.yaml

Изменение в рантайме через admin-базу:

SET log_level = 'debug';
SHOW LOG_LEVEL;

Это влияет только на текущий процесс. Чтобы изменения сохранялись, отредактируйте конфиг и выполните RELOAD или отправьте SIGHUP.

Рекомендуемый пайплайн

Для Kubernetes:

spec:
  containers:
    - name: pg_doorman
      image: ghcr.io/ozontech/pg_doorman:latest
      args:
        - "-F"
        - "Structured"
        - "/etc/pg_doorman/pg_doorman.yaml"
      env:
        - name: LOG_LEVEL
          value: "info"

Логи идут в stdout, рантайм контейнера их захватывает, ваш log shipper (Promtail, Fluent Bit, Vector) пересылает их как есть — JSON сохраняется на всём пути.

Для systemd:

[Service]
ExecStart=/usr/bin/pg_doorman -F Structured /etc/pg_doorman/pg_doorman.yaml
StandardOutput=journal
StandardError=journal

journalctl -u pg_doorman -o json возвращает JSON обратно.

Оговорки

  • Для production выбирайте Text (терминалы, syslog) или Structured (log shippers). Debug зарезервирован под будущее использование и сейчас равен Text.
  • file и line берутся из мест вызова макроса log. Они доступны в release-сборках, потому что pg_doorman поставляется с включённой отладочной информацией.
  • Логгер не включает trace-идентификаторы и корреляцию запросов. Для трассировки на запрос используйте SHOW CLIENTS и Prometheus-метрики.

Куда дальше