Project: YDB (App Definition and Development / Database)
File: audit-log.md

An audit log is a stream that includes data about all the operations that tried to change the {{ ydb-short-name }} objects, successfully or unsuccessfully: Database: Creating, editing, and deleting databases. Directory: Creating and deleting. Table: Creating or editing table schema, changing the number of partitions, backup and recovery, copying and renaming, and deleting tables. Topic: Creating, editing, and deleting. ACL: Editing. The data of the audit log stream can be delivered to: File on each {{ ydb-short-name }} cluster node. Agent for delivering metrics. Standard error stream, `stderr`. You can use any of the listed destinations or their combinations. If you forward the streamto a file, access to the audit log is set byfile-system rights. Saving the audit log to a file is recommended for production installations. Forwarding the audit log to the standard error stream (`stderr`) is recommended for test installations. Further stream processing is determined by the {{ ydb-short-name }} cluster settings. The information about each operation is saved to the audit log as a separate event. Each event includes a set of attributes. Some attributes are common across events, while other attributes are determined by the specific {{ ydb-short-name }} component that generated the event. | Attribute | Description | |:-|:-| | Common attributes | | `subject` | Event source SID (`<login>@<subsystem>` format). Unless mandatory authentication is enabled, the attribute will be set to `{none}`.<br>Required. | | `operation` | Names of operations or actions are similar to theYQL syntax (for example, `ALTER DATABASE`, `CREATE TABLE`).<br>Required. | | `status` | Operation completion status.<br/>Acceptable values:<ul><li>`SUCCESS`: The operation completed successfully.</li><li>`ERROR`: The operation failed.</li><li>`IN-PROCESS`: The operation is in progress.</li></ul>Required. | | `reason` | Error message.<br>Optional. | | `component` | Name of the {{ ydb-short-name }} component that generated the event (for example, `schemeshard`).<br>Optional. | | `requestid` | Unique ID of the request that invoked the operation. You can use the `requestid` to differentiate events related to different operationsandlink the events together to build a singleaudit-related operation context.<br>Optional. | | `remote_address` | The IPof the client that delivered the request.<br>Optional. | | `detailed_status` | The status delivered by a {{ ydb-short-name }} component (for example, `StatusAccepted`, `StatusInvalidParameter `, `StatusNameConflict`).<br>Optional. | | Ownership and permission attributes | | `new_owner` | The SID of the new owner of the object when ownership is transferred. <br>Optional. | | `acl_add` | List of added permissions in (for example, `[+R:someuser]`).<br>Optional. | | `acl_remove` | List of revoked permissions in (for example, `[-R:someuser]`).<br>Optional. | | Custom attributes | | `userattrsadd` | List of custom attributes added when creating objects orupdating attributes (for example, `[attrname1: A, attrname2: B]`).<br>Optional. | | `userattrsremove` | List of custom attributes removed when creating objects orupdating attributes (for example, `[attrname1, attrname2]`).<br>Optional. | | Attributes of the SchemeShard component | | `txid` | Unique transaction ID. Similarly to `requestid`, this ID can be used to differentiate events related to different

