Функции трассировки сессии
Функции API в данном разделе реализованы в рамках поставляемого механизма трассировки, позволяющего включать и выключать отладочную печать с различными уровнями детализации.
Примеры использования функций приведены в подразделе «Сценарии использования» раздела «Трассировка сессий» документа «Руководство администратора».
start_session_tracing()
Функция включает трассировку для сессии с указанным PID, уровнем трассировки, и, опционально, именем файла.
При успешном включении трассировки в лог будет выведено следующее сообщение:
"Process <PID> is signaled tracing to ON with level <trace level> for filename "<path to trace file>""
Синтаксис:
start_session_tracing(integer, integer, text)
RETURNS void
Входные параметры:
| Название параметра | Тип значения | Описание |
|---|---|---|
pid | integer | Идентификатор процесса |
trace_level | integer | Уровень детализации выводимых сообщений |
trace_file_name | text | Файл записи трассировочной информации |
Возвращаемое значение:
Отсутствует. В случае успешного выполнения функция вернет пустое значение.
Пример использования:
SELECT start_session_tracing(<pid>, 15, '');
Пример вывода:
INFO: Process <pid> is signaled tracing to ON with level 15 for filename "<path to trace file>"
Заметки об использовании:
Если имя файла будет задано как NULL или пустой строкой, то будет сгенерировано имя файла трассировки по умолчанию. Для вызова функции пользователю необходимо иметь права суперпользователя, либо иметь выданную роль pg_tracing.
Ожидаемые ошибки:
При выключенной функции трассировки выводится ошибка:
"Session tracing isn't enabled"
При заданном уровне трассировки 0 выводится сообщение:
"Cannot start session tracing for process <PID> with level 0"
При попытке включения трассировки для сессии с включенной трассировкой будет получено сообщение:
"Session tracing for process <PID> already set"
При отсутствии процесса с указанным PID, в том числе, когда сессией управляет не суперпользователь (или владелец), будет получено сообщение вида:
"No process with PID <PID> for a session tracing"
stop_session_tracing()
Функция выключает трассировку для сессии с указанным PID.
При успешном выключении трассировки в лог выводится сообщение:
"Process <PID> is signaled tracing to OFF"
Синтаксис:
stop_session_tracing(integer)
RETURNS void
Входные параметры:
| Название параметра | Тип значения | Описание |
|---|---|---|
pid | integer | Идентификатор процесса |
Выходной результат:
Отсутствуют. В случае успешного выполнения функции значение вернется пустым.
Сценарии использования:
SELECT stop_session_tracing(<pid>);
Пример вывода:
INFO: Process <pid> is signaled tracing to OFF
Заметки об использовании:
Для вызова функции пользователю необходимо иметь права суперпользователя, либо иметь выданную роль pg_tracing.
Ожидаемые ошибки:
При выключенной функции трассировки будет получена следующая ошибка:
"Session tracing isn't enabled"
При попытке включения трассировки для сессии с уже включенной трассировкой будет получена ошибка:
"Session tracing for process <PID> not set"
При отсутствии процесса с указанным PID, в том числе когда сессией управляет не суперпользователь (или пользователь, не являющийся владельцем), будет получено сообщение вида:
"No process with PID <PID> for a session tracing"
Для обращения к функциям трассировки start_session_tracing и stop_session_tracing пользователю необходимо иметь права суперпользователя или иметь роль pg_tracing. Для включения и выключения трассировки через вызов функций start_session_tracing и stop_session_tracing на процесс сессии требуется либо наличие права суперпользователя, либо необходимо являться владельцем процесса (быть тем пользователем, который запустил процесс), либо иметь роль pg_read_all_tracing.
psql_session_tracing()
Функция выводит список сессий с указанием их уровня трассировки и путей к файлам трассировки.
Синтаксис:
psql_session_tracing(pid integer, OUT backend_pid integer, OUT level text, OUT filename text)
RETURNS SETOF record
Входные параметры:
| Название параметра | Тип значения | Описание |
|---|---|---|
pid | integer | Идентификатор процесса |
Выходной результат:
Набор записей с полями:
| Название параметра | Тип значения | Описание |
|---|---|---|
backend_pid | integer | Идентификатор процесса |
level | text | Перечисление текстовых значений (например, BASE | BIND | LOCK | RESOURCE) |
filename | text | Полный путь к файлу трассировки сессии |
Сценарии использования:
SELECT * FROM psql_session_tracing(<pid>);
Пример вывода:
backend_pid | level | filename
------------+-------------------------------+----------------------------------------------
<pid> | BASE | BIND | LOCK | RESOURCE | <path to trace file>
(1 row)
Заметки об использовании:
Функция доступна роли public.
Выводятся только те сессии, для которых текущий пользователь имеет права на роль, запустившую сессию. Пользователь с ролью pg_read_all_stats или суперпользователь видит все сессии.
Ожидаемые ошибки:
При выключенной функции трассировки будет выведена ошибка:
"Session tracing isn't enabled"