Translation

Тикет:В работе [YDB] Перевод информации про версионирование документации YDB potapenko-k
Закрыт [Cloud] — Перевод — ru-RU > en-US — [YDB] Перевод информации про версионирование документации YDB vvazhov

4 files changed, 74 insertions, 165 deletions

diff --git a/ydb/docs/en/core/_includes/trunk.md b/ydb/docs/en/core/_includes/trunk.md
new file mode 100644
index 0000000000..a720d944ea
--- /dev/null
+++ b/ydb/docs/en/core/_includes/trunk.md
@@ -0,0 +1,5 @@
+{% note info %}
+
+This feature is under development; the source code is available in the _main_ branch of the [{{ ydb-short-name }} repository](https://github.com/ydb-platform/ydb). To learn how to build {{ ydb-short-name }} from the source code, see the [instructions](https://github.com/ydb-platform/ydb/blob/main/BUILD.md).
+
+{% endnote %}
diff --git a/ydb/docs/en/core/cluster/audit-log.md b/ydb/docs/en/core/cluster/audit-log.md
new file mode 100644
index 0000000000..9de814f679
--- /dev/null
+++ b/ydb/docs/en/core/cluster/audit-log.md
@@ -0,0 +1,67 @@
+# Audit log
+
+{% include [release-candidate](../_includes/trunk.md) %}
+
+An _audit log_ is a file that includes data about all the operations that tried to change the {{ ydb-short-name }} objects and ACLs, successfully or unsuccessfully, such as:
+
+* Creating, updating, and deleting databases.
+* Creating and deleting directories.
+* Creating or editing database scheme, changing the number of partitions, backup and recovery, copying and renaming, and deleting tables.
+* Creating, editing, or deleting topics.
+* Changing ACLs.
+
+The file is written on each {{ ydb-short-name }} cluster node. You can access your audit log only from a Terminal session.
+
+## Audit log events {#events}
+
+The information about each operation is saved to the audit log as a separate event. Each event includes a set of attributes. Some of those attributes describe the operation, others describe the transaction, within which the operation was executed. If a transaction included multiple operations, its attributes for such events will be the same.
+
+The operation attributes are as follows:
+
+* `operation` (required): Name of the operation.
+* `path` (optional): Path to the changed object.
+* `src path` (optional): Path to the source object used for copy and move operations. This field may include multiple values.
+* `dst path` (optional): Path to the target object used for copy and move operations. This field may include multiple values.
+* `set owner` (optional): New owner assigned when changing the ACL.
+* `add access` (optional): Access added when changing the ACL. This field may include multiple values.
+* `remove access` (optional): Access removed when changing the ACL. This field may include multiple values.
+* `protobuf request` (optional): Description of a schema or an ACL change in ProtoBuf format.
+
+The transaction attributes are as follows:
+
+* `txId` (required): Unique transaction ID.
+* `database` (optional): Path to the database.
+* `subject` (required): Event source SID in the `<login>@<subsystem>` format. Unless mandatory authentication is enabled, the key will have the `no subject` value.
+* `status` (required): Transaction completion status.
+* `reason` (optional): Error message.
+
+The format of event records is defined by the `format` parameter in the [cluster configuration](#enabling-audit-log). Here is an example of events in `JSON` format:
+
+```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"}
+```
+
+The same events in `TXT` format will look as follows:
+
+```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 {#enabling-audit-log}
+
+Saving events to the audit log is enabled at the cluster level. To enable this feature, add the `audit` section to the [cluster configuration](../deploy/configuration/config.md) file:
+
+```proto
+audit:
+  audit_file_path: "path_to_log_file"
+  format: JSON
+```
+
+| Parameter | Value |
+--- | ---
+| `audit_file_path` | Path to the file the audit log will be saved to. If the path and the file are missing, they will be created on each node at cluster startup. If the file exists, the data will be appended to it.<br>This parameter is optional. Make sure to specify either `audit_file_path` or `log_name`, or both. |
+| `format` | Audit log format.<br>The acceptable values are:<ul><li>`JSON`: Serialized [JSON]{% if lang == "ru" %}(https://ru.wikipedia.org/wiki/JSON){% endif %}{% if lang == "en" %}(https://en.wikipedia.org/wiki/JSON){% endif %}.</li><li>`TXT`: Text format.</ul> |
diff --git a/ydb/docs/en/core/cluster/audit-logs.md b/ydb/docs/en/core/cluster/audit-logs.md
deleted file mode 100644
index d2fbc93f51..0000000000
--- a/ydb/docs/en/core/cluster/audit-logs.md
+++ /dev/null
@@ -1,163 +0,0 @@
-# Audit logs
-
-All schema changes (successful and unsuccessful) and ACL changes are recorded in _audit logs_.
-
-## Enabling audit logs
-
-Audit logs are provided as part of YDB [component logging](./logs.md).
-
-To enable audit logs, you need to [change the logging level](../maintenance/embedded_monitoring/logs.md#change_log_level):
-
-1. Follow the link in the format
-
-   ```bash
-   http://<endpoint>:8765/cms
-   ```
-
-   The `Cluster Management System` page opens.
-
-1. On the **Configs** tab, click on the `LogConfigItems` line.
-
-1. Under `Component log settings`, find the `FLAT_TX_SCHEMESHARD` component. Set this component's logging level to `NOTICE` or higher.
-
-1. To save changes, click `Submit`
-
-Audit logs are written together with other YDB logs.
-
-## Audit log format {#format}
-
-A log event consists of comma-separated `key: value` fields:
-
-```text
-2022-08-03T22:41:43.860439Z node 1 :FLAT_TX_SCHEMESHARD NOTICE: AUDIT: txId: 281474976710670, database: /Root, subject: no subject, status: StatusSuccess, operation: MODIFY ACL, path: Root, add access: +(CT):user0@builtin, protobuf request: WorkingDir: "" OperationType: ESchemeOpModifyACL ModifyACL { Name: "Root" DiffACL: "\n\031\010\000\022\025\010\001\020@\032\ruser0@builtin \003" }
-
-2022-08-03T22:41:43.931561Z node 1 :FLAT_TX_SCHEMESHARD NOTICE: AUDIT: txId: 281474976710672, database: /Root, subject: user0@builtin, status: StatusAccepted, operation: DROP TABLE, path: /Root/Test1234/KeyValue, protobuf request: WorkingDir: "/Root/Test1234" OperationType: ESchemeOpDropTable Drop { Name: "KeyValue" }
-
-2022-08-03T22:41:43.895591Z node 1 :FLAT_TX_SCHEMESHARD NOTICE: AUDIT: txId: 281474976710671, database: /Root, subject: user0@builtin, status: StatusAccepted, operation: CREATE DIRECTORY, path: /Root/Test1234, protobuf request: WorkingDir: "/Root" OperationType: ESchemeOpMkDir MkDir { Name: "Test1234" } FailOnExist: true, operation: CREATE TABLE, path: /Root/Test1234/KeyValue, protobuf request: WorkingDir: "/Root/Test1234" OperationType: ESchemeOpCreateTable CreateTable { Name: "KeyValue" Columns { Name: "Key" Type: "Uint32" NotNull: false } Columns { Name: "Value" Type: "String" NotNull: false } KeyColumnNames: "Key" PartitionConfig { ColumnFamilies { Id: 0 StorageConfig { SysLog { PreferredPoolKind: "test" } Log { PreferredPoolKind: "test" } Data { PreferredPoolKind: "test" } } } } } FailOnExist: false
-```
-
-One event describes one transaction. An event can describe several operations performed within a single transaction. In this case, some of the fields will describe [transaction events](#tx-fields) and some of the fields will describe [operation events](#sub-operation-fields) within a transaction.
-
-### Transaction fields {#tx-fields}
-
-* `txId`: (mandatory) The unique transaction ID.
-* `database`: (optional) The path to the database.
-* `subject`: (mandatory) The event source SID (`<login>@<subsystem>` format). If not specified, the value is `no subject`.
-* `status`: (mandatory) The transaction completion status.
-* `reason`: (optional) An error message.
-
-### Operation fields {#sub-operation-fields}
-
-* `operation`: (mandatory) The operation name.
-* `path`: (optional) The path to the change object. This field might change during a transaction.
-* `src path`: (optional) The path to the source object (for copy and move operations).
-* `dst path`: (optional) The path to the target object (for copy and move operations).
-* `no path`: (optional) If there is no change object, the value is `no path`.
-* `set owner`: (optional) The new owner when changing ACL.
-* `add access`: (optional) Add access when changing ACL. The field can be repeated.
-* `remove access`: (optional) Remove access when changing ACL. The field can be repeated.
-* `protobuf request`: (optional) A description of a schema or ACL change in protobuf format.
-
-<!--
-### <a name="statuses"></a>List of possible statuses
-- StatusSuccess
-- StatusAccepted
-- StatusPathDoesNotExist
-- StatusPathIsNotDirectory
-- StatusAlreadyExists
-- StatusSchemeError
-- StatusNameConflict
-- StatusInvalidParameter
-- StatusMultipleModifications
-- StatusReadOnly
-- StatusTxIdNotExists
-- StatusTxIsNotCancellable
-- StatusAccessDenied
-- StatusNotAvailable
-- StatusPreconditionFailed
-- StatusRedirectDomain
-- StatusQuotaExceeded
-- StatusResourceExhausted
-
-### <a name="names"></a>List of possible operations
-- 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/en/core/cluster/toc_i.yaml b/ydb/docs/en/core/cluster/toc_i.yaml
index 01b96cf96d..5a75ed7b40 100644
--- a/ydb/docs/en/core/cluster/toc_i.yaml
+++ b/ydb/docs/en/core/cluster/toc_i.yaml
@@ -9,8 +9,8 @@ items:
   include: { mode: link, path: ../maintenance/embedded_monitoring/toc_p.yaml }
 - name: Cluster system views
   href: ../troubleshooting/system_views_cluster.md
-- name: Audit logs
-  href: audit-logs.md
+- name: Audit log
+  href: audit-log.md
 - name: Monitoring
   items:
     - name: Setting up monitoring for a local YDB cluster