| | `database` | Database path (for example, `/my_dir/db`).<br>Required. | | `paths` | List of paths in the database that arechanged by the operation (for example, `[/mydir/db/table-a, /mydir/db/table-b]`).<br>Required. | Delivering events to the audit log stream is enabled for the entire {{ ydb-short-name }} cluster. To enable it, add, to the , the `auditconfig` section, and specify in it one of the stream destinations (`filebackend`, `unifiedagentbackend`, `stderr_backend`) or their combination: ```yaml audit_config: file_backend: format: auditlogformat filepath: "pathtologfile" unifiedagentbackend: format: auditlogformat logname: sessionmetalogname stderr_backend: format: auditlogformat ``` | Key | Description | | | `file_backend` | Write the audit log to a file at each cluster node.</ul>Optional. | | `format` | Audit log format. The default value is `JSON`.<br>Acceptable values:<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>Optional. | | `filepath` | Path to the file that the audit log will be streamed 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 required if you use `filebackend`. | | `unifiedagentbackend` | Stream the audit log to the Unified Agent. In addition, you need to define the `uaclient_config` section in the .</ul>Optional. | | `logname` | The session metadata delivered with the message. Using the metadata, you can redirect the log stream to one or more child channels based on the condition: `logname: "sessionmetalogname"`.<br>Optional. | | `stderr_backend` | Forward the audit log to the standard error stream (`stderr`).</ul>Optional. | Sample configuration that saves the audit log text to `/var/log/ydb-audit.log`: ```yaml audit_config: file_backend: format: TXT file_path: "/var/log/ydb-audit.log" ``` Sample configuration that saves the audit log text to Yandex Unified Agent with the `audit` label and outputs it to `stderr` in JSON format: ```yaml audit_config: unifiedagentbackend: format: TXT log_name: audit stderr_backend: format: JSON ``` Fragment ofaudit log file in `JSON` format. ```json 2023-03-13T20:05:19.776132Z: {"paths":"[/mydir/db1/somedir]","txid":"562949953476313","database":"/mydir/db1","remoteaddress":"ipv6:[xxxx:xxx:xxx:xxx:x:xxxx:xxx:xxxx]:xxxxx","status":"SUCCESS","subject":"{none}","detailedstatus":"StatusAccepted","operation":"CREATE DIRECTORY","component":"schemeshard"} 2023-03-13T20:07:30.927210Z: {"reason":"Check failed: path: '/mydir/db1/somedir', error: path exist, request accepts it (id: [OwnerId: 72075186224037889, LocalPathId: 3], type: EPathTypeDir, state: EPathStateNoChanges)","paths":"[/mydir/db1/somedir]","txid":"844424930216970","database":"/mydir/db1","remoteaddress":"ipv6:[xxxx:xxx:xxx:xxx:x:xxxx:xxx:xxxx]:xxxxx","status":"SUCCESS","subject":"{none}","detailedstatus":"StatusAlreadyExists","operation":"CREATE DIRECTORY","component":"schemeshard"} 2023-03-13T19:59:27.614731Z: {"paths":"[/mydir/db1/sometable]","txid":"562949953426315","database":"/mydir/db1","remoteaddress":"{none}","status":"SUCCESS","subject":"{none}","detailedstatus":"StatusAccepted","operation":"CREATE TABLE","component":"schemeshard"} 2023-03-13T20:10:44.345767Z: {"paths":"[/mydir/db1/sometable, /mydir/db1/anothertable]","txid":"562949953506313","database":"{none}","remoteaddress":"ipv6:[xxxx:xxx:xxx:xxx:x:xxxx:xxx:xxxx]:xxxxx","status":"SUCCESS","subject":"{none}","detailed_status":"StatusAccepted","operation":"ALTER TABLE RENAME","component":"schemeshard"} 2023-03-14T10:41:36.485788Z: {"paths":"[/mydir/db1/somedir]","txid":"281474976775658","database":"/mydir/db1","remoteaddress":"ipv6:[xxxx:xxx:xxx:xxx:x:xxxx:xxx:xxxx]:xxxxx","status":"SUCCESS","subject":"{none}","detailedstatus":"StatusAccepted","operation":"MODIFY ACL","component":"schemeshard","acl_add":"[+(ConnDB):subject:-]"} ``` Event that occurred at `2023-03-13T20:05:19.776132Z` in JSON-pretty: ```json { "paths": "[/mydir/db1/somedir]", "tx_id": "562949953476313", "database": "/my_dir/db1", "remote_address": "ipv6:[xxxx:xxx:xxx:xxx:x:xxxx:xxx:xxxx]:xxxxx", "status": "SUCCESS", "subject": "{none}", "detailed_status": "StatusAccepted", "operation": "CREATE DIRECTORY", "component": "schemeshard" } ``` The same events in `TXT` format will look as follows: ```txt 2023-03-13T20:05:19.776132Z: component=schemeshard, txid=844424930186969, remoteaddress=ipv6:[xxxx:xxx:xxx:xxx:x:xxxx:xxx:xxxx]:xxxxx, subject={none}, database=/mydir/db1, operation=CREATE DIRECTORY, paths=[/mydir/db1/somedir], status=SUCCESS, detailedstatus=StatusAccepted 2023-03-13T20:07:30.927210Z: component=schemeshard, txid=281474976775657, remoteaddress=ipv6:[xxxx:xxx:xxx:xxx:x:xxxx:xxx:xxxx]:xxxxx, subject={none}, database=/mydir/db1, operation=CREATE DIRECTORY, paths=[/mydir/db1/somedir], status=SUCCESS, detailedstatus=StatusAlreadyExists, reason=Check failed: path: '/mydir/db1/somedir', error: path exist, request accepts it (id: [OwnerId: 72075186224037889, LocalPathId: 3], type: EPathTypeDir, state: EPathStateNoChanges) 2023-03-13T19:59:27.614731Z: component=schemeshard, txid=562949953426315, remoteaddress={none}, subject={none}, database=/mydir/db1, operation=CREATE TABLE, paths=[/mydir/db1/sometable], status=SUCCESS, detailedstatus=StatusAccepted 2023-03-13T20:10:44.345767Z: component=schemeshard, txid=562949953506313, remoteaddress=ipv6:[xxxx:xxx:xxx:xxx:x:xxxx:xxx:xxxx]:xxxxx, subject={none}, database={none}, operation=ALTER TABLE RENAME, paths=[/mydir/db1/sometable, /mydir/db1/anothertable], status=SUCCESS, detailed_status=StatusAccepted 2023-03-14T10:41:36.485788Z: component=schemeshard, txid=281474976775658, remoteaddress=ipv6:[xxxx:xxx:xxx:xxx:x:xxxx:xxx:xxxx]:xxxxx, subject={none}, database=/mydir/db1, operation=MODIFY ACL, paths=[/mydir/db1/somedir], status=SUCCESS, detailedstatus=StatusSuccess, acl_add=[+(ConnDB):subject:-] ```