Audit logs improved clarity

updated

3 files changed, 67 insertions, 159 deletions

diff --git a/ydb/docs/ru/core/cluster/audit-log.md b/ydb/docs/ru/core/cluster/audit-log.md
new file mode 100644
index 00000000000..4c66f4ce306
--- /dev/null
+++ b/ydb/docs/ru/core/cluster/audit-log.md
@@ -0,0 +1,65 @@
+# Аудитный лог
+
+_Аудитный лог_ — это файл, который содержит информацию обо всех операциях (успешных или не успешных) по изменению объектов {{ ydb-short-name }} и ACL, таких как:
+
+* создание, изменение и удаление баз данных;
+* создание и удаление директорий;
+* создание, изменение схемы, изменение количества партиций, резервное копирование и восстановление, копирование и переименование, удаление таблиц;
+* создание, изменение, удаление топиков;
+* изменение ACL.
+
+Файл пишется на каждом узле кластера {{ ydb-short-name }}. Доступ к аудитному логу возможен только через сессию терминала.
+
+## События аудитного лога {#events}
+
+Информация о каждой операции записывается в аудитный лог в виде отдельного события. Событие содержит набор атрибутов. Одни атрибуты описывают операцию, другие - транзакцию, в которой выполнялась операция. Если несколько операций выполнялись в одной транзакции, то атрибуты транзакции таких событий будут совпадать.
+
+Атрибуты операции:
+
+* `operation` — обязательный, имя операции.
+* `path` — не обязательный, путь к объекту изменения.
+* `src path` — не обязательный, путь к исходному объекту (для операций копирования и перемещения). Поле может содержать несколько значений.
+* `dst path` — не обязательный, путь к конечному объекту (для операций копирования и перемещения). Поле может содержать несколько значений.
+* `set owner` — не обязательный, новый владелец при изменении ACL.
+* `add access` — не обязательный, добавление доступа при изменении ACL. Поле может содержать несколько значений.
+* `remove access` — не обязательный, удаление доступа при изменении ACL. Поле может содержать несколько значений.
+* `protobuf request` — не обязательный, описание изменения схемы или ACL в формате protobuf.
+
+Атрибуты транзакции:
+
+* `txId` — обязательный, уникальный идентификатор транзакции.
+* `database` — не обязательный, путь к базе данных.
+* `subject` — обязательный, SID источника события (формат `<login>@<subsystem>`). Если обязательная аутентификация не включена, ключ будет иметь значение `no subject`.
+* `status` — обязательный, статус завершения транзакции.
+* `reason` — не обязательный, сообщение об ошибке.
+
+Формат записи событий определяется параметром `format` в [конфигурации кластера](#enabling-audit-log). Пример событий в формате `JSON`:
+
+```json
+2022-12-05T18:58:39.517833Z: {"protobuf request":"WorkingDir: \"/my_dir/db1\" OperationType: ESchemeOpCreateTable CreateTable { Name: \"my_table\" Columns { Name: \"id\" Type: \"Uint64\" NotNull: false } Columns { Name: \"name\" Type: \"String\" NotNull: false } KeyColumnNames: \"id\" PartitionConfig { PartitioningPolicy { SizeToSplit: 2147483648 } ColumnFamilies { StorageConfig { SysLog { PreferredPoolKind: \"ssd\" } Log { PreferredPoolKind: \"ssd\" } Data { PreferredPoolKind: \"ssd\" } } } } } FailOnExist: false","txId":"281474976720657","subject":"no subject","status":"StatusAccepted","operation":"CREATE TABLE","path":"/my_dir/db1/my_table","database":"/my_dir/db1"}
+
+2022-12-05T19:01:22.309877Z: {"dst path":"{/my_dir/db1/my_table2}","database":"/my_dir/db1","txId":"281474976720658","protobuf request":"OperationType: ESchemeOpMoveTable MoveTable { SrcPath: \"/my_dir/db1/my_table\" DstPath: \"/my_dir/db1/my_table2\" }","status":"StatusAccepted","subject":"no subject","src path":"{/my_dir/db1/my_table}","operation":"ALTER TABLE RENAME"}
+```
+
+Те же события в формате `TXT`:
+
+```txt
+2022-12-05T18:58:39.517833Z: txId=281474976720657, database=/my_dir/db1, subject=no subject, status=StatusAccepted, operation=CREATE TABLE, path=/my_dir/db1/my_table, protobuf request=WorkingDir: "/my_dir/db1" OperationType: ESchemeOpCreateTable CreateTable { Name: "my_table" Columns { Name: "id" Type: "Uint64" NotNull: false } Columns { Name: "name" Type: "String" NotNull: false } KeyColumnNames: "id" PartitionConfig { PartitioningPolicy { SizeToSplit: 2147483648 } ColumnFamilies { StorageConfig { SysLog { PreferredPoolKind: "ssd" } Log { PreferredPoolKind: "ssd" } Data { PreferredPoolKind: "ssd" } } } } } FailOnExist: false
+
+2022-12-05T19:01:22.309877Z: txId=281474976720658, database=/my_dir/db1, subject=no subject, status=StatusAccepted, operation=ALTER TABLE RENAME, src path={/my_dir/db1/my_table}, dst path={/my_dir/db1/my_table2}, protobuf request=OperationType: ESchemeOpMoveTable MoveTable { SrcPath: "/my_dir/db1/my_table" DstPath: "/my_dir/db1/my_table2" }
+```
+
+## Включение аудитного лога {#enabling-audit-log}
+
+Сохранение событий в аудитный лог включается целиком для кластера. Для включения необходимо в файл [конфигурации кластера](../deploy/configuration/config.md) добавить секцию `audit`:
+
+```proto
+audit:
+  audit_file_path: "path_to_log_file"
+  format: JSON
+```
+
+Параметр | Значение
+--- | ---
+`audit_file_path` | Путь к файлу, в который будет записываться аудитный лог. Путь и файл в случае их отсутствия будут созданы на каждом узле при старте кластера. Если файл существует, запись в него будет продолжена.<br>Не обязательный. Должен быть указан один из параметров или оба: `audit_file_path` или `log_name`.
+`format` | Формат аудитного лога.<br>Возможные значения:<ul><li>`JSON` — [JSON]{% if lang == "ru" %}(https://ru.wikipedia.org/wiki/JSON){% endif %}{% if lang == "en" %}(https://en.wikipedia.org/wiki/JSON){% endif %} в сериализованном виде;</li><li>`TXT` — текст.</ul>
diff --git a/ydb/docs/ru/core/cluster/audit-logs.md b/ydb/docs/ru/core/cluster/audit-logs.md
deleted file mode 100644
index e1c1cda5abf..00000000000
--- a/ydb/docs/ru/core/cluster/audit-logs.md
+++ /dev/null
@@ -1,157 +0,0 @@
-# Аудитные логи
-
-Информация обо всех изменениях схемы (успешных и неуспешных), а также об изменениях ACL записывается в _аудитные логи_.
-
-## Подключение аудитных логов
-
-Чтобы подключить аудитные логи, необходимо в файле отвечающем за конфигурацию кластера прописать:
-```
-audit:
-  audit_file_path: "/Berkanavt/kikimr/audit.log"
-  format: JSON
-```
-* `audit_file_path` - путь к файлу, куда будут писаться аудитные логи
-* `format` - формат записи аудитных файлов (возможные значения: JSON или TXT)
-
-## Формат аудитных логов {#format}
-
-Событие лога состоит из полей `ключ: значение`. Конкретный формат записи полей зависит от значения `format` в cluster.yaml:
-
-###### Запись в формате JSON
-```
-2022-12-05T18:58:39.517833Z: {"protobuf request":"WorkingDir: \"/ydb_vla_dev07/db1\" OperationType: ESchemeOpCreateTable CreateTable { Name: \"my_table\" Columns { Name: \"id\" Type: \"Uint64\" NotNull: false } Columns { Name: \"name\" Type: \"String\" NotNull: false } KeyColumnNames: \"id\" PartitionConfig { PartitioningPolicy { SizeToSplit: 2147483648 } ColumnFamilies { StorageConfig { SysLog { PreferredPoolKind: \"ssd\" } Log { PreferredPoolKind: \"ssd\" } Data { PreferredPoolKind: \"ssd\" } } } } } FailOnExist: false","txId":"281474976720657","subject":"no subject","status":"StatusAccepted","operation":"CREATE TABLE","path":"/ydb_vla_dev07/db1/my_table","database":"/ydb_vla_dev07/db1"}
-
-2022-12-05T19:01:22.309877Z: {"dst path":"{/ydb_vla_dev07/db1/my_table2}","database":"/ydb_vla_dev07/db1","txId":"281474976720658","protobuf request":"OperationType: ESchemeOpMoveTable MoveTable { SrcPath: \"/ydb_vla_dev07/db1/my_table\" DstPath: \"/ydb_vla_dev07/db1/my_table2\" }","status":"StatusAccepted","subject":"no subject","src path":"{/ydb_vla_dev07/db1/my_table}","operation":"ALTER TABLE RENAME"}
-```
-
-###### Запись в формате TXT
-```
-2022-12-05T18:44:19.831251Z: txId=562949953441313, database=/ydb_vla_dev07/db1, subject=no subject, status=StatusAccepted, operation=CREATE TABLE, path=/ydb_vla_dev07/db1/my_table, protobuf request=WorkingDir: "/ydb_vla_dev07/db1" OperationType: ESchemeOpCreateTable CreateTable { Name: "my_table" Columns { Name: "id" Type: "Uint64" NotNull: false } Columns { Name: "name" Type: "String" NotNull: false } KeyColumnNames: "id" PartitionConfig { PartitioningPolicy { SizeToSplit: 2147483648 } ColumnFamilies { StorageConfig { SysLog { PreferredPoolKind: "ssd" } Log { PreferredPoolKind: "ssd" } Data { PreferredPoolKind: "ssd" } } } } } FailOnExist: false
-
-2022-12-05T18:45:32.790052Z: txId=562949953441314, database=/ydb_vla_dev07/db1, subject=no subject, status=StatusAccepted, operation=ALTER TABLE RENAME, src path={/ydb_vla_dev07/db1/my_table}, dst path={/ydb_vla_dev07/db1/my_table2}, protobuf request=OperationType: ESchemeOpMoveTable MoveTable { SrcPath: "/ydb_vla_dev07/db1/my_table" DstPath: "/ydb_vla_dev07/db1/my_table2" }
-```
-
-Событие описаывает операцию. Несколько событий могут описывать несколько операций выполненных в рамках одной транзакции. В этом случае часть полей будут описывать [события транзакции](#tx-fields), а часть полей — [события операций](#sub-operation-fields) внутри транзакции.
-
-### Поля операции {#tx-fields}
-
-* `txId` — (обязательно) уникальный идентификатор транзакции.
-* `database` — (опционально) путь к базе данных.
-* `subject` — (обязательно) SID источника события (формат `<login>@<subsystem>`). Если не определен, значение `no subject`.
-* `status` — (обязательно) статус завершения транзакции.
-* `reason` — (опционально) сообщение об ошибке.
-
-### Поля операции {#sub-operation-fields}
-
-* `operation` — (обязательно) название операции.
-* `path` — (опционально) путь к объекту изменения. Это поле может меняться в рамках транзакции.
-* `src path` — (опционально) путь к исходному объекту (для операций копирования и перемещения). Поле может содержать несколько значений.
-* `dst path` — (опционально) путь к конечному объекту (для операций копирования и перемещения). Поле может содержать несколько значений.
-* `set owner` — (опционально) новый владелец при изменении ACL.
-* `add access` — (опционально) добавление доступа при изменении ACL. Поле может содержать несколько значений.
-* `remove access` — (опционально) удаление доступа при изменении ACL. Поле может содержать несколько значений.
-* `protobuf request` — (опционально) Описание изменения схемы или ACL в формате protobuf.
-
-<!-- 
-### <a name="statuses"></a>Список возможных статусов
-- StatusSuccess
-- StatusAccepted
-- StatusPathDoesNotExist
-- StatusPathIsNotDirectory
-- StatusAlreadyExists
-- StatusSchemeError
-- StatusNameConflict
-- StatusInvalidParameter
-- StatusMultipleModifications
-- StatusReadOnly
-- StatusTxIdNotExists
-- StatusTxIsNotCancellable
-- StatusAccessDenied
-- StatusNotAvailable
-- StatusPreconditionFailed
-- StatusRedirectDomain
-- StatusQuotaExceeded
-- StatusResourceExhausted
-
-### <a name="names"></a>Список возможных операций
-- CREATE TABLE
-- CREATE DIRECTORY
-- CREATE PERSISTENT QUEUE
-- DROP TABLE
-- DROP PERSISTENT QUEUE
-- ALTER TABLE
-- ALTER PERSISTENT QUEUE
-- MODIFY ACL
-- DROP DIRECTORY
-- ALTER TABLE PARTITIONS
-- BACKUP TABLE
-- CREATE DATABASE
-- DROP DATABASE
-- CREATE RTMR VOLUME
-- CREATE BLOCK STORE VOLUME
-- ALTER BLOCK STORE VOLUME
-- ALTER BLOCK STORE VOLUME ASSIGN
-- DROP BLOCK STORE VOLUME
-- CREATE KESUS
-- DROP KESUS
-- DROP DATABASE
-- CREATE SOLOMON VOLUME
-- DROP SOLOMON VOLUME
-- ALTER KESUS
-- ALTER DATABASE
-- ALTER USER ATTRIBUTES
-- DROP PATH UNSAFE
-- CREATE TABLE WITH INDEXES
-- CREATE INDEX
-- CREATE TABLE COPY FROM
-- DROP INDEX
-- CREATE DATABASE
-- ALTER DATABASE
-- DROP DATABASE
-- ESchemeOp_DEPRECATED_35
-- ALTER DATABASE MIGRATE
-- ALTER DATABASE MIGRATE DECISION
-- BUILD INDEX
-- ALTER TABLE BUILD INDEX INIT
-- ALTER TABLE LOCK
-- ALTER TABLE BUILD INDEX APPLY
-- ALTER TABLE BUILD INDEX FINISH
-- ALTER INDEX
-- ALTER SOLOMON VOLUME
-- ALTER TABLE UNLOCK
-- ALTER TABLE BUILD INDEX FINISH
-- ALTER TABLE BUILD INDEX INIT
-- ALTER TABLE DROP INDEX
-- ALTER TABLE DROP INDEX
-- ALTER TABLE BUILD INDEX CANCEL
-- CREATE FILE STORE
-- ALTER FILE STORE
-- DROP FILE STORE
-- RESTORE TABLE
-- CREATE COLUMN STORE
-- ALTER COLUMN STORE
-- DROP COLUMN STORE
-- CREATE COLUMN TABLE
-- ALTER COLUMN TABLE
-- DROP COLUMN TABLE
-- ALTER LOGIN
-- ATER TABLE CREATE CDC STREAM
-- CREATE CDC STREAM
-- ATER TABLE CREATE CDC STREAM
-- ATER CDC STREAM
-- ATER CDC STREAM
-- ATER TABLE ATER CDC STREAM
-- DROP CDC STREAM
-- DROP CDC STREAM
-- ATER TABLE DROP CDC STREAM
-- ALTER TABLE RENAME
-- CREATE SEQUENCE
-- ALTER SEQUENCE
-- DROP SEQUENCE
-- CREATE REPLICATION
-- ALTER REPLICATION
-- DROP REPLICATION
-- CREATE BLOB DEPOT
-- ALTER BLOB DEPOT
-- DROP BLOB DEPOT
-- ALTER TABLE INDEX RENAME -->
diff --git a/ydb/docs/ru/core/cluster/toc_i.yaml b/ydb/docs/ru/core/cluster/toc_i.yaml
index 63823018267..89161d4feac 100644
--- a/ydb/docs/ru/core/cluster/toc_i.yaml
+++ b/ydb/docs/ru/core/cluster/toc_i.yaml
@@ -9,8 +9,8 @@ items:
   include: { mode: link, path: ../maintenance/embedded_monitoring/toc_p.yaml }
 - name: Системные таблицы кластера
   href: ../troubleshooting/system_views_cluster.md
-- name: Аудитные логи
-  href: audit-logs.md
+- name: Аудитный лог
+  href: audit-log.md
 - name: Мониторинг
   items:
     - name: Настройка мониторинга локального кластера YDB