From 1404a9f8b3447d7f8c947f7fbc98db402c8a0a3a Mon Sep 17 00:00:00 2001 From: shiyuhang <1136742008@qq.com> Date: Mon, 15 Sep 2025 18:25:55 +0800 Subject: [PATCH 01/20] refactor db audit log --- tidb-cloud/serverless-audit-logging.md | 332 ++++++++++++++++++++----- 1 file changed, 271 insertions(+), 61 deletions(-) diff --git a/tidb-cloud/serverless-audit-logging.md b/tidb-cloud/serverless-audit-logging.md index 5fb94cf7dabaf..372db20bc4be8 100644 --- a/tidb-cloud/serverless-audit-logging.md +++ b/tidb-cloud/serverless-audit-logging.md @@ -1,41 +1,98 @@ --- -title: Database Audit Logging for {{{ .starter }}} and Essential -summary: Learn about how to audit a {{{ .starter }}} or {{{ .essential }}} cluster in TiDB Cloud. +title: Database Audit Logging for {{{ .essential }}} +summary: Learn about how to audit a {{{ .essential }}} cluster in TiDB Cloud. --- -# Database Audit Logging (Beta) for {{{ .starter }}} and Essential +# Database Audit Logging (Beta) for {{{ .essential }}} -{{{ .starter }}} and {{{ .essential }}} provide you with a database audit logging feature to record a history of user access details (such as any SQL statements executed) in logs. +{{{ .essential }}} provide you with a database audit logging feature to record a history of user access details (such as any SQL statements executed) in logs. > **Note:** > -> Currently, the database audit logging feature is only available upon request. To request this feature, click **?** in the lower-right corner of the [TiDB Cloud console](https://tidbcloud.com) and click **Request Support**. Then, fill in "Apply for {{{ .starter }}} or {{{ .essential }}} database audit logging" in the **Description** field and click **Submit**. +> Currently, the database audit logging feature is only available upon request. To request this feature, click **?** in the lower-right corner of the [TiDB Cloud console](https://tidbcloud.com) and click **Request Support**. Then, fill in "Apply for {{{ .essential }}} database audit logging" in the **Description** field and click **Submit**. To assess the effectiveness of user access policies and other information security measures of your organization, it is a security best practice to conduct a periodic analysis of the database audit logs. The audit logging feature is disabled by default. To audit a cluster, you need to enable audit logging for it. -## Enable audit logging +## Audit logging configurations -To enable audit logging for a {{{ .starter }}} or {{{ .essential }}} cluster, use the [TiDB Cloud CLI](/tidb-cloud/ticloud-auditlog-config.md). +### Data redaction -```shell -ticloud serverless audit-log config -c --enabled +{{{ .essential }}} redact sensitive data in the audit logs by default. Take the following SQL statement as an example: + +```sql +INSERT INTO `test`.`users` (`id`, `name`, `password`) VALUES (1, 'Alice', '123456'); ``` -To disable audit logging for a {{{ .starter }}} or {{{ .essential }}} cluster, use the [TiDB Cloud CLI](/tidb-cloud/ticloud-auditlog-config.md). +It is redacted as follows: -```shell -ticloud serverless audit-log config -c --enabled=false +```sql +INSERT INTO `test`.`users` (`id`, `name`, `password`) VALUES ( ... ); ``` -> **Note:** -> -> Only enabling audit logging will not generate audit logs. You need to configure filters to specify what events to log. For more information, see [Manage audit logging filter rules](#manage-audit-logging-filter-rules). +### Log file rotation -## Manage audit logging filter rules +{{{ .essential }}} generate a new audit log file when either of the following conditions is met: + +- The size of the current log file reaches rotation size (100 MB by default). +- Rotation interval (one hour by default) has passed since the previous log generation. Depending on the internal scheduling mechanism, log generation might be delayed by a few minutes. + +## Audit logging locations + +You can store the audit logs to the following locations: + +- TiDB Cloud +- [Amazon S3](https://aws.amazon.com/s3/) +- [Google Cloud Storage](https://cloud.google.com/storage) +- [Azure Blob Storage](https://azure.microsoft.com/en-us/services/storage/blobs/) +- [Alibaba Cloud Object Storage Service (OSS)](https://www.alibabacloud.com/product/oss) + +### TiDB Cloud + +you can store audit logs in TiDB Cloud and download them to your local machine. The audit logs will be expired and deleted after 365 days. To request longer storage duration, contact [TiDB Cloud Support](/tidb-cloud/tidb-cloud-support.md). + +### Amazon S3 + +To store audit logs to Amazon S3, you need to provide the following information: + +- URI: `s3:////` +- One of the following access credentials: + - [An access key](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html): make sure the access key has the `s3:PutObject` and `s3:ListBucket` permissions. + - [A role ARN](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference-arns.html): make sure the role ARN (Amazon Resource Name) has the `s3:PutObject` permissions. Note that only clusters hosted on AWS support the role ARN. + +For more information, see [Configure Amazon S3 access](/tidb-cloud/serverless-external-storage.md#configure-amazon-s3-access). + +### Google Cloud Storage + +To store audit logs to Google Cloud Storage, you need to provide the following information: + +- URI: `gs:////` +- Access credential: a **base64 encoded** [service account key](https://cloud.google.com/iam/docs/creating-managing-service-account-keys) for your bucket. Make sure the service account key has the `storage.objects.create` and `storage.objects.delete` permission. + +For more information, see [Configure GCS access](/tidb-cloud/serverless-external-storage.md#configure-gcs-access). + +### Azure Blob Storage + +To store audit logs to Azure Blob Storage, you need to provide the following information: + +- URI: `azure://.blob.core.windows.net///` or `https://.blob.core.windows.net///` +- Access credential: a [shared access signature (SAS) token](https://docs.microsoft.com/en-us/azure/storage/common/storage-sas-overview) for your Azure Blob Storage container. Make sure the SAS token has the `Read` and `Write` permissions on the `Container` and `Object` resources. -To filter the audit logging, you need to create a filter rule to specify which events to log. You can use the [TiDB Cloud CLI](/tidb-cloud/ticloud-auditlog-filter-create.md) to manage the filter rules. +For more information, see [Configure Azure Blob Storage access](/tidb-cloud/serverless-external-storage.md#configure-azure-blob-storage-access). + +### Alibaba Cloud OSS + +To store audit logs to Alibaba Cloud OSS, you need to provide the following information: + +- URI: `oss:////` +- Access credential: An [AccessKey pair](https://www.alibabacloud.com/help/en/ram/user-guide/create-an-accesskey-pair) for your Alibaba Cloud account. Make sure the AccessKey pair has the `oss:PutObject` and `oss:GetBucketInfo` permissions to allow data export to the OSS bucket. + +For more information, see [Configure Alibaba Cloud Object Storage Service (OSS) access](/tidb-cloud/serverless-external-storage.md#configure-alibaba-cloud-object-storage-service-oss-access). + +## Audit logging filter rules + +To filter the audit logging, you need to create a filter rule to specify which events to log. The filter rule contains the following fields: @@ -66,90 +123,245 @@ Here is the summary of all event classes in database audit logging: | SELECT | Record all operations of the `SELECT` statements | QUERY | | QUERY_DDL | Record all operations of the DDL statements | QUERY | | AUDIT | Record all operations related to setting TiDB database auditing, including setting system variables and calling system functions | - | -| AUDIT_FUNC_CALL | Record all operations of calling system functions related to TiDB database auditing | AUDIT | +| AUDIT_FUNC_CALL | Record all operations of calling system functions related to TiDB database auditing | AUDIT -### Create a filter rule +## Enable Audit Logging + +You can enable audit logging for a {{{ .essential }}} cluster. + +> **Note:** +> +> Only enabling audit logging will not generate audit logs. You need to configure filters to specify what events to log. For more information, see [Manage audit logging filter rules](#manage-audit-logging-filter-rules). + + +
+ +1. Log in to the [TiDB Cloud console](https://tidbcloud.com/) and navigate to the [**Clusters**](https://tidbcloud.com/project/clusters) page of your project. + + > **Tip:** + > + > You can use the combo box in the upper-left corner to switch between organizations, projects, and clusters. -To create a filter rule that captures all audit logs, run the following command: +2. Click the name of your target cluster to go to its overview page, and then click **Settings** > **DB Audit Logging** in the left navigation pane. + +3. On the **DB Audit Logging** page, click **Enable**. + +4. Select the storage location of the audit logs and fill in the necessary information, then click **Test Connection and Next** or **Next**. For more information about the available storage locations, see [Audit logging locations](#audit-logging-locations). + +5. In the **Database Audit Logging Setting** pop-up, fill the log file rotation and log redaction settings, and then click **Save**. + +
+ +
+ +Take s3 storage as an example. Run the following command to enable audit logging and store the audit logs to Amazon S3: ```shell -ticloud serverless audit-log filter create --cluster-id --name --rule '{"users":["%@%"],"filters":[{}]}' +ticloud serverless audit-log config update -c --enabled --cloud-storage S3 --s3.uri --s3.access-key-id --s3.secret-access-key --rotation-size-mib --rotation-interval-minutes --unredacted= ``` -To create a filter rule that filters ALL EXECUTE events, run the following command: +`--rotation-size-mib`, `--rotation-interval-minutes`, and `--unredacted` are optional parameters. If not specified, the default values will be used. + +
+ + +## Configure audit logging + +You can configure the audit logging for a {{{ .essential }}} cluster after enabling it. + + +
+ +1. Log in to the [TiDB Cloud console](https://tidbcloud.com/) and navigate to the [**Clusters**](https://tidbcloud.com/project/clusters) page of your project. + + > **Tip:** + > + > You can use the combo box in the upper-left corner to switch between organizations, projects, and clusters. + +2. Click the name of your target cluster to go to its overview page, and then click **Settings** > **DB Audit Logging** in the left navigation pane. + +3. On the **DB Audit Logging** page, click **Settings**. + +4. In the **Database Audit Logging Setting** pop-up, fill the log file rotation and log redaction settings, and then click **Save**. + +
+ +
```shell -ticloud serverless audit-log filter create --cluster-id --name --rule '{"users":["%@%"],"filters":[{"classes":["EXECUTE"]]}' +ticloud serverless audit-log config update -c --rotation-size-mib --rotation-interval-minutes --unredacted= ``` + +
+ + +## Disable audit logging + +You can disable audit logging for a {{{ .essential }}} cluster. + + +
+ +1. Log in to the [TiDB Cloud console](https://tidbcloud.com/) and navigate to the [**Clusters**](https://tidbcloud.com/project/clusters) page of your project. + + > **Tip:** + > + > You can use the combo box in the upper-left corner to switch between organizations, projects, and clusters. + +2. Click the name of your target cluster to go to its overview page, and then click **Settings** > **DB Audit Logging** in the left navigation pane. -### Update a filter rule +3. On the **DB Audit Logging** page, click **...** in the upper-right corner, and then click **Disable**. -To disable a filter rule, run the following command: +4. Click **Disable** in the pop-up dialog to disable audit logging. + +
+ +
```shell -ticloud serverless audit-log filter update --cluster-id --name --enabled=false +ticloud serverless audit-log config update -c --disabled=true ``` + +
+ + +## Manage audit logging filter rules + +You can manage audit logging filter rules in the [TiDB Cloud console](https://tidbcloud.com/) or by using the [TiDB Cloud CLI](/tidb-cloud/ticloud-auditlog-config.md). + +### Create a filter rule -To update a filter rule, run the following command: + +
+ +1. Log in to the [TiDB Cloud console](https://tidbcloud.com/) and navigate to the [**Clusters**](https://tidbcloud.com/project/clusters) page of your project. + + > **Tip:** + > + > You can use the combo box in the upper-left corner to switch between organizations, projects, and clusters. + +2. Click the name of your target cluster to go to its overview page, and then click **Settings** > **DB Audit Logging** in the left navigation pane. + +3. On the **DB Audit Logging** page, click **Add Filter Rule**. + +4. Fill in the `Filter Name`, `SQL Users`, and `Filter Rules` fields in the **Add Filter Rule** pop-up dialog, and then click **Confirm**. For more information about the fields, see [Audit logging filter rules](#audit-logging-filter-rules). + +
+ +
```shell -ticloud serverless audit-log filter update --cluster-id --name --rule '{"users":["%@%"],"filters":[{"classes":["QUERY"],"tables":["test.t"]}]}' +ticloud serverless audit-log filter create --cluster-id --display-name --rule '{"users":["%@%"],"filters":[{}]} ``` + +
+ -Note that you need to pass the complete `--rule` field when updating. +### Edit a filter rule -### Delete a filter rule +1. Log in to the [TiDB Cloud console](https://tidbcloud.com/) and navigate to the [**Clusters**](https://tidbcloud.com/project/clusters) page of your project. -To delete a filter rule, run the following command: + > **Tip:** + > + > You can use the combo box in the upper-left corner to switch between organizations, projects, and clusters. + +2. Click the name of your target cluster to go to its overview page, and then click **Settings** > **DB Audit Logging** in the left navigation pane. + +3. On the **DB Audit Logging** page, Choose the filter rule you want to delete and click **...**. + +4. Click **Edit**. + +5. Fill in the `Filter Name`, `SQL Users`, and `Filter Rules` fields in the **Add Filter Rule** pop-up dialog, and then click **Confirm**. + + + +
```shell -ticloud serverless audit-log filter delete --cluster-id --name +ticloud serverless audit-log filter update --cluster-id --filter-rule-id --rule '{"users":["%@%"],"filters":[{"classes":["QUERY"],"tables":["test.t"]}]}' ``` + +
+ -## Configure audit logging +### Disable a filter rule -### Data redaction +1. Log in to the [TiDB Cloud console](https://tidbcloud.com/) and navigate to the [**Clusters**](https://tidbcloud.com/project/clusters) page of your project. -{{{ .starter }}} and {{{ .essential }}} redact sensitive data in the audit logs by default. Take the following SQL statement as an example: + > **Tip:** + > + > You can use the combo box in the upper-left corner to switch between organizations, projects, and clusters. -```sql -INSERT INTO `test`.`users` (`id`, `name`, `password`) VALUES (1, 'Alice', '123456'); -``` +2. Click the name of your target cluster to go to its overview page, and then click **Settings** > **DB Audit Logging** in the left navigation pane. -It is redacted as follows: +3. On the **DB Audit Logging** page, Choose the filter rule you want to disable -```sql -INSERT INTO `test`.`users` (`id`, `name`, `password`) VALUES ( ... ); +4. switch the slider to disable the filter rule. + + + +
+ +```shell +ticloud serverless audit-log filter update --cluster-id --filter-rule-id --enabled=false ``` + +
+ + +### Delete a filter rule + +1. Log in to the [TiDB Cloud console](https://tidbcloud.com/) and navigate to the [**Clusters**](https://tidbcloud.com/project/clusters) page of your project. + + > **Tip:** + > + > You can use the combo box in the upper-left corner to switch between organizations, projects, and clusters. -If you want to disable redaction, use the [TiDB Cloud CLI](/tidb-cloud/ticloud-auditlog-config.md). +2. Click the name of your target cluster to go to its overview page, and then click **Settings** > **DB Audit Logging** in the left navigation pane. + +3. On the **DB Audit Logging** page, Choose the filter rule you want to delete and click **...**. + +4. Click **Delete** and then click **I understand. Delete it** in the pop-up dialog to delete the filter rule. + + + +
```shell -ticloud serverless audit-log config --cluster-id --unredacted +ticloud serverless audit-log filter delete --cluster-id --filter-rule-id ``` + +
+ -### Log file rotation -{{{ .starter }}} and {{{ .essential }}} generate a new audit log file when either of the following conditions is met: +## Access audit logging with TiDB Cloud Storage -- The size of the current log file reaches 100 MiB. -- One hour has passed since the previous log generation. Depending on the internal scheduling mechanism, log generation might be delayed by a few minutes. +{{{ .essential }}} audit logs are stored as readable text files named `YYYY-MM-DD-.log`. When you store audit logs in TiDB Cloud, you can access and download them via the [TiDB Cloud Console](https://tidbcloud.com/) or by using the [TiDB Cloud CLI](/tidb-cloud/ticloud-auditlog-download.md). > **Note:** > -> Currently, Log file rotation settings are not configurable. {{{ .starter }}} and {{{ .essential }}} automatically rotate the audit log files based on the preceding conditions. +> {{{ .essential }}} do not guarantee sequential ordering of audit logs. The log file named `YYYY-MM-DD-.log` might contain the audit logs in previous days. +> If you want to retrieve all logs from a specific date (for example, January 1, 2025), specifying `--start-date 2025-01-01` and `--end-date 2025-01-02` usually works. But under extreme conditions, you might need to download all log files and order them by the `TIME` field. -## Access audit logging + +
-{{{ .starter }}} and {{{ .essential }}} audit logs are stored as readable text files named `YYYY-MM-DD-.log`. +1. Log in to the [TiDB Cloud console](https://tidbcloud.com/) and navigate to the [**Clusters**](https://tidbcloud.com/project/clusters) page of your project. -Currently, audit logs are stored within TiDB Cloud for 365 days. After this period, logs are automatically deleted. + > **Tip:** + > + > You can use the combo box in the upper-left corner to switch between organizations, projects, and clusters. -> **Note:** -> -> Contact [TiDB Cloud Support](https://docs.pingcap.com/tidbcloud/tidb-cloud-support) if you need to save audit logs in external storage (such as Amazon S3, Azure Blob Storage, Google Cloud Storage, and Alibaba Cloud OSS). +2. Click the name of your target cluster to go to its overview page, and then click **Settings** > **DB Audit Logging** in the left navigation pane. -To view and download audit logs, use the [TiDB Cloud CLI](/tidb-cloud/ticloud-auditlog-download.md): +3. On the **DB Audit Logging** page, you can view the list of audit logs under `TiDB Cloud Storage`. + +4. To download an audit log, select the audit logs and then click **Download**. + +
+ +
```shell ticloud serverless audit-log download --cluster-id --output-path --start-date --end-date @@ -157,11 +369,9 @@ ticloud serverless audit-log download --cluster-id --output-path **Note:** -> -> {{{ .starter }}} and {{{ .essential }}} do not guarantee sequential ordering of audit logs. The log file named `YYYY-MM-DD-.log` might contain the audit logs in previous days. -> If you want to retrieve all logs from a specific date (for example, January 1, 2025), specifying `--start-date 2025-01-01` and `--end-date 2025-01-02` usually works. But under extreme conditions, you might need to download all log files and order them by the `TIME` field. + +
+ ## Audit logging fields @@ -227,4 +437,4 @@ When the event class is `AUDIT` or a subclass of `AUDIT`, the audit logs contain - Audit logging is only available via TiDB Cloud CLI at present. - Audit logs can only be stored in TiDB Cloud at present. -- {{{ .starter }}} and {{{ .essential }}} do not guarantee the sequential order of audit logs, which means you might have to review all log files to view the latest events. To sort the logs chronologically, you can use the `TIME` field in the audit logs. +- {{{ .essential }}} do not guarantee the sequential order of audit logs, which means you might have to review all log files to view the latest events. To sort the logs chronologically, you can use the `TIME` field in the audit logs. From f255987aa865b45e1dfc813ffa2b731a5e289ad9 Mon Sep 17 00:00:00 2001 From: shi yuhang <52435083+shiyuhang0@users.noreply.github.com> Date: Mon, 15 Sep 2025 18:33:34 +0800 Subject: [PATCH 02/20] Apply suggestions from code review Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> --- tidb-cloud/serverless-audit-logging.md | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/tidb-cloud/serverless-audit-logging.md b/tidb-cloud/serverless-audit-logging.md index 372db20bc4be8..2ed007644f395 100644 --- a/tidb-cloud/serverless-audit-logging.md +++ b/tidb-cloud/serverless-audit-logging.md @@ -50,7 +50,7 @@ You can store the audit logs to the following locations: ### TiDB Cloud -you can store audit logs in TiDB Cloud and download them to your local machine. The audit logs will be expired and deleted after 365 days. To request longer storage duration, contact [TiDB Cloud Support](/tidb-cloud/tidb-cloud-support.md). +You can store audit logs in TiDB Cloud and download them to your local machine. The audit logs will be expired and deleted after 365 days. To request longer storage duration, contact [TiDB Cloud Support](/tidb-cloud/tidb-cloud-support.md). ### Amazon S3 @@ -68,7 +68,7 @@ For more information, see [Configure Amazon S3 access](/tidb-cloud/serverless-ex To store audit logs to Google Cloud Storage, you need to provide the following information: - URI: `gs:////` -- Access credential: a **base64 encoded** [service account key](https://cloud.google.com/iam/docs/creating-managing-service-account-keys) for your bucket. Make sure the service account key has the `storage.objects.create` and `storage.objects.delete` permission. +- Access credential: a **base64 encoded** [service account key](https://cloud.google.com/iam/docs/creating-managing-service-account-keys) for your bucket. Make sure the service account key has the `storage.objects.create` and `storage.objects.delete` permissions. For more information, see [Configure GCS access](/tidb-cloud/serverless-external-storage.md#configure-gcs-access). @@ -123,7 +123,7 @@ Here is the summary of all event classes in database audit logging: | SELECT | Record all operations of the `SELECT` statements | QUERY | | QUERY_DDL | Record all operations of the DDL statements | QUERY | | AUDIT | Record all operations related to setting TiDB database auditing, including setting system variables and calling system functions | - | -| AUDIT_FUNC_CALL | Record all operations of calling system functions related to TiDB database auditing | AUDIT +| AUDIT_FUNC_CALL | Record all operations of calling system functions related to TiDB database auditing | AUDIT ## Enable Audit Logging @@ -160,7 +160,7 @@ Take s3 storage as an example. Run the following command to enable audit logging ticloud serverless audit-log config update -c --enabled --cloud-storage S3 --s3.uri --s3.access-key-id --s3.secret-access-key --rotation-size-mib --rotation-interval-minutes --unredacted= ``` -`--rotation-size-mib`, `--rotation-interval-minutes`, and `--unredacted` are optional parameters. If not specified, the default values will be used. +`--rotation-size-mib`, `--rotation-interval-minutes`, and `--unredacted` are optional parameters. If you do not specify them, the default values are used. @@ -251,8 +251,7 @@ You can manage audit logging filter rules in the [TiDB Cloud console](https://ti
```shell -ticloud serverless audit-log filter create --cluster-id --display-name --rule '{"users":["%@%"],"filters":[{}]} -``` +ticloud serverless audit-log filter create --cluster-id --display-name --rule '{"users":["%@%"],"filters":[{}]}'
@@ -355,9 +354,9 @@ ticloud serverless audit-log filter delete --cluster-id --filter-ru 2. Click the name of your target cluster to go to its overview page, and then click **Settings** > **DB Audit Logging** in the left navigation pane. -3. On the **DB Audit Logging** page, you can view the list of audit logs under `TiDB Cloud Storage`. +3. On the **DB Audit Logging** page, you can view the list of audit logs under `TiDB Cloud Storage`. -4. To download an audit log, select the audit logs and then click **Download**. +4. To download audit logs, select one or more logs from the list and then click **Download**. From a62a762988214b688fea83be2fc9e86cf6e536f3 Mon Sep 17 00:00:00 2001 From: shiyuhang <1136742008@qq.com> Date: Mon, 15 Sep 2025 18:40:18 +0800 Subject: [PATCH 03/20] fix according to ai --- tidb-cloud/serverless-audit-logging.md | 17 ++++++++++++----- 1 file changed, 12 insertions(+), 5 deletions(-) diff --git a/tidb-cloud/serverless-audit-logging.md b/tidb-cloud/serverless-audit-logging.md index 2ed007644f395..b2642900d46ba 100644 --- a/tidb-cloud/serverless-audit-logging.md +++ b/tidb-cloud/serverless-audit-logging.md @@ -258,6 +258,9 @@ ticloud serverless audit-log filter create --cluster-id --display-n ### Edit a filter rule + +
+ 1. Log in to the [TiDB Cloud console](https://tidbcloud.com/) and navigate to the [**Clusters**](https://tidbcloud.com/project/clusters) page of your project. > **Tip:** @@ -266,11 +269,9 @@ ticloud serverless audit-log filter create --cluster-id --display-n 2. Click the name of your target cluster to go to its overview page, and then click **Settings** > **DB Audit Logging** in the left navigation pane. -3. On the **DB Audit Logging** page, Choose the filter rule you want to delete and click **...**. - -4. Click **Edit**. +3. On the **DB Audit Logging** page, find the filter rule you want to edit, click **...** in its row, and then click **Edit**. -5. Fill in the `Filter Name`, `SQL Users`, and `Filter Rules` fields in the **Add Filter Rule** pop-up dialog, and then click **Confirm**. +4. Fill in the `Filter Name` and `Filter Rules` fields in the **Edit Filter Rule** pop-up dialog, and then click **Confirm**.
@@ -285,6 +286,9 @@ ticloud serverless audit-log filter update --cluster-id --filter-ru ### Disable a filter rule + +
+ 1. Log in to the [TiDB Cloud console](https://tidbcloud.com/) and navigate to the [**Clusters**](https://tidbcloud.com/project/clusters) page of your project. > **Tip:** @@ -293,7 +297,7 @@ ticloud serverless audit-log filter update --cluster-id --filter-ru 2. Click the name of your target cluster to go to its overview page, and then click **Settings** > **DB Audit Logging** in the left navigation pane. -3. On the **DB Audit Logging** page, Choose the filter rule you want to disable +3. On the **DB Audit Logging** page, Choose the filter rule you want to disable. 4. switch the slider to disable the filter rule. @@ -310,6 +314,9 @@ ticloud serverless audit-log filter update --cluster-id --filter-ru ### Delete a filter rule + +
+ 1. Log in to the [TiDB Cloud console](https://tidbcloud.com/) and navigate to the [**Clusters**](https://tidbcloud.com/project/clusters) page of your project. > **Tip:** From ecc3fcf65e8b0e6e89292e3c2d9b6b79f299090e Mon Sep 17 00:00:00 2001 From: shiyuhang <1136742008@qq.com> Date: Mon, 15 Sep 2025 18:48:55 +0800 Subject: [PATCH 04/20] fix lint --- tidb-cloud/serverless-audit-logging.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/tidb-cloud/serverless-audit-logging.md b/tidb-cloud/serverless-audit-logging.md index b2642900d46ba..3fcf7f7ed8230 100644 --- a/tidb-cloud/serverless-audit-logging.md +++ b/tidb-cloud/serverless-audit-logging.md @@ -125,7 +125,9 @@ Here is the summary of all event classes in database audit logging: | AUDIT | Record all operations related to setting TiDB database auditing, including setting system variables and calling system functions | - | | AUDIT_FUNC_CALL | Record all operations of calling system functions related to TiDB database auditing | AUDIT -## Enable Audit Logging +## Configure audit logging + +### Enable audit logging You can enable audit logging for a {{{ .essential }}} cluster. @@ -165,9 +167,9 @@ ticloud serverless audit-log config update -c --enabled --cloud-sto
-## Configure audit logging +### Edit audit logging -You can configure the audit logging for a {{{ .essential }}} cluster after enabling it. +You can Edit the audit logging for a {{{ .essential }}} cluster after enabling it.
@@ -195,7 +197,7 @@ ticloud serverless audit-log config update -c --rotation-size-mib <
-## Disable audit logging +### Disable audit logging You can disable audit logging for a {{{ .essential }}} cluster. @@ -252,6 +254,7 @@ You can manage audit logging filter rules in the [TiDB Cloud console](https://ti ```shell ticloud serverless audit-log filter create --cluster-id --display-name --rule '{"users":["%@%"],"filters":[{}]}' +```
@@ -340,10 +343,9 @@ ticloud serverless audit-log filter delete --cluster-id --filter-ru - ## Access audit logging with TiDB Cloud Storage -{{{ .essential }}} audit logs are stored as readable text files named `YYYY-MM-DD-.log`. When you store audit logs in TiDB Cloud, you can access and download them via the [TiDB Cloud Console](https://tidbcloud.com/) or by using the [TiDB Cloud CLI](/tidb-cloud/ticloud-auditlog-download.md). +{{{ .essential }}} audit logs are stored as readable text files named `YYYY-MM-DD-.log`. When you store audit logs in TiDB Cloud, you can access and download them. > **Note:** > From 7e433800227ffa5944ea23340bd1a96c85f35d62 Mon Sep 17 00:00:00 2001 From: shi yuhang <52435083+shiyuhang0@users.noreply.github.com> Date: Mon, 15 Sep 2025 18:50:03 +0800 Subject: [PATCH 05/20] Apply suggestions from code review Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- tidb-cloud/serverless-audit-logging.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/tidb-cloud/serverless-audit-logging.md b/tidb-cloud/serverless-audit-logging.md index 3fcf7f7ed8230..675e8d25373d4 100644 --- a/tidb-cloud/serverless-audit-logging.md +++ b/tidb-cloud/serverless-audit-logging.md @@ -123,7 +123,7 @@ Here is the summary of all event classes in database audit logging: | SELECT | Record all operations of the `SELECT` statements | QUERY | | QUERY_DDL | Record all operations of the DDL statements | QUERY | | AUDIT | Record all operations related to setting TiDB database auditing, including setting system variables and calling system functions | - | -| AUDIT_FUNC_CALL | Record all operations of calling system functions related to TiDB database auditing | AUDIT +| AUDIT_FUNC_CALL | Record all operations of calling system functions related to TiDB database auditing | AUDIT | ## Configure audit logging @@ -300,7 +300,7 @@ ticloud serverless audit-log filter update --cluster-id --filter-ru 2. Click the name of your target cluster to go to its overview page, and then click **Settings** > **DB Audit Logging** in the left navigation pane. -3. On the **DB Audit Logging** page, Choose the filter rule you want to disable. +3. On the **DB Audit Logging** page, choose the filter rule you want to disable. 4. switch the slider to disable the filter rule. @@ -328,7 +328,7 @@ ticloud serverless audit-log filter update --cluster-id --filter-ru 2. Click the name of your target cluster to go to its overview page, and then click **Settings** > **DB Audit Logging** in the left navigation pane. -3. On the **DB Audit Logging** page, Choose the filter rule you want to delete and click **...**. +3. On the **DB Audit Logging** page, choose the filter rule you want to delete and click **...**. 4. Click **Delete** and then click **I understand. Delete it** in the pop-up dialog to delete the filter rule. From 9b5876a7818ec0abcd58d779ab5700f904b6a963 Mon Sep 17 00:00:00 2001 From: shiyuhang <1136742008@qq.com> Date: Mon, 15 Sep 2025 18:53:08 +0800 Subject: [PATCH 06/20] remove some limit --- tidb-cloud/serverless-audit-logging.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/tidb-cloud/serverless-audit-logging.md b/tidb-cloud/serverless-audit-logging.md index 675e8d25373d4..e92312106f951 100644 --- a/tidb-cloud/serverless-audit-logging.md +++ b/tidb-cloud/serverless-audit-logging.md @@ -443,6 +443,4 @@ When the event class is `AUDIT` or a subclass of `AUDIT`, the audit logs contain ## Audit logging limitations -- Audit logging is only available via TiDB Cloud CLI at present. -- Audit logs can only be stored in TiDB Cloud at present. -- {{{ .essential }}} do not guarantee the sequential order of audit logs, which means you might have to review all log files to view the latest events. To sort the logs chronologically, you can use the `TIME` field in the audit logs. +- Do not guarantee the sequential order of audit logs, which means you might have to review all log files to view the latest events. To sort the logs chronologically, you can use the `TIME` field in the audit logs. From 6d8f2e50fe45865eb811804d22b731111f219305 Mon Sep 17 00:00:00 2001 From: shiyuhang <1136742008@qq.com> Date: Tue, 16 Sep 2025 14:29:12 +0800 Subject: [PATCH 07/20] opts all --- TOC-tidb-cloud-essential.md | 1 + ...s-audit-logging.md => serverless-database-audit-logging.md} | 3 +-- 2 files changed, 2 insertions(+), 2 deletions(-) rename tidb-cloud/{serverless-audit-logging.md => serverless-database-audit-logging.md} (99%) diff --git a/TOC-tidb-cloud-essential.md b/TOC-tidb-cloud-essential.md index 83664bac8e801..fbb4c5e6f1518 100644 --- a/TOC-tidb-cloud-essential.md +++ b/TOC-tidb-cloud-essential.md @@ -266,6 +266,7 @@ - [TLS Connections to TiDB Cloud](/tidb-cloud/secure-connections-to-serverless-clusters.md) - Audit Management - [Console Audit Logging](/tidb-cloud/tidb-cloud-console-auditing.md) + - [Database Audit Logging](/tidb-cloud/serverless-database-audit-logging.md) - Billing - [Invoices](/tidb-cloud/tidb-cloud-billing.md#invoices) - [Billing Details](/tidb-cloud/tidb-cloud-billing.md#billing-details) diff --git a/tidb-cloud/serverless-audit-logging.md b/tidb-cloud/serverless-database-audit-logging.md similarity index 99% rename from tidb-cloud/serverless-audit-logging.md rename to tidb-cloud/serverless-database-audit-logging.md index e92312106f951..3476fc5f54270 100644 --- a/tidb-cloud/serverless-audit-logging.md +++ b/tidb-cloud/serverless-database-audit-logging.md @@ -1,6 +1,7 @@ --- title: Database Audit Logging for {{{ .essential }}} summary: Learn about how to audit a {{{ .essential }}} cluster in TiDB Cloud. +aliases: ['/tidbcloud/serverless-audit-logging'] --- # Database Audit Logging (Beta) for {{{ .essential }}} @@ -229,8 +230,6 @@ ticloud serverless audit-log config update -c --disabled=true ## Manage audit logging filter rules -You can manage audit logging filter rules in the [TiDB Cloud console](https://tidbcloud.com/) or by using the [TiDB Cloud CLI](/tidb-cloud/ticloud-auditlog-config.md). - ### Create a filter rule From 4bdd0807a9597b63653f612c1fe28d9b36c646ff Mon Sep 17 00:00:00 2001 From: shi yuhang <52435083+shiyuhang0@users.noreply.github.com> Date: Tue, 16 Sep 2025 14:38:24 +0800 Subject: [PATCH 08/20] Apply suggestions from code review Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> --- .../serverless-database-audit-logging.md | 26 +++++++++---------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/tidb-cloud/serverless-database-audit-logging.md b/tidb-cloud/serverless-database-audit-logging.md index 3476fc5f54270..b69df4ce0b79b 100644 --- a/tidb-cloud/serverless-database-audit-logging.md +++ b/tidb-cloud/serverless-database-audit-logging.md @@ -6,7 +6,7 @@ aliases: ['/tidbcloud/serverless-audit-logging'] # Database Audit Logging (Beta) for {{{ .essential }}} -{{{ .essential }}} provide you with a database audit logging feature to record a history of user access details (such as any SQL statements executed) in logs. +{{{ .essential }}} provides you with a database audit logging feature to record a history of user access details (such as any SQL statements executed) in logs. > **Note:** > @@ -20,7 +20,7 @@ The audit logging feature is disabled by default. To audit a cluster, you need t ### Data redaction -{{{ .essential }}} redact sensitive data in the audit logs by default. Take the following SQL statement as an example: +{{{ .essential }}} redacts sensitive data in the audit logs by default. Take the following SQL statement as an example: ```sql INSERT INTO `test`.`users` (`id`, `name`, `password`) VALUES (1, 'Alice', '123456'); @@ -34,14 +34,14 @@ INSERT INTO `test`.`users` (`id`, `name`, `password`) VALUES ( ... ); ### Log file rotation -{{{ .essential }}} generate a new audit log file when either of the following conditions is met: +{{{ .essential }}} generates a new audit log file when either of the following conditions is met: - The size of the current log file reaches rotation size (100 MB by default). - Rotation interval (one hour by default) has passed since the previous log generation. Depending on the internal scheduling mechanism, log generation might be delayed by a few minutes. ## Audit logging locations -You can store the audit logs to the following locations: +You can store the audit logs in the following locations: - TiDB Cloud - [Amazon S3](https://aws.amazon.com/s3/) @@ -51,7 +51,7 @@ You can store the audit logs to the following locations: ### TiDB Cloud -You can store audit logs in TiDB Cloud and download them to your local machine. The audit logs will be expired and deleted after 365 days. To request longer storage duration, contact [TiDB Cloud Support](/tidb-cloud/tidb-cloud-support.md). +You can store audit logs in TiDB Cloud and download them to your local machine. The audit logs expire and are deleted after 365 days. To request longer storage duration, contact [TiDB Cloud Support](/tidb-cloud/tidb-cloud-support.md). ### Amazon S3 @@ -59,8 +59,8 @@ To store audit logs to Amazon S3, you need to provide the following information: - URI: `s3:////` - One of the following access credentials: - - [An access key](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html): make sure the access key has the `s3:PutObject` and `s3:ListBucket` permissions. - - [A role ARN](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference-arns.html): make sure the role ARN (Amazon Resource Name) has the `s3:PutObject` permissions. Note that only clusters hosted on AWS support the role ARN. + - [An access key](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html): Make sure the access key has the `s3:PutObject` and `s3:ListBucket` permissions. + - [A role ARN](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference-arns.html): Make sure the role ARN (Amazon Resource Name) has the `s3:PutObject` permissions. Note that only clusters hosted on AWS support the role ARN. For more information, see [Configure Amazon S3 access](/tidb-cloud/serverless-external-storage.md#configure-amazon-s3-access). @@ -93,7 +93,7 @@ For more information, see [Configure Alibaba Cloud Object Storage Service (OSS) ## Audit logging filter rules -To filter the audit logging, you need to create a filter rule to specify which events to log. +To filter audit logs, you need to create a filter rule to specify which events to log. The filter rule contains the following fields: @@ -124,7 +124,7 @@ Here is the summary of all event classes in database audit logging: | SELECT | Record all operations of the `SELECT` statements | QUERY | | QUERY_DDL | Record all operations of the DDL statements | QUERY | | AUDIT | Record all operations related to setting TiDB database auditing, including setting system variables and calling system functions | - | -| AUDIT_FUNC_CALL | Record all operations of calling system functions related to TiDB database auditing | AUDIT | +| AUDIT_FUNC_CALL | Record all operations of calling system functions related to TiDB database auditing | AUDIT | ## Configure audit logging @@ -151,13 +151,13 @@ You can enable audit logging for a {{{ .essential }}} cluster. 4. Select the storage location of the audit logs and fill in the necessary information, then click **Test Connection and Next** or **Next**. For more information about the available storage locations, see [Audit logging locations](#audit-logging-locations). -5. In the **Database Audit Logging Setting** pop-up, fill the log file rotation and log redaction settings, and then click **Save**. +5. In the **Database Audit Logging Setting** pop-up, fill in the log file rotation and log redaction settings, and then click **Save**.
-Take s3 storage as an example. Run the following command to enable audit logging and store the audit logs to Amazon S3: +Take Amazon S3 storage as an example. Run the following command to enable audit logging and store the audit logs to Amazon S3: ```shell ticloud serverless audit-log config update -c --enabled --cloud-storage S3 --s3.uri --s3.access-key-id --s3.secret-access-key --rotation-size-mib --rotation-interval-minutes --unredacted= @@ -170,7 +170,7 @@ ticloud serverless audit-log config update -c --enabled --cloud-sto ### Edit audit logging -You can Edit the audit logging for a {{{ .essential }}} cluster after enabling it. +You can edit the audit logging for a {{{ .essential }}} cluster after enabling it.
@@ -442,4 +442,4 @@ When the event class is `AUDIT` or a subclass of `AUDIT`, the audit logs contain ## Audit logging limitations -- Do not guarantee the sequential order of audit logs, which means you might have to review all log files to view the latest events. To sort the logs chronologically, you can use the `TIME` field in the audit logs. +- {{{ .essential }}} does not guarantee the sequential order of audit logs, which means you might have to review all log files to view the latest events. To sort the logs chronologically, you can use the `TIME` field in the audit logs. From 6fce4f53e373c78e188a7e9e89cf769733715d93 Mon Sep 17 00:00:00 2001 From: shi yuhang <52435083+shiyuhang0@users.noreply.github.com> Date: Tue, 16 Sep 2025 14:41:29 +0800 Subject: [PATCH 09/20] Update tidb-cloud/serverless-database-audit-logging.md Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> --- tidb-cloud/serverless-database-audit-logging.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tidb-cloud/serverless-database-audit-logging.md b/tidb-cloud/serverless-database-audit-logging.md index b69df4ce0b79b..7cc3726de7188 100644 --- a/tidb-cloud/serverless-database-audit-logging.md +++ b/tidb-cloud/serverless-database-audit-logging.md @@ -344,7 +344,7 @@ ticloud serverless audit-log filter delete --cluster-id --filter-ru ## Access audit logging with TiDB Cloud Storage -{{{ .essential }}} audit logs are stored as readable text files named `YYYY-MM-DD-.log`. When you store audit logs in TiDB Cloud, you can access and download them. +When you store audit logs in TiDB Cloud, {{{ .essential }}} stores them as readable text files named `YYYY-MM-DD-.log`, which you can access and download. > **Note:** > From af9044678435a711a37dc407172ed4aa124a9aab Mon Sep 17 00:00:00 2001 From: shiyuhang <1136742008@qq.com> Date: Tue, 16 Sep 2025 14:42:42 +0800 Subject: [PATCH 10/20] fix according to ai --- tidb-cloud/serverless-database-audit-logging.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/tidb-cloud/serverless-database-audit-logging.md b/tidb-cloud/serverless-database-audit-logging.md index 7cc3726de7188..d5c0e78e90e46 100644 --- a/tidb-cloud/serverless-database-audit-logging.md +++ b/tidb-cloud/serverless-database-audit-logging.md @@ -101,7 +101,7 @@ The filter rule contains the following fields: - `filters`: A list of filter objects. Each filter object can contain the following fields: - `classes`: A list of event classes to filter audit events. For example, `["QUERY", "EXECUTE"]`. - - `tables`: A list of table filters. For more information, see [Table filters]. + - `tables`: A list of table filters. For more information, see [Table filter](https://docs.pingcap.com/tidb/stable/table-filter/). - `statusCodes`: A list of status codes to filter audit events. `1` means success, `0` means failure. Here is the summary of all event classes in database audit logging: @@ -400,7 +400,7 @@ All classes of audit logs contain the following information: | STATUS_CODE | The status code of the audit record. `1` means success, and `0` means failure. | | KEYSPACE_NAME | The keyspace name of the audit record. | | SERVERLESS_TENANT_ID | The ID of the serverless tenant that the cluster belongs to. | -| SERVERLESS_TSERVERLESS_PROJECT_ID | The ID of the serverless project that the cluster belongs to. | +| SERVERLESS_PROJECT_ID | The ID of the serverless project that the cluster belongs to. | | SERVERLESS_CLUSTER_ID | The ID of the serverless cluster that the audit record belongs to. | | REASON | The error message of the audit record. Only recorded when an error occurs during the operation. | From c98012dbd04049e9ff070ac4154643c486be900b Mon Sep 17 00:00:00 2001 From: houfaxin Date: Thu, 18 Sep 2025 10:34:57 +0800 Subject: [PATCH 11/20] Update serverless-database-audit-logging.md --- .../serverless-database-audit-logging.md | 166 +++++++++--------- 1 file changed, 86 insertions(+), 80 deletions(-) diff --git a/tidb-cloud/serverless-database-audit-logging.md b/tidb-cloud/serverless-database-audit-logging.md index d5c0e78e90e46..510e3abc84149 100644 --- a/tidb-cloud/serverless-database-audit-logging.md +++ b/tidb-cloud/serverless-database-audit-logging.md @@ -98,36 +98,38 @@ To filter audit logs, you need to create a filter rule to specify which events t The filter rule contains the following fields: - `users`: A list of user names to filter audit events. You can use the wildcard `%` to match any user name. -- `filters`: A list of filter objects. Each filter object can contain the following fields: +- `filters`: A list of filter objects. Each filter object contains the following fields: - `classes`: A list of event classes to filter audit events. For example, `["QUERY", "EXECUTE"]`. - - `tables`: A list of table filters. For more information, see [Table filter](https://docs.pingcap.com/tidb/stable/table-filter/). - - `statusCodes`: A list of status codes to filter audit events. `1` means success, `0` means failure. + - `tables`: A list of table filters. For more information, see [Table Filter](https://docs.pingcap.com/tidb/stable/table-filter/). + - `statusCodes`: A list of status codes to filter audit events. `1` means success, and `0` means failure. -Here is the summary of all event classes in database audit logging: +The following tables shows all event classes in database audit logging: | Event Class | Description | Parent-class | |---------------|--------------------------------------------------------------------------------------------------|---------------| -| CONNECTION | Record all operations related to connections, such as handshaking, connections, disconnections, connection reset, and changing users | - | -| CONNECT | Record all operations of the handshaking in connections | CONNECTION | -| DISCONNECT | Record all operations of the disconnections | CONNECTION | -| CHANGE_USER | Record all operations of changing users | CONNECTION | -| QUERY | Record all operations of SQL statements, including all errors about querying and modifying data | - | -| TRANSACTION | Record all operations related to transactions, such as `BEGIN`, `COMMIT`, and `ROLLBACK` | QUERY | -| EXECUTE | Record all operations of the `EXECUTE` statements | QUERY | -| QUERY_DML | Record all operations of the DML statements, including `INSERT`, `REPLACE`, `UPDATE`, `DELETE`, and `LOAD DATA` | QUERY | -| INSERT | Record all operations of the `INSERT` statements | QUERY_DML | -| REPLACE | Record all operations of the `REPLACE` statements | QUERY_DML | -| UPDATE | Record all operations of the `UPDATE` statements | QUERY_DML | -| DELETE | Record all operations of the `DELETE` statements | QUERY_DML | -| LOAD DATA | Record all operations of the `LOAD DATA` statements | QUERY_DML | -| SELECT | Record all operations of the `SELECT` statements | QUERY | -| QUERY_DDL | Record all operations of the DDL statements | QUERY | -| AUDIT | Record all operations related to setting TiDB database auditing, including setting system variables and calling system functions | - | -| AUDIT_FUNC_CALL | Record all operations of calling system functions related to TiDB database auditing | AUDIT | +| `CONNECTION` | Records all operations related to connections, such as handshaking, connections, disconnections, connection reset, and changing users | - | +| `CONNECT` | Records all operations of the handshaking in connections | `CONNECTION` | +| `DISCONNECT` | Records all operations of the disconnections | `CONNECTION` | +| `CHANGE_USER` | Records all operations of changing users | `CONNECTION` | +| `QUERY` | Records all operations of SQL statements, including all errors about querying and modifying data | - | +| `TRANSACTION` | Records all operations related to transactions, such as `BEGIN`, `COMMIT`, and `ROLLBACK` | `QUERY` | +| `EXECUTE` | Records all operations of the `EXECUTE` statements | `QUERY` | +| `QUERY_DML` | Records all operations of the DML statements, including `INSERT`, `REPLACE`, `UPDATE`, `DELETE`, and `LOAD DATA` | `QUERY` | +| `INSERT` | Records all operations of the `INSERT` statements | `QUERY_DML` | +| `REPLACE` | Records all operations of the `REPLACE` statements | `QUERY_DML` | +| `UPDATE` | Records all operations of the `UPDATE` statements | `QUERY_DML` | +| `DELETE` | Records all operations of the `DELETE` statements | `QUERY_DML` | +| `LOAD DATA` | Records all operations of the `LOAD DATA` statements | `QUERY_DML` | +| `SELECT` | Records all operations of the `SELECT` statements | `QUERY` | +| `QUERY_DDL` | Records all operations of the DDL statements | `QUERY` | +| `AUDIT` | Records all operations related to setting TiDB database auditing, including setting system variables and calling system functions | - | +| `AUDIT_FUNC_CALL` | Records all operations of calling system functions related to TiDB Cloud database auditing | `AUDIT` | ## Configure audit logging +You can enable, edit, and disable audit logging. + ### Enable audit logging You can enable audit logging for a {{{ .essential }}} cluster. @@ -151,7 +153,7 @@ You can enable audit logging for a {{{ .essential }}} cluster. 4. Select the storage location of the audit logs and fill in the necessary information, then click **Test Connection and Next** or **Next**. For more information about the available storage locations, see [Audit logging locations](#audit-logging-locations). -5. In the **Database Audit Logging Setting** pop-up, fill in the log file rotation and log redaction settings, and then click **Save**. +5. In the **Database Audit Logging Setting** dialog box, fill in the log file rotation and log redaction settings, and then click **Save**.
@@ -177,15 +179,15 @@ You can edit the audit logging for a {{{ .essential }}} cluster after enabling i 1. Log in to the [TiDB Cloud console](https://tidbcloud.com/) and navigate to the [**Clusters**](https://tidbcloud.com/project/clusters) page of your project. - > **Tip:** - > - > You can use the combo box in the upper-left corner to switch between organizations, projects, and clusters. + > **Tip:** + > + > You can use the combo box in the upper-left corner to switch between organizations, projects, and clusters. 2. Click the name of your target cluster to go to its overview page, and then click **Settings** > **DB Audit Logging** in the left navigation pane. 3. On the **DB Audit Logging** page, click **Settings**. -4. In the **Database Audit Logging Setting** pop-up, fill the log file rotation and log redaction settings, and then click **Save**. +4. In the **Database Audit Logging Setting** dialog box, fill the log file rotation and log redaction settings, and then click **Save**.
@@ -207,15 +209,15 @@ You can disable audit logging for a {{{ .essential }}} cluster. 1. Log in to the [TiDB Cloud console](https://tidbcloud.com/) and navigate to the [**Clusters**](https://tidbcloud.com/project/clusters) page of your project. - > **Tip:** - > - > You can use the combo box in the upper-left corner to switch between organizations, projects, and clusters. + > **Tip:** + > + > You can use the combo box in the upper-left corner to switch between organizations, projects, and clusters. 2. Click the name of your target cluster to go to its overview page, and then click **Settings** > **DB Audit Logging** in the left navigation pane. 3. On the **DB Audit Logging** page, click **...** in the upper-right corner, and then click **Disable**. -4. Click **Disable** in the pop-up dialog to disable audit logging. +4. Click **Disable** in the dialog box to disable audit logging. @@ -230,8 +232,12 @@ ticloud serverless audit-log config update -c --disabled=true ## Manage audit logging filter rules +You can create, edit, disable, and delete a filter rule. + ### Create a filter rule +To create a filter rule, define which users and events you want to capture in the audit logs. You can specify users, event classes, tables, and status codes to tailor the logging to your needs. +
@@ -245,7 +251,7 @@ ticloud serverless audit-log config update -c --disabled=true 3. On the **DB Audit Logging** page, click **Add Filter Rule**. -4. Fill in the `Filter Name`, `SQL Users`, and `Filter Rules` fields in the **Add Filter Rule** pop-up dialog, and then click **Confirm**. For more information about the fields, see [Audit logging filter rules](#audit-logging-filter-rules). +4. Fill in the `Filter Name`, `SQL Users`, and `Filter Rules` fields in the **Add Filter Rule** dialog box, and then click **Confirm**. For more information about the fields, see [Audit logging filter rules](#audit-logging-filter-rules).
@@ -265,15 +271,15 @@ ticloud serverless audit-log filter create --cluster-id --display-n 1. Log in to the [TiDB Cloud console](https://tidbcloud.com/) and navigate to the [**Clusters**](https://tidbcloud.com/project/clusters) page of your project. - > **Tip:** - > - > You can use the combo box in the upper-left corner to switch between organizations, projects, and clusters. + > **Tip:** + > + > You can use the combo box in the upper-left corner to switch between organizations, projects, and clusters. 2. Click the name of your target cluster to go to its overview page, and then click **Settings** > **DB Audit Logging** in the left navigation pane. 3. On the **DB Audit Logging** page, find the filter rule you want to edit, click **...** in its row, and then click **Edit**. -4. Fill in the `Filter Name` and `Filter Rules` fields in the **Edit Filter Rule** pop-up dialog, and then click **Confirm**. +4. Fill in the `Filter Name` and `Filter Rules` fields in the **Edit Filter Rule** dialog box, and then click **Confirm**. @@ -293,15 +299,15 @@ ticloud serverless audit-log filter update --cluster-id --filter-ru 1. Log in to the [TiDB Cloud console](https://tidbcloud.com/) and navigate to the [**Clusters**](https://tidbcloud.com/project/clusters) page of your project. - > **Tip:** - > - > You can use the combo box in the upper-left corner to switch between organizations, projects, and clusters. + > **Tip:** + > + > You can use the combo box in the upper-left corner to switch between organizations, projects, and clusters. 2. Click the name of your target cluster to go to its overview page, and then click **Settings** > **DB Audit Logging** in the left navigation pane. -3. On the **DB Audit Logging** page, choose the filter rule you want to disable. +3. On the **DB Audit Logging** page, choose the filter rule that you want to disable. -4. switch the slider to disable the filter rule. +4. Turn off the slider to disable the filter rule. @@ -321,15 +327,15 @@ ticloud serverless audit-log filter update --cluster-id --filter-ru 1. Log in to the [TiDB Cloud console](https://tidbcloud.com/) and navigate to the [**Clusters**](https://tidbcloud.com/project/clusters) page of your project. - > **Tip:** - > - > You can use the combo box in the upper-left corner to switch between organizations, projects, and clusters. + > **Tip:** + > + > You can use the combo box in the upper-left corner to switch between organizations, projects, and clusters. 2. Click the name of your target cluster to go to its overview page, and then click **Settings** > **DB Audit Logging** in the left navigation pane. 3. On the **DB Audit Logging** page, choose the filter rule you want to delete and click **...**. -4. Click **Delete** and then click **I understand. Delete it** in the pop-up dialog to delete the filter rule. +4. Click **Delete** and then click **I understand. Delete it** in the dialog box to delete the filter rule. @@ -348,7 +354,7 @@ When you store audit logs in TiDB Cloud, {{{ .essential }}} stores them as reada > **Note:** > -> {{{ .essential }}} do not guarantee sequential ordering of audit logs. The log file named `YYYY-MM-DD-.log` might contain the audit logs in previous days. +> {{{ .essential }}} does not guarantee sequential ordering of audit logs. The log file named `YYYY-MM-DD-.log` might contain the audit logs in previous days. > If you want to retrieve all logs from a specific date (for example, January 1, 2025), specifying `--start-date 2025-01-01` and `--end-date 2025-01-02` usually works. But under extreme conditions, you might need to download all log files and order them by the `TIME` field. @@ -356,9 +362,9 @@ When you store audit logs in TiDB Cloud, {{{ .essential }}} stores them as reada 1. Log in to the [TiDB Cloud console](https://tidbcloud.com/) and navigate to the [**Clusters**](https://tidbcloud.com/project/clusters) page of your project. - > **Tip:** - > - > You can use the combo box in the upper-left corner to switch between organizations, projects, and clusters. + > **Tip:** + > + > You can use the combo box in the upper-left corner to switch between organizations, projects, and clusters. 2. Click the name of your target cluster to go to its overview page, and then click **Settings** > **DB Audit Logging** in the left navigation pane. @@ -374,15 +380,15 @@ When you store audit logs in TiDB Cloud, {{{ .essential }}} stores them as reada ticloud serverless audit-log download --cluster-id --output-path --start-date --end-date ``` -- `start-date`: The start date of the audit log you want to download in the format of `YYYY-MM-DD`, for example `2025-01-01`. -- `end-date`: The end date of the audit log you want to download in the format of `YYYY-MM-DD`, for example `2025-01-01`. +- `start-date`: The start date of the audit log that you want to download in the format of `YYYY-MM-DD`, for example `2025-01-01`. +- `end-date`: The end date of the audit log that you want to download in the format of `YYYY-MM-DD`, for example `2025-01-01`. ## Audit logging fields -For each database event record in audit logs, TiDB provides the following fields: +For each database event record in audit logs, TiDB Cloud provides the following fields: ### General information @@ -390,19 +396,19 @@ All classes of audit logs contain the following information: | Field | Description | |---------------|-----------------------------------------------------------------------------------------------| -| ID | The unique identifier that identifies the audit record of an operation | -| TIME | The timestamp of the audit record | -| EVENT | The event classes of the audit record. Multiple event types are separated by commas (`,`) | -| USER | The username of the audit record | -| ROLES | The roles of the user at the time of the operation | -| CONNECTION_ID | The identifier of the user's connection | -| TABLES | The accessed tables related to this audit record | -| STATUS_CODE | The status code of the audit record. `1` means success, and `0` means failure. | -| KEYSPACE_NAME | The keyspace name of the audit record. | -| SERVERLESS_TENANT_ID | The ID of the serverless tenant that the cluster belongs to. | -| SERVERLESS_PROJECT_ID | The ID of the serverless project that the cluster belongs to. | -| SERVERLESS_CLUSTER_ID | The ID of the serverless cluster that the audit record belongs to. | -| REASON | The error message of the audit record. Only recorded when an error occurs during the operation. | +| `ID` | The unique identifier that identifies the audit record of an operation | +| `TIME` | The timestamp of the audit record | +| `EVENT` | The event classes of the audit record. Multiple event types are separated by commas (`,`) | +| `USER` | The username of the audit record | +| `ROLES` | The roles of the user at the time of the operation | +| `CONNECTION_ID` | The identifier of the user's connection | +| `TABLES` | The accessed tables related to this audit record | +| `STATUS_CODE` | The status code of the audit record. `1` means success, and `0` means failure. | +| `KEYSPACE_NAME` | The keyspace name of the audit record. | +| `SERVERLESS_TENANT_ID` | The ID of the serverless tenant that the cluster belongs to. | +| `SERVERLESS_PROJECT_ID` | The ID of the serverless project that the cluster belongs to. | +| `SERVERLESS_CLUSTER_ID` | The ID of the serverless cluster that the audit record belongs to. | +| `REASON` | The error message of the audit record. Only recorded when an error occurs during the operation.| ### SQL statement information @@ -410,10 +416,10 @@ When the event class is `QUERY` or a subclass of `QUERY`, the audit logs contain | Field | Description | |----------------|---------------------------------------------------------------------------------------------------------------| -| CURRENT_DB | The name of the current database. | -| SQL_TEXT | The executed SQL statements. If audit log redaction is enabled, the redacted SQL statements are recorded. | -| EXECUTE_PARAMS | The parameters for the `EXECUTE` statements. Recorded only when the event classes include `EXECUTE` and redaction is disabled. | -| AFFECTED_ROWS | The number of affected rows of the SQL statements. Recorded only when the event classes include `QUERY_DML`. | +| `CURRENT_DB` | The name of the current database. | +| `SQL_TEXT` | The executed SQL statements. If audit log redaction is enabled, the redacted SQL statements are recorded. | +| `EXECUTE_PARAMS` | The parameters for the `EXECUTE` statements. Recorded only when the event classes include `EXECUTE` and redaction is disabled. | +| `AFFECTED_ROWS` | The number of affected rows of the SQL statements. Recorded only when the event classes include `QUERY_DML`. | ### Connection information @@ -421,15 +427,15 @@ When the event class is `CONNECTION` or a subclass of `CONNECTION`, the audit lo | Field | Description | |-----------------|-----------------------------------------------------------------------------------------------| -| CURRENT_DB | The name of the current database. When the event classes include DISCONNECT, this information is not recorded. | -| CONNECTION_TYPE | The type of connection, including Socket, UnixSocket, and SSL/TLS. | -| PID | The process ID of the current connection. | -| SERVER_VERSION | The current version of the connected TiDB server. | -| SSL_VERSION | The current version of SSL in use. | -| HOST_IP | The current IP address of the connected TiDB server. | -| HOST_PORT | The current port of the connected TiDB server. | -| CLIENT_IP | The current IP address of the client. | -| CLIENT_PORT | The current port of the client. | +| `CURRENT_DB` | The name of the current database. When the event classes include DISCONNECT, this information is not recorded. | +| `CONNECTION_TYPE` | The type of connection, including Socket, UnixSocket, and SSL/TLS. | +| `PID` | The process ID of the current connection. | +| `SERVER_VERSION` | The current version of the connected TiDB server. | +| `SSL_VERSION` | The current version of SSL in use. | +| `HOST_IP` | The current IP address of the connected TiDB server. | +| `HOST_PORT` | The current port of the connected TiDB server. | +| `CLIENT_IP` | The current IP address of the client. | +| `CLIENT_PORT` | The current port of the client. | ### Audit operation information @@ -437,9 +443,9 @@ When the event class is `AUDIT` or a subclass of `AUDIT`, the audit logs contain | Field | Description | |----------------|---------------------------------------------------------------------------------------------------------------| -| AUDIT_OP_TARGET| The objects of the setting related to TiDB database auditing. | -| AUDIT_OP_ARGS | The arguments of the setting related to TiDB database auditing. | +| `AUDIT_OP_TARGET`| The objects of the setting related to TiDB Cloud database auditing. | +| `AUDIT_OP_ARGS` | The arguments of the setting related to TiDB Cloud database auditing. | ## Audit logging limitations -- {{{ .essential }}} does not guarantee the sequential order of audit logs, which means you might have to review all log files to view the latest events. To sort the logs chronologically, you can use the `TIME` field in the audit logs. +{{{ .essential }}} does not guarantee the sequential order of audit logs, which means that you might have to review all log files to view the latest events. To sort the logs chronologically, you can use the `TIME` field in the audit logs. From 509f5dd2408097e7251b6fca3a17189aa4c6c11f Mon Sep 17 00:00:00 2001 From: houfaxin Date: Thu, 18 Sep 2025 14:01:48 +0800 Subject: [PATCH 12/20] Update serverless-database-audit-logging.md --- tidb-cloud/serverless-database-audit-logging.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tidb-cloud/serverless-database-audit-logging.md b/tidb-cloud/serverless-database-audit-logging.md index 510e3abc84149..fdef8f63867df 100644 --- a/tidb-cloud/serverless-database-audit-logging.md +++ b/tidb-cloud/serverless-database-audit-logging.md @@ -104,7 +104,7 @@ The filter rule contains the following fields: - `tables`: A list of table filters. For more information, see [Table Filter](https://docs.pingcap.com/tidb/stable/table-filter/). - `statusCodes`: A list of status codes to filter audit events. `1` means success, and `0` means failure. -The following tables shows all event classes in database audit logging: +The following table shows all event classes in database audit logging: | Event Class | Description | Parent-class | |---------------|--------------------------------------------------------------------------------------------------|---------------| From 9426a5cf4e90e1dea756de15b070b77fe95d5faa Mon Sep 17 00:00:00 2001 From: houfaxin Date: Thu, 18 Sep 2025 14:36:50 +0800 Subject: [PATCH 13/20] Update serverless-database-audit-logging.md --- tidb-cloud/serverless-database-audit-logging.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/tidb-cloud/serverless-database-audit-logging.md b/tidb-cloud/serverless-database-audit-logging.md index fdef8f63867df..1aba408510d83 100644 --- a/tidb-cloud/serverless-database-audit-logging.md +++ b/tidb-cloud/serverless-database-audit-logging.md @@ -153,7 +153,7 @@ You can enable audit logging for a {{{ .essential }}} cluster. 4. Select the storage location of the audit logs and fill in the necessary information, then click **Test Connection and Next** or **Next**. For more information about the available storage locations, see [Audit logging locations](#audit-logging-locations). -5. In the **Database Audit Logging Setting** dialog box, fill in the log file rotation and log redaction settings, and then click **Save**. +5. In the **Database Audit Logging Settings** dialog box, fill in the log file rotation and log redaction settings, and then click **Save**. @@ -187,7 +187,7 @@ You can edit the audit logging for a {{{ .essential }}} cluster after enabling i 3. On the **DB Audit Logging** page, click **Settings**. -4. In the **Database Audit Logging Setting** dialog box, fill the log file rotation and log redaction settings, and then click **Save**. +4. In the **Database Audit Logging Settings** dialog box, fill the log file rotation and log redaction settings, and then click **Save**. @@ -217,7 +217,7 @@ You can disable audit logging for a {{{ .essential }}} cluster. 3. On the **DB Audit Logging** page, click **...** in the upper-right corner, and then click **Disable**. -4. Click **Disable** in the dialog box to disable audit logging. +4. In the **Disable DB Audit Logging** dialog box, click **Disable**. @@ -232,7 +232,7 @@ ticloud serverless audit-log config update -c --disabled=true ## Manage audit logging filter rules -You can create, edit, disable, and delete a filter rule. +You can create, edit, disable, and delete a audit logging filter rule. ### Create a filter rule @@ -251,7 +251,7 @@ To create a filter rule, define which users and events you want to capture in th 3. On the **DB Audit Logging** page, click **Add Filter Rule**. -4. Fill in the `Filter Name`, `SQL Users`, and `Filter Rules` fields in the **Add Filter Rule** dialog box, and then click **Confirm**. For more information about the fields, see [Audit logging filter rules](#audit-logging-filter-rules). +4. Fill in the **Filter Name**, **SQL Users**, and **Filter Rule** fields in the **Add Filter Rule** dialog box, and then click **Confirm**. For more information about the fields, see [Audit logging filter rules](#audit-logging-filter-rules). @@ -279,7 +279,7 @@ ticloud serverless audit-log filter create --cluster-id --display-n 3. On the **DB Audit Logging** page, find the filter rule you want to edit, click **...** in its row, and then click **Edit**. -4. Fill in the `Filter Name` and `Filter Rules` fields in the **Edit Filter Rule** dialog box, and then click **Confirm**. +4. Fill in the **Filter Name** and **Filter Rule** fields in the **Edit Filter Rule** dialog box, and then click **Confirm**. @@ -335,7 +335,7 @@ ticloud serverless audit-log filter update --cluster-id --filter-ru 3. On the **DB Audit Logging** page, choose the filter rule you want to delete and click **...**. -4. Click **Delete** and then click **I understand. Delete it** in the dialog box to delete the filter rule. +4. Click **Delete** and then click **I understand. Delete it** to delete the filter rule. From 40196d5d22c47c82625382486546620e69806456 Mon Sep 17 00:00:00 2001 From: shiyuhang <1136742008@qq.com> Date: Wed, 24 Sep 2025 13:13:11 +0800 Subject: [PATCH 14/20] rename doc --- TOC-tidb-cloud-essential.md | 2 +- ...ase-audit-logging.md => essential-database-audit-logging.md} | 0 2 files changed, 1 insertion(+), 1 deletion(-) rename tidb-cloud/{serverless-database-audit-logging.md => essential-database-audit-logging.md} (100%) diff --git a/TOC-tidb-cloud-essential.md b/TOC-tidb-cloud-essential.md index fbb4c5e6f1518..10d653dadbaf9 100644 --- a/TOC-tidb-cloud-essential.md +++ b/TOC-tidb-cloud-essential.md @@ -266,7 +266,7 @@ - [TLS Connections to TiDB Cloud](/tidb-cloud/secure-connections-to-serverless-clusters.md) - Audit Management - [Console Audit Logging](/tidb-cloud/tidb-cloud-console-auditing.md) - - [Database Audit Logging](/tidb-cloud/serverless-database-audit-logging.md) + - [Database Audit Logging](/tidb-cloud/essential-database-audit-logging.md) - Billing - [Invoices](/tidb-cloud/tidb-cloud-billing.md#invoices) - [Billing Details](/tidb-cloud/tidb-cloud-billing.md#billing-details) diff --git a/tidb-cloud/serverless-database-audit-logging.md b/tidb-cloud/essential-database-audit-logging.md similarity index 100% rename from tidb-cloud/serverless-database-audit-logging.md rename to tidb-cloud/essential-database-audit-logging.md From 4e07e9dcad7ceae0fac135f437b22920dc2dd30f Mon Sep 17 00:00:00 2001 From: shiyuhang <1136742008@qq.com> Date: Fri, 10 Oct 2025 12:42:47 +0800 Subject: [PATCH 15/20] remove base64 --- tidb-cloud/essential-database-audit-logging.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tidb-cloud/essential-database-audit-logging.md b/tidb-cloud/essential-database-audit-logging.md index 1aba408510d83..9a0e4870d7af1 100644 --- a/tidb-cloud/essential-database-audit-logging.md +++ b/tidb-cloud/essential-database-audit-logging.md @@ -69,7 +69,7 @@ For more information, see [Configure Amazon S3 access](/tidb-cloud/serverless-ex To store audit logs to Google Cloud Storage, you need to provide the following information: - URI: `gs:////` -- Access credential: a **base64 encoded** [service account key](https://cloud.google.com/iam/docs/creating-managing-service-account-keys) for your bucket. Make sure the service account key has the `storage.objects.create` and `storage.objects.delete` permissions. +- Access credential: a [service account key](https://cloud.google.com/iam/docs/creating-managing-service-account-keys) for your bucket. Make sure the service account key has the `storage.objects.create` and `storage.objects.delete` permissions. For more information, see [Configure GCS access](/tidb-cloud/serverless-external-storage.md#configure-gcs-access). From 335d937ea9f504915e07d7aa0ea902b970c3abef Mon Sep 17 00:00:00 2001 From: shi yuhang <52435083+shiyuhang0@users.noreply.github.com> Date: Fri, 10 Oct 2025 15:03:19 +0800 Subject: [PATCH 16/20] Apply suggestions from code review Co-authored-by: Aolin --- .../essential-database-audit-logging.md | 106 ++++++++++-------- 1 file changed, 58 insertions(+), 48 deletions(-) diff --git a/tidb-cloud/essential-database-audit-logging.md b/tidb-cloud/essential-database-audit-logging.md index 9a0e4870d7af1..2c5058416b492 100644 --- a/tidb-cloud/essential-database-audit-logging.md +++ b/tidb-cloud/essential-database-audit-logging.md @@ -1,5 +1,5 @@ --- -title: Database Audit Logging for {{{ .essential }}} +title: Database Audit Logging (Beta) for {{{ .essential }}} summary: Learn about how to audit a {{{ .essential }}} cluster in TiDB Cloud. aliases: ['/tidbcloud/serverless-audit-logging'] --- @@ -20,9 +20,9 @@ The audit logging feature is disabled by default. To audit a cluster, you need t ### Data redaction -{{{ .essential }}} redacts sensitive data in the audit logs by default. Take the following SQL statement as an example: +By default, {{{ .essential }}} redacts sensitive data in audit logs. Take the following SQL statement as an example: -```sql +```sql INSERT INTO `test`.`users` (`id`, `name`, `password`) VALUES (1, 'Alice', '123456'); ``` @@ -36,8 +36,8 @@ INSERT INTO `test`.`users` (`id`, `name`, `password`) VALUES ( ... ); {{{ .essential }}} generates a new audit log file when either of the following conditions is met: -- The size of the current log file reaches rotation size (100 MB by default). -- Rotation interval (one hour by default) has passed since the previous log generation. Depending on the internal scheduling mechanism, log generation might be delayed by a few minutes. +- The current log file reaches the rotation size (100 MiB by default). +- The rotation interval (one hour by default) has passed since the previous log generation. Depending on the internal scheduling mechanism, log generation might be delayed by a few minutes. ## Audit logging locations @@ -51,43 +51,43 @@ You can store the audit logs in the following locations: ### TiDB Cloud -You can store audit logs in TiDB Cloud and download them to your local machine. The audit logs expire and are deleted after 365 days. To request longer storage duration, contact [TiDB Cloud Support](/tidb-cloud/tidb-cloud-support.md). +You can store audit logs in TiDB Cloud and download them to your local machine. Audit logs expire and are deleted after 365 days. To request a longer retention period, contact [TiDB Cloud Support](/tidb-cloud/tidb-cloud-support.md). ### Amazon S3 -To store audit logs to Amazon S3, you need to provide the following information: +To store audit logs in Amazon S3, you need to provide the following information: - URI: `s3:////` -- One of the following access credentials: - - [An access key](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html): Make sure the access key has the `s3:PutObject` and `s3:ListBucket` permissions. - - [A role ARN](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference-arns.html): Make sure the role ARN (Amazon Resource Name) has the `s3:PutObject` permissions. Note that only clusters hosted on AWS support the role ARN. +- Access credentials: choose one of the following: + - An [access key](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html) with the `s3:PutObject` and `s3:ListBucket` permissions. + - A [role ARN](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference-arns.html) with the `s3:PutObject` permission. Only clusters hosted on AWS support using a role ARN. For more information, see [Configure Amazon S3 access](/tidb-cloud/serverless-external-storage.md#configure-amazon-s3-access). ### Google Cloud Storage -To store audit logs to Google Cloud Storage, you need to provide the following information: +To store audit logs in Google Cloud Storage, you need to provide the following information: - URI: `gs:////` -- Access credential: a [service account key](https://cloud.google.com/iam/docs/creating-managing-service-account-keys) for your bucket. Make sure the service account key has the `storage.objects.create` and `storage.objects.delete` permissions. +- Access credential: a [service account key](https://cloud.google.com/iam/docs/creating-managing-service-account-keys) with the `storage.objects.create` and `storage.objects.delete` permissions. For more information, see [Configure GCS access](/tidb-cloud/serverless-external-storage.md#configure-gcs-access). ### Azure Blob Storage -To store audit logs to Azure Blob Storage, you need to provide the following information: +To store audit logs in Azure Blob Storage, you need to provide the following information: - URI: `azure://.blob.core.windows.net///` or `https://.blob.core.windows.net///` -- Access credential: a [shared access signature (SAS) token](https://docs.microsoft.com/en-us/azure/storage/common/storage-sas-overview) for your Azure Blob Storage container. Make sure the SAS token has the `Read` and `Write` permissions on the `Container` and `Object` resources. +- Access credential: a [shared access signature (SAS) token](https://docs.microsoft.com/en-us/azure/storage/common/storage-sas-overview) with `Read` and `Write` permissions on the `Container` and `Object` resources. For more information, see [Configure Azure Blob Storage access](/tidb-cloud/serverless-external-storage.md#configure-azure-blob-storage-access). ### Alibaba Cloud OSS -To store audit logs to Alibaba Cloud OSS, you need to provide the following information: +To store audit logs in Alibaba Cloud OSS, you need to provide the following information: - URI: `oss:////` -- Access credential: An [AccessKey pair](https://www.alibabacloud.com/help/en/ram/user-guide/create-an-accesskey-pair) for your Alibaba Cloud account. Make sure the AccessKey pair has the `oss:PutObject` and `oss:GetBucketInfo` permissions to allow data export to the OSS bucket. +- Access credential: an [AccessKey pair](https://www.alibabacloud.com/help/en/ram/user-guide/create-an-accesskey-pair) with the `oss:PutObject` and `oss:GetBucketInfo` permissions to allow data export to the OSS bucket. For more information, see [Configure Alibaba Cloud Object Storage Service (OSS) access](/tidb-cloud/serverless-external-storage.md#configure-alibaba-cloud-object-storage-service-oss-access). @@ -106,7 +106,7 @@ The filter rule contains the following fields: The following table shows all event classes in database audit logging: -| Event Class | Description | Parent-class | +| Event class | Description | Parent-class | |---------------|--------------------------------------------------------------------------------------------------|---------------| | `CONNECTION` | Records all operations related to connections, such as handshaking, connections, disconnections, connection reset, and changing users | - | | `CONNECT` | Records all operations of the handshaking in connections | `CONNECTION` | @@ -132,40 +132,40 @@ You can enable, edit, and disable audit logging. ### Enable audit logging -You can enable audit logging for a {{{ .essential }}} cluster. +You can enable audit logging for a {{{ .essential }}} cluster using the TiDB Cloud console or the TiDB Cloud CLI. > **Note:** > -> Only enabling audit logging will not generate audit logs. You need to configure filters to specify what events to log. For more information, see [Manage audit logging filter rules](#manage-audit-logging-filter-rules). +> Enabling audit logging alone does not generate audit logs. You must also configure filters to specify which events to log. For more information, see [Manage audit logging filter rules](#manage-audit-logging-filter-rules).
1. Log in to the [TiDB Cloud console](https://tidbcloud.com/) and navigate to the [**Clusters**](https://tidbcloud.com/project/clusters) page of your project. - > **Tip:** - > - > You can use the combo box in the upper-left corner to switch between organizations, projects, and clusters. + > **Tip:** + > + > You can use the combo box in the upper-left corner to switch between organizations, projects, and clusters. 2. Click the name of your target cluster to go to its overview page, and then click **Settings** > **DB Audit Logging** in the left navigation pane. 3. On the **DB Audit Logging** page, click **Enable**. -4. Select the storage location of the audit logs and fill in the necessary information, then click **Test Connection and Next** or **Next**. For more information about the available storage locations, see [Audit logging locations](#audit-logging-locations). +4. Select a storage location for the audit logs and fill in the required information. Then click **Test Connection and Next** or **Next**. For more information about available storage locations, see [Audit logging locations](#audit-logging-locations). -5. In the **Database Audit Logging Settings** dialog box, fill in the log file rotation and log redaction settings, and then click **Save**. +5. In the **Database Audit Logging Settings** dialog, fill in the log file rotation and log redaction settings, and then click **Save**.
-Take Amazon S3 storage as an example. Run the following command to enable audit logging and store the audit logs to Amazon S3: +Take Amazon S3 storage as an example. To enable audit logging and store audit logs in Amazon S3, run the following command: ```shell -ticloud serverless audit-log config update -c --enabled --cloud-storage S3 --s3.uri --s3.access-key-id --s3.secret-access-key --rotation-size-mib --rotation-interval-minutes --unredacted= +ticloud serverless audit-log config update -c --enabled --cloud-storage S3 --s3.uri --s3.access-key-id --s3.secret-access-key --rotation-size-mib --rotation-interval-minutes --unredacted= ``` -`--rotation-size-mib`, `--rotation-interval-minutes`, and `--unredacted` are optional parameters. If you do not specify them, the default values are used. +The `--rotation-size-mib`, `--rotation-interval-minutes`, and `--unredacted` parameters are optional. If you do not specify them, the default values are used.
@@ -187,12 +187,14 @@ You can edit the audit logging for a {{{ .essential }}} cluster after enabling i 3. On the **DB Audit Logging** page, click **Settings**. -4. In the **Database Audit Logging Settings** dialog box, fill the log file rotation and log redaction settings, and then click **Save**. +4. In the **Database Audit Logging Settings** dialog, update the log file rotation or log redaction settings, and then click **Save**.
+To update the audit logging settings using the TiDB Cloud CLI, run the following command: + ```shell ticloud serverless audit-log config update -c --rotation-size-mib --rotation-interval-minutes --unredacted= ``` @@ -217,12 +219,14 @@ You can disable audit logging for a {{{ .essential }}} cluster. 3. On the **DB Audit Logging** page, click **...** in the upper-right corner, and then click **Disable**. -4. In the **Disable DB Audit Logging** dialog box, click **Disable**. +4. In the **Disable DB Audit Logging** dialog, click **Disable**.
+To disable audit logging using the TiDB Cloud CLI, run the following command: + ```shell ticloud serverless audit-log config update -c --disabled=true ``` @@ -232,7 +236,7 @@ ticloud serverless audit-log config update -c --disabled=true ## Manage audit logging filter rules -You can create, edit, disable, and delete a audit logging filter rule. +You can create, edit, disable, and delete an audit logging filter rule. ### Create a filter rule @@ -243,20 +247,22 @@ To create a filter rule, define which users and events you want to capture in th 1. Log in to the [TiDB Cloud console](https://tidbcloud.com/) and navigate to the [**Clusters**](https://tidbcloud.com/project/clusters) page of your project. - > **Tip:** - > - > You can use the combo box in the upper-left corner to switch between organizations, projects, and clusters. + > **Tip:** + > + > You can use the combo box in the upper-left corner to switch between organizations, projects, and clusters. 2. Click the name of your target cluster to go to its overview page, and then click **Settings** > **DB Audit Logging** in the left navigation pane. 3. On the **DB Audit Logging** page, click **Add Filter Rule**. -4. Fill in the **Filter Name**, **SQL Users**, and **Filter Rule** fields in the **Add Filter Rule** dialog box, and then click **Confirm**. For more information about the fields, see [Audit logging filter rules](#audit-logging-filter-rules). +4. In the **Add Filter Rule** dialog, fill in the **Filter Name**, **SQL Users**, and **Filter Rule** fields, and then click **Confirm**. For more information about these fields, see [Audit logging filter rules](#audit-logging-filter-rules).
+To create a filter rule using the TiDB Cloud CLI, run the following command: + ```shell ticloud serverless audit-log filter create --cluster-id --display-name --rule '{"users":["%@%"],"filters":[{}]}' ``` @@ -277,14 +283,16 @@ ticloud serverless audit-log filter create --cluster-id --display-n 2. Click the name of your target cluster to go to its overview page, and then click **Settings** > **DB Audit Logging** in the left navigation pane. -3. On the **DB Audit Logging** page, find the filter rule you want to edit, click **...** in its row, and then click **Edit**. +3. On the **DB Audit Logging** page, locate the filter rule you want to edit, click **...** in its row, and then click **Edit**. -4. Fill in the **Filter Name** and **Filter Rule** fields in the **Edit Filter Rule** dialog box, and then click **Confirm**. +4. In the **Edit Filter Rule** dialog, update the **Filter Name** or **Filter Rule** field, and then click **Confirm**.
+To edit a filter rule using the TiDB Cloud CLI, run the following command: + ```shell ticloud serverless audit-log filter update --cluster-id --filter-rule-id --rule '{"users":["%@%"],"filters":[{"classes":["QUERY"],"tables":["test.t"]}]}' ``` @@ -305,14 +313,14 @@ ticloud serverless audit-log filter update --cluster-id --filter-ru 2. Click the name of your target cluster to go to its overview page, and then click **Settings** > **DB Audit Logging** in the left navigation pane. -3. On the **DB Audit Logging** page, choose the filter rule that you want to disable. - -4. Turn off the slider to disable the filter rule. +3. On the **DB Audit Logging** page, locate the filter rule you want to disable, and turn off the toggle to disable the filter rule.
+To disable a filter rule using the TiDB Cloud CLI, run the following command: + ```shell ticloud serverless audit-log filter update --cluster-id --filter-rule-id --enabled=false ``` @@ -333,9 +341,9 @@ ticloud serverless audit-log filter update --cluster-id --filter-ru 2. Click the name of your target cluster to go to its overview page, and then click **Settings** > **DB Audit Logging** in the left navigation pane. -3. On the **DB Audit Logging** page, choose the filter rule you want to delete and click **...**. +3. On the **DB Audit Logging** page, locate the filter rule you want to delete and click **...**. -4. Click **Delete** and then click **I understand. Delete it** to delete the filter rule. +4. Click **Delete**, and then click **I understand. Delete it** to confirm.
@@ -350,12 +358,12 @@ ticloud serverless audit-log filter delete --cluster-id --filter-ru ## Access audit logging with TiDB Cloud Storage -When you store audit logs in TiDB Cloud, {{{ .essential }}} stores them as readable text files named `YYYY-MM-DD-.log`, which you can access and download. +When you store audit logs in TiDB Cloud, {{{ .essential }}} saves them as readable text files named `YYYY-MM-DD-.log`. You can view and download these files from the TiDB Cloud console or using the TiDB Cloud CLI. > **Note:** > -> {{{ .essential }}} does not guarantee sequential ordering of audit logs. The log file named `YYYY-MM-DD-.log` might contain the audit logs in previous days. -> If you want to retrieve all logs from a specific date (for example, January 1, 2025), specifying `--start-date 2025-01-01` and `--end-date 2025-01-02` usually works. But under extreme conditions, you might need to download all log files and order them by the `TIME` field. +> - {{{ .essential }}} does not guarantee that audit logs are stored in sequential order. A log file named `YYYY-MM-DD-.log` might contain entries from earlier dates. +> - To retrieve all logs for a specific date (for example, January 1, 2025), set `--start-date 2025-01-01` and `--end-date 2025-01-02`. In some cases, you might need to download all log files and sort them by the `TIME` field.
@@ -368,7 +376,7 @@ When you store audit logs in TiDB Cloud, {{{ .essential }}} stores them as reada 2. Click the name of your target cluster to go to its overview page, and then click **Settings** > **DB Audit Logging** in the left navigation pane. -3. On the **DB Audit Logging** page, you can view the list of audit logs under `TiDB Cloud Storage`. +3. On the **DB Audit Logging** page, you can view the list of audit logs under **TiDB Cloud Storage**. 4. To download audit logs, select one or more logs from the list and then click **Download**. @@ -376,12 +384,14 @@ When you store audit logs in TiDB Cloud, {{{ .essential }}} stores them as reada
+To download audit logs using the TiDB Cloud CLI, run the following command: + ```shell ticloud serverless audit-log download --cluster-id --output-path --start-date --end-date ``` -- `start-date`: The start date of the audit log that you want to download in the format of `YYYY-MM-DD`, for example `2025-01-01`. -- `end-date`: The end date of the audit log that you want to download in the format of `YYYY-MM-DD`, for example `2025-01-01`. +- `start-date`: the start date of the audit logs to download, in the format of `YYYY-MM-DD`, for example, `2025-01-01`. +- `end-date`: the end date of the audit logs to download, in the format of `YYYY-MM-DD`, for example, `2025-01-01`.
@@ -448,4 +458,4 @@ When the event class is `AUDIT` or a subclass of `AUDIT`, the audit logs contain ## Audit logging limitations -{{{ .essential }}} does not guarantee the sequential order of audit logs, which means that you might have to review all log files to view the latest events. To sort the logs chronologically, you can use the `TIME` field in the audit logs. +{{{ .essential }}} does not guarantee the sequential order of audit logs, which means that you might have to review all log files find the most recent events. To sort the logs chronologically, you can use the `TIME` field in the audit logs. From e5fab89af132fc6453eb4458ff40b40b6163f8ae Mon Sep 17 00:00:00 2001 From: shiyuhang <1136742008@qq.com> Date: Fri, 10 Oct 2025 15:08:16 +0800 Subject: [PATCH 17/20] fix according to the review --- tidb-cloud/essential-database-audit-logging.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/tidb-cloud/essential-database-audit-logging.md b/tidb-cloud/essential-database-audit-logging.md index 2c5058416b492..037a2f021cd55 100644 --- a/tidb-cloud/essential-database-audit-logging.md +++ b/tidb-cloud/essential-database-audit-logging.md @@ -41,7 +41,7 @@ INSERT INTO `test`.`users` (`id`, `name`, `password`) VALUES ( ... ); ## Audit logging locations -You can store the audit logs in the following locations: +You can store audit logs in the following locations: - TiDB Cloud - [Amazon S3](https://aws.amazon.com/s3/) @@ -59,7 +59,7 @@ To store audit logs in Amazon S3, you need to provide the following information: - URI: `s3:////` - Access credentials: choose one of the following: - - An [access key](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html) with the `s3:PutObject` and `s3:ListBucket` permissions. + - An [access key](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html) with the `s3:PutObject` permissions. - A [role ARN](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference-arns.html) with the `s3:PutObject` permission. Only clusters hosted on AWS support using a role ARN. For more information, see [Configure Amazon S3 access](/tidb-cloud/serverless-external-storage.md#configure-amazon-s3-access). From cfbc9baac60ca84b6130e9e2a0cdffabcb2b02c6 Mon Sep 17 00:00:00 2001 From: xixirangrang Date: Fri, 10 Oct 2025 16:45:49 +0800 Subject: [PATCH 18/20] Apply suggestions from code review Co-authored-by: Aolin --- tidb-cloud/essential-database-audit-logging.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/tidb-cloud/essential-database-audit-logging.md b/tidb-cloud/essential-database-audit-logging.md index 037a2f021cd55..4611e4e7eec9a 100644 --- a/tidb-cloud/essential-database-audit-logging.md +++ b/tidb-cloud/essential-database-audit-logging.md @@ -59,7 +59,7 @@ To store audit logs in Amazon S3, you need to provide the following information: - URI: `s3:////` - Access credentials: choose one of the following: - - An [access key](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html) with the `s3:PutObject` permissions. + - An [access key](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html) with the `s3:PutObject` permission. - A [role ARN](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference-arns.html) with the `s3:PutObject` permission. Only clusters hosted on AWS support using a role ARN. For more information, see [Configure Amazon S3 access](/tidb-cloud/serverless-external-storage.md#configure-amazon-s3-access). @@ -406,13 +406,13 @@ All classes of audit logs contain the following information: | Field | Description | |---------------|-----------------------------------------------------------------------------------------------| -| `ID` | The unique identifier that identifies the audit record of an operation | -| `TIME` | The timestamp of the audit record | -| `EVENT` | The event classes of the audit record. Multiple event types are separated by commas (`,`) | -| `USER` | The username of the audit record | -| `ROLES` | The roles of the user at the time of the operation | -| `CONNECTION_ID` | The identifier of the user's connection | -| `TABLES` | The accessed tables related to this audit record | +| `ID` | The unique identifier that identifies the audit record of an operation. | +| `TIME` | The timestamp of the audit record. | +| `EVENT` | The event classes of the audit record. Multiple event types are separated by commas (`,`). | +| `USER` | The username of the audit record. | +| `ROLES` | The roles of the user at the time of the operation. | +| `CONNECTION_ID` | The identifier of the user's connection. | +| `TABLES` | The accessed tables related to this audit record. | | `STATUS_CODE` | The status code of the audit record. `1` means success, and `0` means failure. | | `KEYSPACE_NAME` | The keyspace name of the audit record. | | `SERVERLESS_TENANT_ID` | The ID of the serverless tenant that the cluster belongs to. | From c705f2ce0a72e1155cf797d704c977c0318c7b9d Mon Sep 17 00:00:00 2001 From: shiyuhang <1136742008@qq.com> Date: Fri, 10 Oct 2025 17:05:54 +0800 Subject: [PATCH 19/20] add note --- tidb-cloud/essential-database-audit-logging.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/tidb-cloud/essential-database-audit-logging.md b/tidb-cloud/essential-database-audit-logging.md index 4611e4e7eec9a..58b2ba17bc8b9 100644 --- a/tidb-cloud/essential-database-audit-logging.md +++ b/tidb-cloud/essential-database-audit-logging.md @@ -125,6 +125,11 @@ The following table shows all event classes in database audit logging: | `QUERY_DDL` | Records all operations of the DDL statements | `QUERY` | | `AUDIT` | Records all operations related to setting TiDB database auditing, including setting system variables and calling system functions | - | | `AUDIT_FUNC_CALL` | Records all operations of calling system functions related to TiDB Cloud database auditing | `AUDIT` | +| `AUDIT_SET_SYS_VAR` | Records all operations of setting system variables | `AUDIT` | + +> **Note:** +> +> The `AUDIT` event class and its subclasses are always recorded in audit logs and cannot be filtered out. ## Configure audit logging From 50fb33ff3faa422d7ca035b1db4f4e440e6672f1 Mon Sep 17 00:00:00 2001 From: qiancai Date: Tue, 14 Oct 2025 19:13:34 +0800 Subject: [PATCH 20/20] Update tidb-cloud-release-notes.md --- tidb-cloud/tidb-cloud-release-notes.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/tidb-cloud/tidb-cloud-release-notes.md b/tidb-cloud/tidb-cloud-release-notes.md index ac38479cc6175..64be041bf4994 100644 --- a/tidb-cloud/tidb-cloud-release-notes.md +++ b/tidb-cloud/tidb-cloud-release-notes.md @@ -303,8 +303,6 @@ This page lists the release notes of [TiDB Cloud](https://www.pingcap.com/tidb-c To request this feature, click **?** in the lower-right corner of the [TiDB Cloud console](https://tidbcloud.com) and click **Request Support**. Then, fill in "Apply for TiDB Cloud Serverless database audit logging" in the Description field and click **Submit**. - For more information, see [TiDB Cloud Serverless Database Audit Logging](/tidb-cloud/serverless-audit-logging.md). - - [TiDB Cloud Dedicated](/tidb-cloud/select-cluster-tier.md#tidb-cloud-dedicated) supports user-controlled log redaction. You can now enable or disable log redaction for your TiDB Cloud Dedicated clusters to manage the redaction status of cluster logs by yourself.