8.4.5.6 Reading Audit Log Files — MySQL 9.2

8.4.5.6 Чтение файлов журнала аудита

Плагин журнала аудита поддерживает функции, предоставляющие SQL-интерфейс для чтения файлов журнала аудита в формате JSON. (Эта возможность не применяется к файлам журнала, записанным в других форматах.)

При инициализации и настройке плагина журнала аудита для ведения журнала в формате JSON он использует каталог, содержащий текущий файл журнала аудита, в качестве места для поиска читаемых файлов журнала аудита. Плагин определяет расположение файла, базовое имя и суффикс по значению системной переменной audit_log_file, а затем ищет файлы с именами, соответствующими следующему шаблону, где [...] указывает необязательные части имени файла:

basename[.timestamp].suffix[.gz][[.pwd_id].enc]

Если имя файла заканчивается на .enc, файл зашифрован, и для чтения его незашифрованного содержимого требуется пароль расшифровки, полученный из хранилища ключей. Плагин журнала аудита определяет идентификатор хранилища ключей для пароля расшифровки следующим образом:

Если .enc предваряется pwd_id, идентификатор хранилища ключей равен audit_log-pwd_id.
Если .enc не предваряется pwd_id, файл имеет старое имя, существовавшее до реализации истории паролей шифрования журнала аудита. Идентификатор хранилища ключей равен audit_log.

Дополнительную информацию о зашифрованных файлах журнала аудита см. в разделе Шифрование файлов журнала аудита.

Плагин игнорирует файлы, которые были переименованы вручную и не соответствуют шаблону, а также файлы, которые были зашифрованы паролем, больше не доступным в хранилище ключей. Плагин открывает каждый оставшийся кандидатный файл, проверяет, что файл действительно содержит JSON события аудита, и сортирует файлы по временным меткам из первого события каждого файла. Результатом является последовательность файлов, доступ к которым осуществляется с помощью функций чтения журнала:

audit_log_read() считывает события из журнала аудита или закрывает процесс чтения.
audit_log_read_bookmark() возвращает закладку для последнего записанного события журнала аудита. Эта закладка подходит для передачи функции audit_log_read() для указания точки начала чтения.

audit_log_read() принимает необязательный JSON строковый аргумент, и результатом успешного вызова любой из функций является JSON строка.

Для использования функций для чтения журнала аудита следуйте этим принципам:

Вызовите audit_log_read() для чтения событий, начиная с заданной или текущей позиции, или для закрытия чтения:
- Для инициализации последовательности чтения журнала аудита передайте аргумент, указывающий позицию начала. Одним из способов является передача закладки, возвращенной функцией audit_log_read_bookmark():
```
SELECT audit_log_read(audit_log_read_bookmark());
```
- Для продолжения чтения с текущей позиции в последовательности вызовите audit_log_read() без указания позиции:
```
SELECT audit_log_read();
```
- Для явного закрытия последовательности чтения передайте JSON null аргумент:
```
SELECT audit_log_read('null');
```
  Явного закрытия чтения необязательно. Чтение закрывается неявно при завершении сессии или при инициализации новой последовательности чтения путем вызова audit_log_read() с аргументом, указывающим позицию начала.
Успешный вызов audit_log_read() для чтения событий возвращает JSON строку, содержащую массив событий аудита:
- Если конечное значение возвращаемого массива не является JSON null значением, последующие события и функция audit_log_read() могут быть вызваны повторно для их чтения.
- Если конечное значение возвращаемого массива является JSON null значением, больше событий для чтения в текущей последовательности нет.
Каждый элемент массива, не являющийся null, представляет событие в виде JSON хеша. Например:
```
[
  {
    "timestamp": "2020-05-18 13:39:33", "id": 0,
    "class": "connection", "event": "connect",
    ...
  },
  {
    "timestamp": "2020-05-18 13:39:33", "id": 1,
    "class": "general", "event": "status",
    ...
  },
  {
    "timestamp": "2020-05-18 13:39:33", "id": 2,
    "class": "connection", "event": "disconnect",
    ...
  },
  null
]
```
Дополнительную информацию о содержимом событий аудита в формате JSON см. в разделе Формат файла журнала аудита JSON.
Вызов audit_log_read() для чтения событий без указания позиции приводит к ошибке при соблюдении следующих условий:
- Последовательность чтения еще не была инициализирована путем передачи позиции функции audit_log_read().
- Больше событий для чтения в текущей последовательности нет; другими словами, функция audit_log_read() ранее возвращала массив, заканчивающийся JSON null значением.
- Недавняя последовательность чтения была закрыта путем передачи JSON null значения функции audit_log_read().
Для чтения событий в этих условиях необходимо сначала инициализировать последовательность чтения, вызвав audit_log_read() с аргументом, указывающим позицию.

Для указания позиции для audit_log_read() включите аргумент, указывающий, с какой точки начать чтение. Например, передайте закладку, представляющую собой JSON хеш, содержащий timestamp и id элементы, которые однозначно идентифицируют конкретное событие. Вот пример закладки, полученной при вызове функции audit_log_read_bookmark():

mysql> SELECT audit_log_read_bookmark();
+-------------------------------------------------+
| audit_log_read_bookmark()                       |
+-------------------------------------------------+
| { "timestamp": "2020-05-18 21:03:44", "id": 0 } |
+-------------------------------------------------+

Передача текущей закладки функции audit_log_read() инициализирует чтение событий, начиная с позиции закладки:

