18.8. Регистрация ошибок и протоколирование работы сервера #
18.8.1. Куда протоколировать #
log_destination(string) #Postgres Pro поддерживает несколько методов протоколирования сообщений сервера: stderr, csvlog, jsonlog и syslog. В Windows также поддерживается eventlog. В качестве значения
log_destinationуказывается один или несколько методов протоколирования, разделённых запятыми. По умолчанию используется stderr. Параметр можно задать только в конфигурационных файлах или в командной строке при запуске сервера.Если в
log_destinationвключено значение csvlog, то протоколирование ведётся в формате CSV (разделённые запятыми значения). Это удобно для программной обработки журнала. Подробнее об этом в Подразделе 18.8.4. Для вывода в формате CSV должен быть включён logging_collector.Если в
log_destinationвключено значение jsonlog, то протоколирование ведётся в формате JSON. Это удобно для программной обработки журнала. Подробнее об этом в Подразделе 18.8.5. Для вывода в формате JSON должен быть включён logging_collector.Если присутствует указание stderr, csvlog или jsonlog, создаётся файл
current_logfiles, в который записывается расположение файлов журнала, в настоящее время используемых сборщиком сообщений для соответствующих назначений. Это позволяет легко определить, какие файлы журнала используются в данный момент экземпляром сервера. Например, он может иметь такое содержание:stderr log/postgresql.log csvlog log/postgresql.csv jsonlog log/postgresql.json
current_logfilesпереписывается, когда при прокрутке создаётся новый файл журнала или когда изменяется значениеlog_destination. Он удаляется, когда вlog_destinationне задаётся ни stderr, ни csvlog, ни jsonlog, а также когда сборщик сообщений отключён.Примечание
В большинстве систем Unix потребуется изменить конфигурацию системного демона syslog для использования варианта syslog в
log_destination. Для указания типа протоколируемой программы (facility), Postgres Pro может использовать значения сLOCAL0поLOCAL7(см. syslog_facility). Однако на большинстве платформ конфигурация syslog по умолчанию не учитывает сообщения подобного типа. Чтобы это работало, потребуется добавить в конфигурацию демона syslog что-то подобное:local0.* /var/log/postgresql
Для использования
eventlogвlog_destinationна Windows, необходимо зарегистрировать источник событий и его библиотеку в операционной системе. Тогда Windows Event Viewer сможет отображать сообщения журнала событий. Подробнее в Разделе 17.12.logging_collector(boolean) #Параметр включает сборщик сообщений (logging collector). Это фоновый процесс, который собирает отправленные в stderr сообщения и перенаправляет их в журнальные файлы. Такой подход зачастую более полезен чем запись в syslog, поскольку некоторые сообщения в syslog могут не попасть. (Типичный пример с сообщениями об ошибках динамического связывания, другой пример — ошибки в скриптах типа
archive_command.) Для установки параметра требуется перезапуск сервера.Примечание
Можно обойтись без сборщика сообщений и просто писать в stderr. Сообщения будут записываться в место, куда направлен поток stderr. Такой способ подойдёт только для небольших объёмов протоколирования, потому что не предоставляет удобных средств для организации ротации журнальных файлов. Кроме того, на некоторых платформах отказ от использования сборщика сообщений может привести к потере или искажению сообщений, так как несколько процессов, одновременно пишущих в один журнальный файл, могут перезаписывать информацию друг друга.
Примечание
Сборщик спроектирован так, чтобы сообщения никогда не терялись. А это значит, что при очень высокой нагрузке, серверные процессы могут быть заблокированы при попытке отправить сообщения во время сбоя фонового процесса сборщика. В противоположность этому, syslog предпочитает удалять сообщения, при невозможности их записать. Поэтому часть сообщений может быть потеряна, но система не будет блокироваться.
log_directory(string) #При включённом
logging_collector, определяет каталог, в котором создаются журнальные файлы. Можно задавать как абсолютный путь, так и относительный от каталога данных кластера. Параметр можно задать только в конфигурационных файлах или в командной строке при запуске сервера. Значение по умолчанию —log.log_filename(string) #При включённом
logging_collectorзадаёт имена журнальных файлов. Значение трактуется как строка формата в функцииstrftime, поэтому в ней можно использовать спецификаторы%для включения в имена файлов информации о дате и времени. (При наличии зависящих от часового пояса спецификаторов%будет использован пояс, заданный в log_timezone.) Поддерживаемые спецификаторы%похожи на те, что перечислены в описании strftime спецификации Open Group. Обратите внимание, что системная функцияstrftimeнапрямую не используется. Поэтому нестандартные, специфичные для платформы особенности не будут работать. Значение по умолчаниюpostgresql-%Y-%m-%d_%H%M%S.log.Если для задания имени файлов не используются спецификаторы
%, то для избежания переполнения диска, следует использовать утилиты для ротации журнальных файлов. В версиях до 8.4, при отсутствии спецификаторов%, PostgreSQL автоматически добавлял время в формате Epoch к имени файла. Сейчас в этом больше нет необходимости.Если в
log_destinationвключён вывод в формате CSV, то к имени журнального файла будет добавлено расширение.csv. (Еслиlog_filenameзаканчивается на.log, то это расширение заменится на.csv.)Если в
log_destinationвключён вывод в формате JSON, то к имени журнального файла будет добавлено расширение.json. (Еслиlog_filenameзаканчивается на.log, то это расширение заменится на.json.)Задать этот параметр можно только в
postgresql.confили в командной строке при запуске сервера.log_file_mode(integer) #В системах Unix задаёт права доступа к журнальным файлам, при включённом
logging_collector. (В Windows этот параметр игнорируется.) Значение параметра должно быть числовым, в формате командchmodиumask. (Для восьмеричного формата, требуется задать лидирующий0(ноль).)Права доступа по умолчанию
0600, т. е. только владелец сервера может читать и писать в журнальные файлы. Также, может быть полезным значение0640, разрешающее чтение файлов членам группы. Однако чтобы установить такое значение, нужно каталог для хранения журнальных файлов (log_directory) вынести за пределы каталога данных кластера. В любом случае нежелательно открывать для всех доступ на чтение журнальных файлов, так как они могут содержать конфиденциальные данные.Задать этот параметр можно только в
postgresql.confили в командной строке при запуске сервера.log_rotation_age(integer) #При включённом
logging_collectorэтот параметр определяет максимальное время жизни отдельного журнального файла, по истечении которого создаётся новый файл. Если это значение задаётся без единиц измерения, оно считается заданным в минутах. Значение по умолчанию — 24 часа. При нулевом значении смена файлов по времени не производится. Задать этот параметр можно только вpostgresql.confили в командной строке при запуске сервера.log_rotation_size(integer) #При включённом
logging_collectorэтот параметр определяет максимальный размер отдельного журнального файла. При достижении этого размера создаётся новый файл. Если это значение задаётся без единиц измерения, оно считается заданным в килобайтах. Значение по умолчанию — 10 мегабайт. При нулевом значении смена файлов по размеру не производится. Задать этот параметр можно только вpostgresql.confили в командной строке при запуске сервера.log_truncate_on_rotation(boolean) #Если параметр
logging_collectorвключён, Postgres Pro будет перезаписывать существующие журнальные файлы, а не дописывать в них. Однако перезапись при переключении на новый файл возможна только в результате ротации по времени, но не при старте сервера или ротации по размеру файла. При выключенном параметре всегда продолжается запись в существующий файл. Например, включение этого параметра в комбинации сlog_filenameравнымpostgresql-%H.log, приведёт к генерации 24-х часовых журнальных файлов, которые циклически перезаписываются. Параметр можно задать только в конфигурационных файлах или в командной строке при запуске сервера.Пример: для хранения журнальных файлов в течение 7 дней, по одному файлу на каждый день с именами вида
server_log.Mon,server_log.Tueи т. д., а также с автоматической перезаписью файлов прошлой недели, нужно установитьlog_filenameвserver_log.%a,log_truncate_on_rotationвonиlog_rotation_ageв1440.Пример: для хранения журнальных файлов в течение 24 часов, по одному файлу на час, с дополнительной возможностью переключения файла при превышения 1ГБ, установите
log_filenameвserver_log.%H%M,log_truncate_on_rotationвon,log_rotation_ageв60иlog_rotation_sizeв1000000. Добавление%Mвlog_filenameпозволит при переключении по размеру указать другое имя файла в пределах одного часа.syslog_facility(enum) #При включённом протоколировании в syslog, этот параметр определяет значение «facility». Допустимые значения
LOCAL0,LOCAL1,LOCAL2,LOCAL3,LOCAL4,LOCAL5,LOCAL6,LOCAL7. По умолчанию используетсяLOCAL0. Подробнее в документации на системный демон syslog. Параметр можно задать только в конфигурационных файлах или в командной строке при запуске сервера.syslog_ident(string) #При включённом протоколировании в syslog, этот параметр задаёт имя программы, которое будет использоваться в syslog для идентификации сообщений относящихся к Postgres Pro. По умолчанию используется
postgres. Задать этот параметр можно только вpostgresql.confили в командной строке при запуске сервера.syslog_sequence_numbers(boolean) #Когда сообщения выводятся в syslog и этот параметр включён (по умолчанию), все сообщения будут предваряться последовательно увеличивающимися номерами (например,
[2]). Это позволяет обойти подавление повторов «--- последнее сообщение повторилось N раз ---», которое по умолчанию осуществляется во многих реализациях syslog. В более современных реализациях syslog подавление повторных сообщений можно настроить (например, в rsyslog есть директива$RepeatedMsgReduction), так что это может излишне. Если же вы действительно хотите, чтобы повторные сообщения подавлялись, вы можете отключить этот параметр.Задать этот параметр можно только в
postgresql.confили в командной строке при запуске сервера.syslog_split_messages(boolean) #Когда активен вывод сообщений в syslog, этот параметр определяет, как будут доставляться сообщения. Если он включён (по умолчанию), сообщения разделяются по строкам, а длинные строки разбиваются на строки не длиннее 1024 байт, что составляет типичное ограничение размера для традиционных реализаций syslog. Когда он отключён, сообщения сервера Postgres Pro передаются службе syslog как есть, и она должна сама корректно воспринять потенциально длинные сообщения.
Если syslog в итоге выводит сообщения в текстовый файл, результат будет тем же и лучше оставить этот параметр включённым, так как многие реализации syslog не способны обрабатывать большие сообщения или их нужно специально настраивать для этого. Но если syslog направляет сообщения в некоторую другую среду, может потребоваться или будет удобнее сохранять логическую целостность сообщений.
Задать этот параметр можно только в
postgresql.confили в командной строке при запуске сервера.event_source(string) #При включённом протоколировании в event log, этот параметр задаёт имя программы, которое будет использоваться в журнале событий для идентификации сообщений относящихся к Postgres Pro. По умолчанию используется
Postgres Pro. Задать этот параметр можно только при запуске сервера.
18.8.2. Когда протоколировать #
log_min_messages(enum) #Управляет минимальным уровнем сообщений, записываемых в журнал сервера. Допустимые значения
DEBUG5,DEBUG4,DEBUG3,DEBUG2,DEBUG1,INFO,NOTICE,WARNING,ERROR,LOG,FATALиPANIC. Каждый из перечисленных уровней включает все идущие после него. Чем дальше в этом списке уровень сообщения, тем меньше сообщений будет записано в журнал сервера. По умолчанию используетсяWARNING. Обратите внимание, позицияLOGздесь отличается от принятой в client_min_messages. Только суперпользователи и пользователи с соответствующим правомSETмогут изменить этот параметр.log_min_error_statement(enum) #Управляет тем, какие SQL-операторы, завершившиеся ошибкой, записываются в журнал сервера. SQL-оператор будет записан в журнал, если он завершится ошибкой с указанным уровнем важности или выше. Допустимые значения:
DEBUG5,DEBUG4,DEBUG3,DEBUG2,DEBUG1,INFO,NOTICE,WARNING,ERROR,LOG,FATALиPANIC. По умолчанию используетсяERROR. Это означает, что в журнал сервера будут записаны все операторы, завершившиеся сообщением с уровнем важностиERROR,LOG,FATALиPANIC. Чтобы фактически отключить запись операторов с ошибками, установите для этого параметра значениеPANIC. Изменить этот параметр могут только суперпользователи и пользователи с соответствующим правомSET.log_min_duration_statement(integer) #Записывает в журнал продолжительность выполнения всех команд, время работы которых не меньше указанного. Например, при значении
250msв журнал сервера будут записаны все команды, выполняющиеся 250 миллисекунд и дольше. С помощью этого параметра можно выявить неоптимизированные запросы в приложениях. Если значение этого параметра задаётся без единиц измерения, оно считается заданным в миллисекундах. При нулевом значении записывается продолжительность выполнения всех команд. Со значением -1 (по умолчанию) запись полностью отключается. Изменить этот параметр могут только суперпользователи и пользователи с соответствующим правомSET.Этот параметр переопределяет log_min_duration_sample, то есть запросы с длительностью, превышающей заданное значение, всегда фиксируются в журнале, вне зависимости от параметров извлечения выборки.
Для клиентов, использующих расширенный протокол запросов, будет записываться продолжительность фаз: разбор, связывание и выполнение.
Примечание
При использовании совместно с log_statement, текст SQL-операторов будет записываться только один раз (от использования
log_statement) и не будет задублирован в сообщении о длительности выполнения. Если не используется вывод в syslog, то рекомендуется в log_line_prefix включить идентификатор процесса или сеанса. Это позволит связать текст запроса с записью о продолжительности выполнения, которая появится позже.log_min_duration_sample(integer) #Позволяет сделать выборку по продолжительности команд, которые выполнялись не менее чем определённое время. При этом в журнал будут вноситься такие же записи, как и при включённом параметре log_min_duration_statement, но не для всех команд, а только для их подмножества, ограничиваемого параметром log_statement_sample_rate. Например, при значении
100msпредварительно для выборки будут отобраны все SQL-операторы, выполняющиеся 100 миллисекунд и дольше. Этот параметр может быть полезен, когда количество запросов слишком велико, чтобы записывать в журнал их все. Если значение этого параметра задаётся без единиц измерения, оно считается заданным в миллисекундах. При нулевом значении для выборки отбираются команды с любой продолжительностью. Со значением -1 (по умолчанию) формирование выборки по продолжительности полностью отключается. Изменить этот параметр могут только суперпользователи и пользователи с соответствующим правомSET.Этот параметр имеет меньший приоритет, чем
log_min_duration_statement, то есть команды с длительностью, превышающейlog_min_duration_statement, будут регистрироваться в журнале всегда, вне зависимости от того, какой будет выборка.Другие замечания, относящиеся к
log_min_duration_statement, применимы так же и к данному параметру.log_statement_sample_rate(floating point) #Определяет, какая доля команд с длительностью, достигшей log_min_duration_sample, будет регистрироваться в журнале. Выборка формируется вероятностным образом, например, со значением
0.5можно считать, что шанс попадания каждой отдельной команды в выборку равен один к двум. Значение по умолчанию —1.0, то есть выбираются и регистрируются все команды. Со значением 0 запись команд выборки, в зависимости от их длительности, отключается, так же как и приlog_min_duration_sample, равном-1. Изменить этот параметр могут только суперпользователи и пользователи с соответствующим правомSET.log_transaction_sample_rate(floating point) #Задаёт долю транзакций, команды из которых будут записываться в журнал дополнительно (помимо команд, записываемых по другим причинам). Этот параметр действует на все транзакции, независимо от длительности команд. Выборка осуществляется вероятностным образом, например, со значением
0.1можно считать, что каждая транзакция может попасть в журнал с шансом один к десяти. Параметрlog_transaction_sample_rateможет быть полезен для анализа выборки транзакций. Значение по умолчанию —0, то есть команды из дополнительно выбираемых транзакций не записываются. При значении1записываются все команды из всех транзакций. Изменить этот параметр могут только суперпользователи и пользователи с соответствующим правомSET.Примечание
С этим параметром, как и со всеми остальными, управляющими журналированием команд, могут быть связаны значительные издержки.
log_startup_progress_interval(integer) #Задаёт интервал времени, по истечении которого процесс запуска будет выдавать сообщение о длительной операции, которая всё ещё выполняется; с таким же интервалом будут выдаваться и последующие сообщения об этой операции. Значение по умолчанию — 10 секунд. Значение
0отключает эту функцию. Если это значение указано без единиц измерения, оно считается заданным в миллисекундах. Этот интервал отсчитывается для каждой операции в отдельности. Задать этот параметр можно только в файлеpostgresql.confили в командной строке сервера.Например, при значении по умолчанию, равном 10 сек., если синхронизация каталога данных продолжается 25 секунд, а после этого сброс нежурналируемых отношений выполняется 8 секунд, в журнал будет выдано сообщение об операции синхронизации через 10 секунд после её начала, а затем ещё одно сообщение об этой операции, когда её продолжительность достигнет 20 секунд, а сообщений об операции сброса нежурналируемых отношений в журнале не будет.
В Таблице 18.2 поясняются уровни важности сообщений в Postgres Pro. Также в этой таблице показано, как эти уровни транслируются в системные при использовании syslog или eventlog в Windows.
Таблица 18.2. Уровни важности сообщений
| Уровень | Использование | syslog | eventlog |
|---|---|---|---|
DEBUG1 .. DEBUG5 | Более детальная информация для разработчиков. Чем больше номер, тем детальнее. | DEBUG | INFORMATION |
INFO | Неявно запрошенная пользователем информация, например вывод команды VACUUM VERBOSE. | INFO | INFORMATION |
NOTICE | Информация, которая может быть полезной пользователям. Например, уведомления об усечении длинных идентификаторов. | NOTICE | INFORMATION |
WARNING | Предупреждения о возможных проблемах. Например, COMMIT вне транзакционного блока. | NOTICE | WARNING |
ERROR | Сообщает об ошибке, из-за которой прервана текущая команда. | WARNING | ERROR |
LOG | Информация, полезная для администраторов. Например, выполнение контрольных точек. | INFO | INFORMATION |
FATAL | Сообщает об ошибке, из-за которой прерван текущий сеанс. | ERR | ERROR |
PANIC | Сообщает об ошибке, из-за которой прерваны все сеансы. | CRIT | ERROR |
18.8.3. Что протоколировать #
Примечание
Выбирая, что будет записываться в протокол, важно учитывать возможные риски безопасности; подробнее об этом говорится в Разделе 23.3.
application_name(string) #application_name— это любая строка длиной не болееNAMEDATALENсимволов (64 символа при стандартной сборке). Обычно устанавливается приложением при подключении к серверу. Значение отображается в представленииpg_stat_activityи добавляется в журнал сервера, при использовании формата CSV. Для прочих форматов,application_nameможно добавить в журнал через параметр log_line_prefix. Значениеapplication_nameможет содержать только печатные ASCII символы. Остальные символы заменяются шестнадцатеричными спецсимволами в стиле C.debug_print_parse(boolean)debug_print_rewritten(boolean)debug_print_plan(boolean) #Эти параметры включают вывод различной отладочной информации. А именно: вывод дерева запроса, дерево запроса после применения правил или плана выполнения запроса, соответственно. Все эти сообщения имеют уровень
LOG. Поэтому, по умолчанию, они записываются в журнал сервера, но не отправляются клиенту. Отправку клиенту можно настроить через client_min_messages и/или log_min_messages. По умолчанию параметры выключены.debug_pretty_print(boolean) #Включает выравнивание сообщений, выводимых
debug_print_parse,debug_print_rewrittenилиdebug_print_plan. В результате сообщения легче читать, но они значительно длиннее, чем в формате «compact», который используется при выключенном значении. По умолчанию включён.log_autovacuum_min_duration(integer) #Задаёт время выполнения действия автоочистки, при превышении которого информация об этом действии записывается в журнал. При нулевом значении в журнале фиксируются все действия автоочистки. Значение
-1отключает журналирование действий автоочистки. Если это значение задаётся без единиц измерения, оно считается заданным в миллисекундах. Например, если задать значение250ms, в журнале будут фиксироваться все операции автоматической очистки и анализа, выполняемые дольше 250 мс. Кроме того, когда этот параметр имеет любое значение, отличное от-1, в журнал будет записываться сообщение в случае пропуска действия автоочистки из-за конфликтующей блокировки или параллельного удаления отношения. Значение по умолчанию —10min. Во включённом состоянии этот параметр помогает отслеживать активность автоочистки. Задать этот параметр можно только вpostgresql.confили в командной строке при запуске сервера. Однако его можно переопределить для отдельных таблиц, изменив их параметры хранения.log_checkpoints(boolean) #Включает протоколирование выполнения контрольных точек и точек перезапуска сервера. При этом записывается некоторая статистическая информация. Например, число записанных буферов и время, затраченное на их запись. Параметр можно задать только в конфигурационных файлах или в командной строке при запуске сервера. По умолчанию включён.
log_connections(boolean) #Включает протоколирование всех попыток подключения к серверу, в том числе успешного завершения как аутентификации (если она требуется), так и авторизации клиентов. Изменить его можно только в начале сеанса и сделать это могут только суперпользователи и пользователи с соответствующим правом
SET. Значение по умолчанию —off.Примечание
Некоторые программы, например psql, предпринимают две попытки подключения (первая для определения, нужен ли пароль). Поэтому дублирование сообщения «connection received» не обязательно говорит о наличии проблемы.
log_disconnections(boolean) #Включает протоколирование завершения сеанса. В журнал выводится примерно та же информация, что и с
log_connections, плюс длительность сеанса. Изменить этот параметр можно только в начале сеанса и сделать это могут только суперпользователи и пользователи с соответствующим правомSET. Значение по умолчанию —off.log_duration(boolean) #Записывает продолжительность каждой завершённой команды. По умолчанию выключен. Только суперпользователи и пользователи с соответствующим правом
SETмогут изменить этот параметр.Для клиентов, использующих расширенный протокол запросов, будет записываться продолжительность фаз: разбор, связывание и выполнение.
Примечание
Включение параметра
log_durationне равнозначно установке нулевого значения для log_min_duration_statement. Разница в том, что при превышении значенияlog_min_duration_statementв журнал записывается текст запроса, а при включении данного параметра — нет. Таким образом, приlog_duration=onи положительном значенииlog_min_duration_statementв журнал записывается длительность для всех команд, а текст запроса — только для команд с длительностью, превышающей предел. Такое поведение может оказаться полезным при сборе статистики в условиях большой нагрузки.log_error_verbosity(enum) #Управляет количеством детальной информации, записываемой в журнал сервера для каждого сообщения. Допустимые значения:
TERSE,DEFAULTиVERBOSE. Каждое последующее значение добавляет больше полей в выводимое сообщение. ДляTERSEиз сообщения об ошибке исключаются поляDETAIL,HINT,QUERYиCONTEXT. ДляVERBOSEв сообщение включается код ошибкиSQLSTATE(см. Приложение A), а также имя файла с исходным кодом, имя функции и номер строки сгенерировавшей ошибку. Только суперпользователи и пользователи с соответствующим правомSETмогут изменить этот параметр.log_hostname(boolean) #По умолчанию, сообщения журнала содержат лишь IP-адрес подключившегося клиента. При включении этого параметра, дополнительно будет фиксироваться и имя сервера. Обратите внимание, что в зависимости от применяемого способа разрешения имён, это может отрицательно сказаться на производительности. Задать этот параметр можно только в
postgresql.confили в командной строке при запуске сервера.log_line_prefix(string) #Строка, в стиле функции
printf, которая выводится в начале каждой строки журнала сообщений. С символов%начинаются управляющие последовательности, которые заменяются статусной информацией, описанной ниже. Неизвестные управляющие последовательности игнорируются. Все остальные символы напрямую копируются в выводимую строку. Некоторые управляющие последовательности используются только для пользовательских процессов и будут игнорироваться фоновыми процессами, например основным процессом сервера. Статусная информация может быть выровнена по ширине влево или вправо указанием числа после % и перед кодом последовательности. Отрицательное число дополняет значение пробелами справа до заданной ширины, а положительное число — слева. Выравнивание может быть полезно для улучшения читаемости.Этот параметр можно задать только в
postgresql.confили в командной строке при запуске сервера. По умолчанию этот параметр имеет значение'%m [%p] ', с которым в журнал выводится время и идентификатор процесса (PID).Спецсимвол Назначение Только для пользовательского процесса %aИмя приложения (application_name) да %uИмя пользователя да %dИмя базы данных да %rИмя удалённого узла или IP-адрес, а также номер порта да %hИмя удалённого узла или IP-адрес да %bТип обслуживающего процесса нет %pИдентификатор процесса нет %PИдентификатор ведущего процесса группы, если текущий процесс является исполнителем параллельного запроса нет %tШтамп времени, без миллисекунд нет %mШтамп времени, с миллисекундами нет %nШтамп времени, с миллисекундами (в виде времени Unix) нет %iТег команды: тип текущей команды в сеансе да %eКод ошибки SQLSTATE нет %cИдентификатор сеанса. Подробности ниже нет %lНомер строки журнала для каждого сеанса или процесса. Начинается с 1 нет %sШтамп времени начала процесса нет %vИдентификатор виртуальной транзакции (backendID/localXID); см. Раздел 71.1 нет %xИдентификатор транзакции (0 если не присвоен); см. Раздел 71.1 нет %qНичего не выводит. Непользовательские процессы останавливаются в этой точке. Игнорируется пользовательскими процессами нет %QИдентификатор текущего запроса. Вычисление идентификаторов запроса по умолчанию отключено, поэтому в этом поле будет выводиться значение 0, если не включён параметр compute_query_id или не настроен дополнительный модуль, вычисляющий идентификаторы запросов. да %%Выводит %нет Тип обслуживающего процесса соответствует содержимому столбца
backend_typeв представленииpg_stat_activity, но в журнале могут фигурировать и другие типы, которые не показываются в этом представлении.Спецпоследовательность
%cзаменяется на практически уникальный идентификатор сеанса, содержащий из 4 шестнадцатеричных чисел (без ведущих нулей), разделённых точками. Эти числа представляют время запуска процесса и его PID, так что%cможно использовать как более компактную альтернативу совокупности этих двух элементов. Чтобы получить такой идентификатор сеанса, например изpg_stat_activity, воспользуйтесь этим запросом:SELECT to_hex(trunc(EXTRACT(EPOCH FROM backend_start))::integer) || '.' || to_hex(pid) FROM pg_stat_activity;Подсказка
Последним символом в
log_line_prefixлучше оставлять пробел, чтобы отделить от остальной строки. Можно использовать и символы пунктуации.Подсказка
Syslog также формирует штамп времени и идентификатор процесса, поэтому вероятно нет смысла использовать соответствующие управляющие последовательности при использовании syslog.
Подсказка
Спецпоследовательность
%qполезна для включения информации, которая существует только в контексте сеанса (обслуживающего процесса), например, имя пользователя или базы данных. Например:log_line_prefix = '%m [%p] %q%u@%d/%a '
Примечание
Спецпоследовательность
%Qвсегда выдаёт нулевой идентификатор для строк, выводимых посредством log_statement, потому что соответствующий выводlog_statementформируется до вычисления этого идентификатора, в том числе и для некорректных операторов, для которых идентификатор вычислить нельзя.log_lock_waits(boolean) #Определяет, нужно ли фиксировать в журнале события, когда сеанс ожидает получения блокировки дольше, чем указано в deadlock_timeout. Это позволяет выяснить, не связана ли низкая производительность с ожиданием блокировок. По умолчанию отключён. Только суперпользователи и пользователи с соответствующим правом
SETмогут изменить этот параметр.log_recovery_conflict_waits(boolean) #Определяет, нужно ли фиксировать в журнале события, когда сеанс ожидает получения блокировки дольше, чем указано в
deadlock_timeoutдля конфликтов восстановления. Это позволяет выяснить, препятствуют ли конфликты восстановления применению WAL.Значение по умолчанию —
off(выкл.). Задать этот параметр можно только вpostgresql.confили в командной строке при запуске сервера.log_parameter_max_length(integer) #Положительное значение устанавливает количество байт, до которого будут усекаться значения привязанных SQL-параметров, выводимые в сообщениях вместе с SQL-операторами (это не относится к регистрации ошибок). Ноль отключает вывод значений привязанных параметров в таких сообщениях. Значение
-1(по умолчанию) позволяет получить в журнале привязанные параметры в полном объёме. Если значение этого параметра задаётся без единиц измерения, оно считается заданным в байтах. Изменить этот параметр могут только суперпользователи и пользователи с соответствующим правомSET.Этот параметр влияет только на сообщения, выводимые в журнал по критериям, которые устанавливают параметры log_statement, log_duration и связанные с ними. С ненулевыми значениями этого параметра сопряжены некоторые издержки, особенно если привязанные значения передаются в двоичной форме, так как их нужно будет переводить в текстовый вид.
log_parameter_types(boolean) #Указывает, добавлять ли к каждому значению привязываемых параметров в сообщениях журнала префикс с типом данных. Например,
[integer] $1 = '42'.Этот параметр влияет только на сообщения журнала со значениями привязываемых параметров: сообщения об ошибках (
CONTEXT), информацию об операторах (DETAIL) и сообщения auto_explain.Значение по умолчанию —
off. Этот параметр можно задать только вpostgresql.conf, в командной строке сервера или с помощью командыSETдля текущего сеанса.log_parameter_max_length_on_error(integer) #Положительное значение устанавливает количество байт, до которого будут усекаться значения привязанных SQL-параметров, выводимые вместе с SQL-операторами при регистрации ошибок. Нулевое значение отключает вывод значений привязанных операторов в сообщениях об ошибках. Значение
-1(по умолчанию) позволяет получить в журнале привязанные параметры в полном объёме. Если значение этого параметра задаётся без единиц измерения, оно считается заданным в байтах.С ненулевыми значениями этого параметра сопряжены некоторые издержки, так как Postgres Pro должен будет сформировать в памяти текстовые представления всех значений параметров перед выполнением всех операторов, в том числе, выполненных в итоге без ошибок. Издержки дополнительно возрастают, когда привязанные параметры передаются не в текстовой, а в двоичной форме, так как их недостаточно просто скопировать в строку, их нужно ещё преобразовать.
log_statement(enum) #Управляет тем, какие SQL-команды записывать в журнал. Допустимые значения:
none(отключено),ddl,modиall(все команды).ddlзаписывает все команды определения данных, такие какCREATE,ALTER,DROP.modзаписывает все командыddl, а также команды изменяющие данные, такие какINSERT,UPDATE,DELETE,TRUNCATEиCOPY FROM.PREPARE,EXECUTEиEXPLAIN ANALYZEтакже записываются, если вызваны для команды соответствующего типа. Если клиент использует расширенный протокол запросов, то запись происходит на фазе выполнения и содержит значения всех связанных переменных (если есть символы одиночных кавычек, то они дублируются).По умолчанию
none. Только суперпользователи и пользователи с соответствующим правомSETмогут изменить этот параметр.Примечание
Команды с синтаксическими ошибками не записываются, даже если
log_statement=all, так как сообщение формируется только после выполнения предварительного разбора, определяющего тип команды. При расширенном протоколе запросов, похожим образом не будут записываться команды, неуспешно завершившиеся до фазы выполнения (например, при разборе или построении плана запроса). Для включения в журнал таких команд установитеlog_min_error_statementвERROR(или ниже).Записываемые в журнал команды могут раскрывать конфиденциальные данные. Однако при записи в журнал сервера пароли маскируются.
log_replication_commands(boolean) #Включает запись в журнал сервера всех команд репликации. Подробнее о командах репликации можно узнать в Разделе 54.4. Значение по умолчанию —
off. Изменить этот параметр могут только суперпользователи и пользователи с соответствующим правомSET.log_temp_files(integer) #Управляет регистрацией в журнале имён и размеров временных файлов. Временные файлы могут использоваться для сортировки, хеширования и временного хранения результатов запросов. Когда этот параметр включён, при удалении временного файла информация о нём может записываться в журнал с указанием размера файла в байтах. При нулевом значении записывается информация обо всех файлах, а при положительном — о файлах, размер которых не меньше заданной величины. Если это значение задаётся без единиц измерения, оно считается заданным в килобайтах. Значение по умолчанию равно -1, то есть запись такой информации отключена. Изменить этот параметр могут только суперпользователи и пользователи с соответствующим правом
SET.log_timezone(string) #Устанавливает часовой пояс для штампов времени при записи в журнал сервера. В отличие от TimeZone, это значение одинаково для всех баз данных кластера, поэтому для всех сеансов используются согласованные значения штампов времени. Встроенное значение по умолчанию
GMT, но оно переопределяется вpostgresql.conf: initdb записывает в него значение, соответствующее системной среде. Подробнее об этом в Подразделе 8.5.3. Задать этот параметр можно только вpostgresql.confили в командной строке при запуске сервера.
18.8.4. Использование вывода журнала в формате CSV #
Добавление csvlog в log_destination делает удобным загрузку журнальных файлов в таблицу базы данных. Строки журнала представляют собой значения, разделённые запятыми (формат CSV), со следующими полями: штамп времени с миллисекундами; имя пользователя; имя базы данных; идентификатор процесса; клиентский узел:номер порта; идентификатор сеанса; номер строки каждого сеанса; тег команды; время начала сеанса; виртуальный идентификатор транзакции; идентификатор транзакции; уровень важности ошибки; код ошибки SQLSTATE; сообщение об ошибке; подробности к сообщению об ошибке; подсказка к сообщению об ошибке; внутренний запрос, приведший к ошибке (если есть); номер символа внутреннего запроса, где произошла ошибка; контекст ошибки; запрос пользователя, приведший к ошибке (если есть и включён log_min_error_statement); номер символа в запросе пользователя, где произошла ошибка; расположение ошибки в исходном коде Postgres Pro (если log_error_verbosity установлен в verbose), имя приложения, тип обслуживающего процесса, идентификатор ведущего процесса группы и идентификатор запроса. Вот пример определения таблицы, для хранения журналов в формате CSV:
CREATE TABLE postgres_log ( log_time timestamp(3) with time zone, user_name text, database_name text, process_id integer, connection_from text, session_id text, session_line_num bigint, command_tag text, session_start_time timestamp with time zone, virtual_transaction_id text, transaction_id bigint, error_severity text, sql_state_code text, message text, detail text, hint text, internal_query text, internal_query_pos integer, context text, query text, query_pos integer, location text, application_name text, backend_type text, leader_pid integer, query_id bigint, PRIMARY KEY (session_id, session_line_num) );
Для загрузки журнального файла в такую таблицу можно использовать команду COPY FROM:
COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv;
Также можно обратиться к этому файлу как к сторонней таблице, используя поставляемый модуль file_fdw.
Для упрощения загрузки журналов в CSV формате используйте следующее:
Установите для
log_filenameиlog_rotation_ageзначения, гарантирующие согласованную и предсказуемую схему именования журнальных файлов. Зная, какие имена будут у журнальных файлов, можно определить, когда конкретный файл заполнен и готов к загрузке.Установите
log_rotation_sizeв 0, чтобы запретить ротацию файлов по достижении определённого размера, так как это делает непредсказуемой схему именования журнальных файлов.Установите
log_truncate_on_rotationвon, чтобы новые сообщения не смешивались со старыми при переключении на существующий файл.Определение таблицы содержит первичный ключ. Это полезно для предотвращения случайной повторной загрузки данных. Команда
COPYфиксирует изменения один раз, поэтому любая ошибка приведёт к отмене всей загрузки. Если сначала загрузить неполный журнальный файл, то его повторная загрузка (по заполнении) приведёт к нарушению первичного ключа и, следовательно, к ошибке загрузки. Поэтому необходимо дожидаться окончания записи в журнальный файл перед началом загрузки. Похожим образом предотвращается случайная загрузка частично сформированной строки сообщения, что также приведёт к сбою в командеCOPY.
18.8.5. Использование вывода журнала в формате JSON #
Добавление jsonlog в список log_destination позволяет легко импортировать файлы журналов в различные программы. Когда выбран этот метод, строки журнала выводятся в формате JSON.
В этом формате строковые поля, содержащие NULL, не выводятся. Описанный ниже набор полей не окончательный, в будущем могут появиться новые поля. При обработке вывода jsonlog в пользовательских приложениях поля, неизвестные для этих приложений, должны игнорироваться.
Каждая строка журнала сериализуется в виде объекта JSON с набором ключей и связанных с ними значений, перечисленных в Таблица 18.3.
Таблица 18.3. Ключи и значения записей журнала в формате JSON
| Имя ключа | Тип | Описание |
|---|---|---|
timestamp | строка | Штамп времени, с миллисекундами |
user | строка | Имя пользователя |
dbname | строка | Имя базы данных |
pid | число | Идентификатор процесса |
remote_host | строка | Компьютер клиента |
remote_port | число | Порт клиента |
session_id | строка | Идентификатор сеанса |
line_num | число | Номер строки внутри сеанса |
ps | строка | Текущая строка для ps |
session_start | строка | Время начала сеанса |
vxid | строка | Идентификатор виртуальной транзакции |
txid | строка | Идентификатор обычной транзакции |
error_severity | строка | Уровень ошибки |
state_code | строка | Код SQLSTATE |
message | строка | Сообщение об ошибке |
detail | строка | Подробное сообщение об ошибке |
hint | строка | Подсказка, связанная с ошибкой |
internal_query | строка | Внутренний запрос, вызвавший ошибку |
internal_position | число | Положение курсора в тексте внутреннего запроса |
context | строка | Контекст ошибки |
statement | строка | Строка запроса, предоставленная клиентом |
cursor_position | число | Положение курсора в строке запроса |
func_name | строка | Имя функции, в которой произошла ошибка |
file_name | строка | Имя файла, в котором произошла ошибка |
file_line_num | число | Номер строки в файле, где произошла ошибка |
application_name | строка | Имя клиентского приложения |
backend_type | строка | Тип обслуживающего процесса |
leader_pid | число | Идентификатор ведущего процесса группы параллельных исполнителей |
query_id | число | Идентификатор запроса |
18.8.6. Заголовок процесса #
Эти параметры влияют на то, как формируются заголовки серверных процессов. Заголовок процесса обычно можно наблюдать в программах типа ps, а в Windows — в Process Explorer. За подробностями обратитесь к Разделу 26.1.
cluster_name(string) #Задаёт имя, которое идентифицирует данный кластер (экземпляр сервера) для различных целей. Имя кластера выводится в заголовке процесса для всех серверных процессов в данном кластере. Более того, это имя будет именем приложения по умолчанию, используемым при подключении ведомого сервера (см. synchronous_standby_names).
Это имя может быть любой строкой не длиннее
NAMEDATALENсимволов (64 символа в стандартной сборке). В строкеcluster_nameмогут использоваться только печатаемые ASCII-символы. Остальные символы заменяются шестнадцатеричными спецсимволами в стиле C. Если этот параметр содержит пустую строку''(это значение по умолчанию), никакое имя не выводится. Этот параметр можно задать только при запуске сервера.update_process_title(boolean) #Включает изменение заголовка процесса при получении сервером каждой очередной команды SQL. На большинстве платформ он включён (имеет значение
on), но в Windows по умолчанию выключен (off) ввиду больших издержек на изменение этого заголовка. Изменить этот параметр могут только суперпользователи и пользователи с соответствующим правомSET.
18.8. Error Reporting and Logging #
18.8.1. Where to Log #
log_destination(string) #Postgres Pro supports several methods for logging server messages, including stderr, csvlog, jsonlog, and syslog. On Windows, eventlog is also supported. Set this parameter to a list of desired log destinations separated by commas. The default is to log to stderr only. This parameter can only be set in the
postgresql.conffile or on the server command line.If csvlog is included in
log_destination, log entries are output in “comma separated value” (CSV) format, which is convenient for loading logs into programs. See Section 18.8.4 for details. logging_collector must be enabled to generate CSV-format log output.If jsonlog is included in
log_destination, log entries are output in JSON format, which is convenient for loading logs into programs. See Section 18.8.5 for details. logging_collector must be enabled to generate JSON-format log output.When either stderr, csvlog or jsonlog are included, the file
current_logfilesis created to record the location of the log file(s) currently in use by the logging collector and the associated logging destination. This provides a convenient way to find the logs currently in use by the instance. Here is an example of this file's content:stderr log/postgresql.log csvlog log/postgresql.csv jsonlog log/postgresql.json
current_logfilesis recreated when a new log file is created as an effect of rotation, and whenlog_destinationis reloaded. It is removed when none of stderr, csvlog or jsonlog are included inlog_destination, and when the logging collector is disabled.Note
On most Unix systems, you will need to alter the configuration of your system's syslog daemon in order to make use of the syslog option for
log_destination. Postgres Pro can log to syslog facilitiesLOCAL0throughLOCAL7(see syslog_facility), but the default syslog configuration on most platforms will discard all such messages. You will need to add something like:local0.* /var/log/postgresql
to the syslog daemon's configuration file to make it work.
On Windows, when you use the
eventlogoption forlog_destination, you should register an event source and its library with the operating system so that the Windows Event Viewer can display event log messages cleanly. See Section 17.12 for details.logging_collector(boolean) #This parameter enables the logging collector, which is a background process that captures log messages sent to stderr and redirects them into log files. This approach is often more useful than logging to syslog, since some types of messages might not appear in syslog output. (One common example is dynamic-linker failure messages; another is error messages produced by scripts such as
archive_command.) This parameter can only be set at server start.Note
It is possible to log to stderr without using the logging collector; the log messages will just go to wherever the server's stderr is directed. However, that method is only suitable for low log volumes, since it provides no convenient way to rotate log files. Also, on some platforms not using the logging collector can result in lost or garbled log output, because multiple processes writing concurrently to the same log file can overwrite each other's output.
Note
The logging collector is designed to never lose messages. This means that in case of extremely high load, server processes could be blocked while trying to send additional log messages when the collector has fallen behind. In contrast, syslog prefers to drop messages if it cannot write them, which means it may fail to log some messages in such cases but it will not block the rest of the system.
log_directory(string) #When
logging_collectoris enabled, this parameter determines the directory in which log files will be created. It can be specified as an absolute path, or relative to the cluster data directory. This parameter can only be set in thepostgresql.conffile or on the server command line. The default islog.log_filename(string) #When
logging_collectoris enabled, this parameter sets the file names of the created log files. The value is treated as astrftimepattern, so%-escapes can be used to specify time-varying file names. (Note that if there are any time-zone-dependent%-escapes, the computation is done in the zone specified by log_timezone.) The supported%-escapes are similar to those listed in the Open Group's strftime specification. Note that the system'sstrftimeis not used directly, so platform-specific (nonstandard) extensions do not work. The default ispostgresql-%Y-%m-%d_%H%M%S.log.If you specify a file name without escapes, you should plan to use a log rotation utility to avoid eventually filling the entire disk. In releases prior to 8.4, if no
%escapes were present, PostgreSQL would append the epoch of the new log file's creation time, but this is no longer the case.If CSV-format output is enabled in
log_destination,.csvwill be appended to the timestamped log file name to create the file name for CSV-format output. (Iflog_filenameends in.log, the suffix is replaced instead.)If JSON-format output is enabled in
log_destination,.jsonwill be appended to the timestamped log file name to create the file name for JSON-format output. (Iflog_filenameends in.log, the suffix is replaced instead.)This parameter can only be set in the
postgresql.conffile or on the server command line.log_file_mode(integer) #On Unix systems this parameter sets the permissions for log files when
logging_collectoris enabled. (On Microsoft Windows this parameter is ignored.) The parameter value is expected to be a numeric mode specified in the format accepted by thechmodandumasksystem calls. (To use the customary octal format the number must start with a0(zero).)The default permissions are
0600, meaning only the server owner can read or write the log files. The other commonly useful setting is0640, allowing members of the owner's group to read the files. Note however that to make use of such a setting, you'll need to alter log_directory to store the files somewhere outside the cluster data directory. In any case, it's unwise to make the log files world-readable, since they might contain sensitive data.This parameter can only be set in the
postgresql.conffile or on the server command line.log_rotation_age(integer) #When
logging_collectoris enabled, this parameter determines the maximum amount of time to use an individual log file, after which a new log file will be created. If this value is specified without units, it is taken as minutes. The default is 24 hours. Set to zero to disable time-based creation of new log files. This parameter can only be set in thepostgresql.conffile or on the server command line.log_rotation_size(integer) #When
logging_collectoris enabled, this parameter determines the maximum size of an individual log file. After this amount of data has been emitted into a log file, a new log file will be created. If this value is specified without units, it is taken as kilobytes. The default is 10 megabytes. Set to zero to disable size-based creation of new log files. This parameter can only be set in thepostgresql.conffile or on the server command line.log_truncate_on_rotation(boolean) #When
logging_collectoris enabled, this parameter will cause Postgres Pro to truncate (overwrite), rather than append to, any existing log file of the same name. However, truncation will occur only when a new file is being opened due to time-based rotation, not during server startup or size-based rotation. When off, pre-existing files will be appended to in all cases. For example, using this setting in combination with alog_filenamelikepostgresql-%H.logwould result in generating twenty-four hourly log files and then cyclically overwriting them. This parameter can only be set in thepostgresql.conffile or on the server command line.Example: To keep 7 days of logs, one log file per day named
server_log.Mon,server_log.Tue, etc., and automatically overwrite last week's log with this week's log, setlog_filenametoserver_log.%a,log_truncate_on_rotationtoon, andlog_rotation_ageto1440.Example: To keep 24 hours of logs, one log file per hour, but also rotate sooner if the log file size exceeds 1GB, set
log_filenametoserver_log.%H%M,log_truncate_on_rotationtoon,log_rotation_ageto60, andlog_rotation_sizeto1000000. Including%Minlog_filenameallows any size-driven rotations that might occur to select a file name different from the hour's initial file name.syslog_facility(enum) #When logging to syslog is enabled, this parameter determines the syslog “facility” to be used. You can choose from
LOCAL0,LOCAL1,LOCAL2,LOCAL3,LOCAL4,LOCAL5,LOCAL6,LOCAL7; the default isLOCAL0. See also the documentation of your system's syslog daemon. This parameter can only be set in thepostgresql.conffile or on the server command line.syslog_ident(string) #When logging to syslog is enabled, this parameter determines the program name used to identify Postgres Pro messages in syslog logs. The default is
postgres. This parameter can only be set in thepostgresql.conffile or on the server command line.syslog_sequence_numbers(boolean) #When logging to syslog and this is on (the default), then each message will be prefixed by an increasing sequence number (such as
[2]). This circumvents the “--- last message repeated N times ---” suppression that many syslog implementations perform by default. In more modern syslog implementations, repeated message suppression can be configured (for example,$RepeatedMsgReductionin rsyslog), so this might not be necessary. Also, you could turn this off if you actually want to suppress repeated messages.This parameter can only be set in the
postgresql.conffile or on the server command line.syslog_split_messages(boolean) #When logging to syslog is enabled, this parameter determines how messages are delivered to syslog. When on (the default), messages are split by lines, and long lines are split so that they will fit into 1024 bytes, which is a typical size limit for traditional syslog implementations. When off, Postgres Pro server log messages are delivered to the syslog service as is, and it is up to the syslog service to cope with the potentially bulky messages.
If syslog is ultimately logging to a text file, then the effect will be the same either way, and it is best to leave the setting on, since most syslog implementations either cannot handle large messages or would need to be specially configured to handle them. But if syslog is ultimately writing into some other medium, it might be necessary or more useful to keep messages logically together.
This parameter can only be set in the
postgresql.conffile or on the server command line.event_source(string) #When logging to event log is enabled, this parameter determines the program name used to identify Postgres Pro messages in the log. The default is
Postgres Pro. This parameter can only be set at server start.
18.8.2. When to Log #
log_min_messages(enum) #Controls which message levels are written to the server log. Valid values are
DEBUG5,DEBUG4,DEBUG3,DEBUG2,DEBUG1,INFO,NOTICE,WARNING,ERROR,LOG,FATAL, andPANIC. Each level includes all the levels that follow it. The later the level, the fewer messages are sent to the log. The default isWARNING. Note thatLOGhas a different rank here than in client_min_messages. Only superusers and users with the appropriateSETprivilege can change this setting.log_min_error_statement(enum) #Controls which SQL statements that cause an error condition are recorded in the server log. The current SQL statement is included in the log entry for any message of the specified severity or higher. Valid values are
DEBUG5,DEBUG4,DEBUG3,DEBUG2,DEBUG1,INFO,NOTICE,WARNING,ERROR,LOG,FATAL, andPANIC. The default isERROR, which means statements causing errors, log messages, fatal errors, or panics will be logged. To effectively turn off logging of failing statements, set this parameter toPANIC. Only superusers and users with the appropriateSETprivilege can change this setting.log_min_duration_statement(integer) #Causes the duration of each completed statement to be logged if the statement ran for at least the specified amount of time. For example, if you set it to
250msthen all SQL statements that run 250ms or longer will be logged. Enabling this parameter can be helpful in tracking down unoptimized queries in your applications. If this value is specified without units, it is taken as milliseconds. Setting this to zero prints all statement durations.-1(the default) disables logging statement durations. Only superusers and users with the appropriateSETprivilege can change this setting.This overrides log_min_duration_sample, meaning that queries with duration exceeding this setting are not subject to sampling and are always logged.
For clients using extended query protocol, durations of the Parse, Bind, and Execute steps are logged independently.
Note
When using this option together with log_statement, the text of statements that are logged because of
log_statementwill not be repeated in the duration log message. If you are not using syslog, it is recommended that you log the PID or session ID using log_line_prefix so that you can link the statement message to the later duration message using the process ID or session ID.log_min_duration_sample(integer) #Allows sampling the duration of completed statements that ran for at least the specified amount of time. This produces the same kind of log entries as log_min_duration_statement, but only for a subset of the executed statements, with sample rate controlled by log_statement_sample_rate. For example, if you set it to
100msthen all SQL statements that run 100ms or longer will be considered for sampling. Enabling this parameter can be helpful when the traffic is too high to log all queries. If this value is specified without units, it is taken as milliseconds. Setting this to zero samples all statement durations.-1(the default) disables sampling statement durations. Only superusers and users with the appropriateSETprivilege can change this setting.This setting has lower priority than
log_min_duration_statement, meaning that statements with durations exceedinglog_min_duration_statementare not subject to sampling and are always logged.Other notes for
log_min_duration_statementapply also to this setting.log_statement_sample_rate(floating point) #Determines the fraction of statements with duration exceeding log_min_duration_sample that will be logged. Sampling is stochastic, for example
0.5means there is statistically one chance in two that any given statement will be logged. The default is1.0, meaning to log all sampled statements. Setting this to zero disables sampled statement-duration logging, the same as settinglog_min_duration_sampleto-1. Only superusers and users with the appropriateSETprivilege can change this setting.log_transaction_sample_rate(floating point) #Sets the fraction of transactions whose statements are all logged, in addition to statements logged for other reasons. It applies to each new transaction regardless of its statements' durations. Sampling is stochastic, for example
0.1means there is statistically one chance in ten that any given transaction will be logged.log_transaction_sample_ratecan be helpful to construct a sample of transactions. The default is0, meaning not to log statements from any additional transactions. Setting this to1logs all statements of all transactions. Only superusers and users with the appropriateSETprivilege can change this setting.Note
Like all statement-logging options, this option can add significant overhead.
log_startup_progress_interval(integer) #Sets the amount of time after which the startup process will log a message about a long-running operation that is still in progress, as well as the interval between further progress messages for that operation. The default is 10 seconds. A setting of
0disables the feature. If this value is specified without units, it is taken as milliseconds. This setting is applied separately to each operation. This parameter can only be set in thepostgresql.conffile or on the server command line.For example, if syncing the data directory takes 25 seconds and thereafter resetting unlogged relations takes 8 seconds, and if this setting has the default value of 10 seconds, then a messages will be logged for syncing the data directory after it has been in progress for 10 seconds and again after it has been in progress for 20 seconds, but nothing will be logged for resetting unlogged relations.
Table 18.2 explains the message severity levels used by Postgres Pro. If logging output is sent to syslog or Windows' eventlog, the severity levels are translated as shown in the table.
Table 18.2. Message Severity Levels
| Severity | Usage | syslog | eventlog |
|---|---|---|---|
DEBUG1 .. DEBUG5 | Provides successively-more-detailed information for use by developers. | DEBUG | INFORMATION |
INFO | Provides information implicitly requested by the user, e.g., output from VACUUM VERBOSE. | INFO | INFORMATION |
NOTICE | Provides information that might be helpful to users, e.g., notice of truncation of long identifiers. | NOTICE | INFORMATION |
WARNING | Provides warnings of likely problems, e.g., COMMIT outside a transaction block. | NOTICE | WARNING |
ERROR | Reports an error that caused the current command to abort. | WARNING | ERROR |
LOG | Reports information of interest to administrators, e.g., checkpoint activity. | INFO | INFORMATION |
FATAL | Reports an error that caused the current session to abort. | ERR | ERROR |
PANIC | Reports an error that caused all database sessions to abort. | CRIT | ERROR |
18.8.3. What to Log #
Note
What you choose to log can have security implications; see Section 23.3.
application_name(string) #The
application_namecan be any string of less thanNAMEDATALENcharacters (64 characters in a standard build). It is typically set by an application upon connection to the server. The name will be displayed in thepg_stat_activityview and included in CSV log entries. It can also be included in regular log entries via the log_line_prefix parameter. Only printable ASCII characters may be used in theapplication_namevalue. Other characters are replaced with C-style hexadecimal escapes.debug_print_parse(boolean)debug_print_rewritten(boolean)debug_print_plan(boolean) #These parameters enable various debugging output to be emitted. When set, they print the resulting parse tree, the query rewriter output, or the execution plan for each executed query. These messages are emitted at
LOGmessage level, so by default they will appear in the server log but will not be sent to the client. You can change that by adjusting client_min_messages and/or log_min_messages. These parameters are off by default.debug_pretty_print(boolean) #When set,
debug_pretty_printindents the messages produced bydebug_print_parse,debug_print_rewritten, ordebug_print_plan. This results in more readable but much longer output than the “compact” format used when it is off. It is on by default.log_autovacuum_min_duration(integer) #Causes each action executed by autovacuum to be logged if it ran for at least the specified amount of time. Setting this to zero logs all autovacuum actions.
-1disables logging autovacuum actions. If this value is specified without units, it is taken as milliseconds. For example, if you set this to250msthen all automatic vacuums and analyzes that run 250ms or longer will be logged. In addition, when this parameter is set to any value other than-1, a message will be logged if an autovacuum action is skipped due to a conflicting lock or a concurrently dropped relation. The default is10min. Enabling this parameter can be helpful in tracking autovacuum activity. This parameter can only be set in thepostgresql.conffile or on the server command line; but the setting can be overridden for individual tables by changing table storage parameters.log_checkpoints(boolean) #Causes checkpoints and restartpoints to be logged in the server log. Some statistics are included in the log messages, including the number of buffers written and the time spent writing them. This parameter can only be set in the
postgresql.conffile or on the server command line. The default is on.log_connections(boolean) #Causes each attempted connection to the server to be logged, as well as successful completion of both client authentication (if necessary) and authorization. Only superusers and users with the appropriate
SETprivilege can change this parameter at session start, and it cannot be changed at all within a session. The default isoff.Note
Some client programs, like psql, attempt to connect twice while determining if a password is required, so duplicate “connection received” messages do not necessarily indicate a problem.
log_disconnections(boolean) #Causes session terminations to be logged. The log output provides information similar to
log_connections, plus the duration of the session. Only superusers and users with the appropriateSETprivilege can change this parameter at session start, and it cannot be changed at all within a session. The default isoff.log_duration(boolean) #Causes the duration of every completed statement to be logged. The default is
off. Only superusers and users with the appropriateSETprivilege can change this setting.For clients using extended query protocol, durations of the Parse, Bind, and Execute steps are logged independently.
Note
The difference between enabling
log_durationand setting log_min_duration_statement to zero is that exceedinglog_min_duration_statementforces the text of the query to be logged, but this option doesn't. Thus, iflog_durationisonandlog_min_duration_statementhas a positive value, all durations are logged but the query text is included only for statements exceeding the threshold. This behavior can be useful for gathering statistics in high-load installations.log_error_verbosity(enum) #Controls the amount of detail written in the server log for each message that is logged. Valid values are
TERSE,DEFAULT, andVERBOSE, each adding more fields to displayed messages.TERSEexcludes the logging ofDETAIL,HINT,QUERY, andCONTEXTerror information.VERBOSEoutput includes theSQLSTATEerror code (see also Appendix A) and the source code file name, function name, and line number that generated the error. Only superusers and users with the appropriateSETprivilege can change this setting.log_hostname(boolean) #By default, connection log messages only show the IP address of the connecting host. Turning this parameter on causes logging of the host name as well. Note that depending on your host name resolution setup this might impose a non-negligible performance penalty. This parameter can only be set in the
postgresql.conffile or on the server command line.log_line_prefix(string) #This is a
printf-style string that is output at the beginning of each log line.%characters begin “escape sequences” that are replaced with status information as outlined below. Unrecognized escapes are ignored. Other characters are copied straight to the log line. Some escapes are only recognized by session processes, and will be treated as empty by background processes such as the main server process. Status information may be aligned either left or right by specifying a numeric literal after the % and before the option. A negative value will cause the status information to be padded on the right with spaces to give it a minimum width, whereas a positive value will pad on the left. Padding can be useful to aid human readability in log files.This parameter can only be set in the
postgresql.conffile or on the server command line. The default is'%m [%p] 'which logs a time stamp and the process ID.Escape Effect Session only %aApplication name yes %uUser name yes %dDatabase name yes %rRemote host name or IP address, and remote port yes %hRemote host name or IP address yes %bBackend type no %pProcess ID no %PProcess ID of the parallel group leader, if this process is a parallel query worker no %tTime stamp without milliseconds no %mTime stamp with milliseconds no %nTime stamp with milliseconds (as a Unix epoch) no %iCommand tag: type of session's current command yes %eSQLSTATE error code no %cSession ID: see below no %lNumber of the log line for each session or process, starting at 1 no %sProcess start time stamp no %vVirtual transaction ID (backendID/localXID); see Section 71.1 no %xTransaction ID (0 if none is assigned); see Section 71.1 no %qProduces no output, but tells non-session processes to stop at this point in the string; ignored by session processes no %QQuery identifier of the current query. Query identifiers are not computed by default, so this field will be zero unless compute_query_id parameter is enabled or a third-party module that computes query identifiers is configured. yes %%Literal %no The backend type corresponds to the column
backend_typein the viewpg_stat_activity, but additional types can appear in the log that don't show in that view.The
%cescape prints a quasi-unique session identifier, consisting of two 4-byte hexadecimal numbers (without leading zeros) separated by a dot. The numbers are the process start time and the process ID, so%ccan also be used as a space saving way of printing those items. For example, to generate the session identifier frompg_stat_activity, use this query:SELECT to_hex(trunc(EXTRACT(EPOCH FROM backend_start))::integer) || '.' || to_hex(pid) FROM pg_stat_activity;Tip
If you set a nonempty value for
log_line_prefix, you should usually make its last character be a space, to provide visual separation from the rest of the log line. A punctuation character can be used too.Tip
Syslog produces its own time stamp and process ID information, so you probably do not want to include those escapes if you are logging to syslog.
Tip
The
%qescape is useful when including information that is only available in session (backend) context like user or database name. For example:log_line_prefix = '%m [%p] %q%u@%d/%a '
Note
The
%Qescape always reports a zero identifier for lines output by log_statement becauselog_statementgenerates output before an identifier can be calculated, including invalid statements for which an identifier cannot be calculated.log_lock_waits(boolean) #Controls whether a log message is produced when a session waits longer than deadlock_timeout to acquire a lock. This is useful in determining if lock waits are causing poor performance. The default is
off. Only superusers and users with the appropriateSETprivilege can change this setting.log_recovery_conflict_waits(boolean) #Controls whether a log message is produced when the startup process waits longer than
deadlock_timeoutfor recovery conflicts. This is useful in determining if recovery conflicts prevent the recovery from applying WAL.The default is
off. This parameter can only be set in thepostgresql.conffile or on the server command line.log_parameter_max_length(integer) #If greater than zero, each bind parameter value logged with a non-error statement-logging message is trimmed to this many bytes. Zero disables logging of bind parameters for non-error statement logs.
-1(the default) allows bind parameters to be logged in full. If this value is specified without units, it is taken as bytes. Only superusers and users with the appropriateSETprivilege can change this setting.This setting only affects log messages printed as a result of log_statement, log_duration, and related settings. Non-zero values of this setting add some overhead, particularly if parameters are sent in binary form, since then conversion to text is required.
log_parameter_types(boolean) #Controls whether each bind parameter value in a log message is prefixed with its data type. For example,
[integer] $1 = '42'.This setting only affects log messages that print bind parameters: error (
CONTEXT), statement-logging (DETAIL), and auto_explain messages.The default is
off. This parameter can only be set inpostgresql.conf, on the server command line, or using theSETcommand in the current session.log_parameter_max_length_on_error(integer) #If greater than zero, each bind parameter value reported in error messages is trimmed to this many bytes. Zero (the default) disables including bind parameters in error messages.
-1allows bind parameters to be printed in full. If this value is specified without units, it is taken as bytes.Non-zero values of this setting add overhead, as Postgres Pro will need to store textual representations of parameter values in memory at the start of each statement, whether or not an error eventually occurs. The overhead is greater when bind parameters are sent in binary form than when they are sent as text, since the former case requires data conversion while the latter only requires copying the string.
log_statement(enum) #Controls which SQL statements are logged. Valid values are
none(off),ddl,mod, andall(all statements).ddllogs all data definition statements, such asCREATE,ALTER, andDROPstatements.modlogs allddlstatements, plus data-modifying statements such asINSERT,UPDATE,DELETE,TRUNCATE, andCOPY FROM.PREPARE,EXECUTE, andEXPLAIN ANALYZEstatements are also logged if their contained command is of an appropriate type. For clients using extended query protocol, logging occurs when an Execute message is received, and values of the Bind parameters are included (with any embedded single-quote marks doubled).The default is
none. Only superusers and users with the appropriateSETprivilege can change this setting.Note
Statements that contain simple syntax errors are not logged even by the
log_statement=allsetting, because the log message is emitted only after basic parsing has been done to determine the statement type. In the case of extended query protocol, this setting likewise does not log statements that fail before the Execute phase (i.e., during parse analysis or planning). Setlog_min_error_statementtoERROR(or lower) to log such statements.Logged statements might reveal sensitive data. However, passwords are masked when written to the server log.
log_replication_commands(boolean) #Causes each replication command to be logged in the server log. See Section 54.4 for more information about replication command. The default value is
off. Only superusers and users with the appropriateSETprivilege can change this setting.log_temp_files(integer) #Controls logging of temporary file names and sizes. Temporary files can be created for sorts, hashes, and temporary query results. If enabled by this setting, a log entry is emitted for each temporary file, with the file size specified in bytes, when it is deleted. A value of zero logs all temporary file information, while positive values log only files whose size is greater than or equal to the specified amount of data. If this value is specified without units, it is taken as kilobytes. The default setting is -1, which disables such logging. Only superusers and users with the appropriate
SETprivilege can change this setting.log_timezone(string) #Sets the time zone used for timestamps written in the server log. Unlike TimeZone, this value is cluster-wide, so that all sessions will report timestamps consistently. The built-in default is
GMT, but that is typically overridden inpostgresql.conf; initdb will install a setting there corresponding to its system environment. See Section 8.5.3 for more information. This parameter can only be set in thepostgresql.conffile or on the server command line.
18.8.4. Using CSV-Format Log Output #
Including csvlog in the log_destination list provides a convenient way to import log files into a database table. This option emits log lines in comma-separated-values (CSV) format, with these columns: time stamp with milliseconds, user name, database name, process ID, client host:port number, session ID, per-session line number, command tag, session start time, virtual transaction ID, regular transaction ID, error severity, SQLSTATE code, error message, error message detail, hint, internal query that led to the error (if any), character count of the error position therein, error context, user query that led to the error (if any and enabled by log_min_error_statement), character count of the error position therein, location of the error in the Postgres Pro source code (if log_error_verbosity is set to verbose), application name, backend type, process ID of parallel group leader, and query id. Here is a sample table definition for storing CSV-format log output:
CREATE TABLE postgres_log ( log_time timestamp(3) with time zone, user_name text, database_name text, process_id integer, connection_from text, session_id text, session_line_num bigint, command_tag text, session_start_time timestamp with time zone, virtual_transaction_id text, transaction_id bigint, error_severity text, sql_state_code text, message text, detail text, hint text, internal_query text, internal_query_pos integer, context text, query text, query_pos integer, location text, application_name text, backend_type text, leader_pid integer, query_id bigint, PRIMARY KEY (session_id, session_line_num) );
To import a log file into this table, use the COPY FROM command:
COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv;
It is also possible to access the file as a foreign table, using the supplied file_fdw module.
There are a few things you need to do to simplify importing CSV log files:
Set
log_filenameandlog_rotation_ageto provide a consistent, predictable naming scheme for your log files. This lets you predict what the file name will be and know when an individual log file is complete and therefore ready to be imported.Set
log_rotation_sizeto 0 to disable size-based log rotation, as it makes the log file name difficult to predict.Set
log_truncate_on_rotationtoonso that old log data isn't mixed with the new in the same file.The table definition above includes a primary key specification. This is useful to protect against accidentally importing the same information twice. The
COPYcommand commits all of the data it imports at one time, so any error will cause the entire import to fail. If you import a partial log file and later import the file again when it is complete, the primary key violation will cause the import to fail. Wait until the log is complete and closed before importing. This procedure will also protect against accidentally importing a partial line that hasn't been completely written, which would also causeCOPYto fail.
18.8.5. Using JSON-Format Log Output #
Including jsonlog in the log_destination list provides a convenient way to import log files into many different programs. This option emits log lines in JSON format.
String fields with null values are excluded from output. Additional fields may be added in the future. User applications that process jsonlog output should ignore unknown fields.
Each log line is serialized as a JSON object with the set of keys and their associated values shown in Table 18.3.
Table 18.3. Keys and Values of JSON Log Entries
| Key name | Type | Description |
|---|---|---|
timestamp | string | Time stamp with milliseconds |
user | string | User name |
dbname | string | Database name |
pid | number | Process ID |
remote_host | string | Client host |
remote_port | number | Client port |
session_id | string | Session ID |
line_num | number | Per-session line number |
ps | string | Current ps display |
session_start | string | Session start time |
vxid | string | Virtual transaction ID |
txid | string | Regular transaction ID |
error_severity | string | Error severity |
state_code | string | SQLSTATE code |
message | string | Error message |
detail | string | Error message detail |
hint | string | Error message hint |
internal_query | string | Internal query that led to the error |
internal_position | number | Cursor index into internal query |
context | string | Error context |
statement | string | Client-supplied query string |
cursor_position | number | Cursor index into query string |
func_name | string | Error location function name |
file_name | string | File name of error location |
file_line_num | number | File line number of the error location |
application_name | string | Client application name |
backend_type | string | Type of backend |
leader_pid | number | Process ID of leader for active parallel workers |
query_id | number | Query ID |
18.8.6. Process Title #
These settings control how process titles of server processes are modified. Process titles are typically viewed using programs like ps or, on Windows, Process Explorer. See Section 26.1 for details.
cluster_name(string) #Sets a name that identifies this database cluster (instance) for various purposes. The cluster name appears in the process title for all server processes in this cluster. Moreover, it is the default application name for a standby connection (see synchronous_standby_names).
The name can be any string of less than
NAMEDATALENcharacters (64 characters in a standard build). Only printable ASCII characters may be used in thecluster_namevalue. Other characters are replaced with C-style hexadecimal escapes. No name is shown if this parameter is set to the empty string''(which is the default). This parameter can only be set at server start.update_process_title(boolean) #Enables updating of the process title every time a new SQL command is received by the server. This setting defaults to
onon most platforms, but it defaults tooffon Windows due to that platform's larger overhead for updating the process title. Only superusers and users with the appropriateSETprivilege can change this setting.