mysql> SELECT audit_log_read(audit_log_read_bookmark());
+-----------------------------------------------------------------------+
| audit_log_read(audit_log_read_bookmark())                             |
+-----------------------------------------------------------------------+
| [ {"timestamp":"2020-05-18 22:41:24","id":0,"class":"connection", ... |
+-----------------------------------------------------------------------+

Аргумент функции audit_log_read() является необязательным. При его наличии он может содержать JSON null значение для закрытия последовательности чтения или JSON хеш.

В аргументе-хеше для функции audit_log_read() элементы являются необязательными и управляют аспектами операции чтения, такими как позиция начала чтения или количество считываемых событий. Следующие элементы значимы (другие игнорируются):

start: Позиция в журнале аудита первого события для чтения. Позиция задается как временная метка, и чтение начинается с первого события, произошедшего в или после указанного значения временной метки. Элемент start имеет следующий формат, где value — это литеральное значение временной метки:
```
"start": { "timestamp": "value" }
```
timestamp, id: Позиция в журнале аудита первого события для чтения. Элементы timestamp и id вместе составляют закладку, которая однозначно идентифицирует конкретное событие. Если аргумент функции audit_log_read() включает любой из этих элементов, он должен включать оба для полного указания позиции, иначе произойдет ошибка.
max_array_length: Максимальное количество событий для чтения из журнала. Если этот элемент опущен, по умолчанию читается до конца журнала или до заполнения буфера чтения, в зависимости от того, что произойдет раньше.

Для указания начальной позиции для audit_log_read() передайте аргумент-хеш, который включает либо элемент start, либо закладку, состоящую из элементов timestamp и id. Если хеш-аргумент включает как элемент start, так и закладку, произойдет ошибка.

Если хеш-аргумент не указывает начальную позицию, чтение продолжается с текущей позиции.

Если значение временной метки не содержит части времени, предполагается часть времени 00:00:00.

Примеры аргументов, принимаемых функцией audit_log_read():

Читать события, начиная с первого события, которое происходит в или после заданной временной метки:
```
audit_log_read('{ "start": { "timestamp": "2020-05-24 12:30:00" } }')
```
Как в предыдущем примере, но прочитать не более 3 событий:
```
audit_log_read('{ "start": { "timestamp": "2020-05-24 12:30:00" }, "max_array_length": 3 }')
```
Читать события, начиная с первого события, которое происходит в или после 2020-05-24 00:00:00 (временная метка не включает часть времени, поэтому предполагается 00:00:00):
```
audit_log_read('{ "start": { "timestamp": "2020-05-24" } }')
```
Читать события, начиная с события, которое имеет точную временную метку и идентификатор события:
```
audit_log_read('{ "timestamp": "2020-05-24 12:30:00", "id": 0 }')
```
Как в предыдущем примере, но прочитать не более 3 событий:
```
audit_log_read('{ "timestamp": "2020-05-24 12:30:00", "id": 0, "max_array_length": 3 }')
```
Читать события, начиная с текущей позиции в последовательности чтения:
```
audit_log_read()
```
Прочитать не более 5 событий, начиная с текущей позиции в последовательности чтения:
```
audit_log_read('{ "max_array_length": 5 }')
```
Закрыть текущую последовательность чтения:
```
audit_log_read('null')
```

Строка JSON, возвращаемая любой из функций чтения журналов, может быть обработана по мере необходимости. Предположим, что вызов для получения закладки возвращает это значение:

mysql> SET @mark := audit_log_read_bookmark();
mysql> SELECT @mark;
+-------------------------------------------------+
| @mark                                           |
+-------------------------------------------------+
| { "timestamp": "2020-05-18 16:10:28", "id": 2 } |
+-------------------------------------------------+

Вызов функции audit_log_read() с этим аргументом может вернуть несколько событий. Чтобы ограничить audit_log_read() чтением не более N событий, добавьте в строку элемент max_array_length с этим значением. Например, чтобы прочитать одно событие, измените строку следующим образом:

mysql> SET @mark := JSON_SET(@mark, '$.max_array_length', 1);
mysql> SELECT @mark;
+----------------------------------------------------------------------+
| @mark                                                                |
+----------------------------------------------------------------------+
| {"id": 2, "timestamp": "2020-05-18 16:10:28", "max_array_length": 1} |
+----------------------------------------------------------------------+

Изменённая строка, передаваемая в функцию audit_log_read(), производит результат, содержащий не более одного события, независимо от того, сколько их доступно.

Если функция аудита вызывается из клиента mysql, результаты двоичных строк отображаются в шестнадцатеричном формате, в зависимости от значения параметра --binary-as-hex. Дополнительную информацию об этом параметре см. в Разделе 6.5.1, «mysql — Клиентская программа командной строки MySQL».

Чтобы установить ограничение на количество байтов, которые audit_log_read() считывает, установите системную переменную audit_log_read_buffer_size. Эта переменная имеет значение по умолчанию 32 КБ и может быть установлена во время выполнения. Каждый клиент должен установить своё сессионное значение audit_log_read_buffer_size в соответствии с его использованием функции audit_log_read().

Каждый вызов функции audit_log_read() возвращает столько доступных событий, сколько помещается в буфер. События, которые не помещаются в буфер, пропускаются и генерируют предупреждения. Учитывая это поведение, при оценке подходящего размера буфера для приложения следует учитывать следующие факторы:

Существует компромисс между количеством вызовов функции audit_log_read() и возвращаемыми событиями за вызов:
- При меньшем размере буфера вызовы возвращают меньше событий, поэтому требуется больше вызовов.
- При большем размере буфера вызовы возвращают больше событий, поэтому требуется меньше вызовов.
При меньшем размере буфера, таком как значение по умолчанию 32 КБ, существует большая вероятность того, что события превысят размер буфера и, следовательно, будут пропущены.

Дополнительную информацию о функциях чтения журналов аудита см. в Функциях журналов аудита.