--- title: Audit Logging summary: Learn about how to audit a cluster in TiDB Cloud. --- # Audit Logging TiDB Cloud provides you with a database audit logging feature to record a history of user access details (such as any SQL statements executed) in logs. > **Warning:** > > Currently, the **audit logging** feature is experimental. It is not recommended that you use it for production environments. 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 the audit logging first, and then specify the auditing filter rules. > **Note:** > > Because audit logging consumes cluster resources, be prudent about whether to audit a cluster. ## Prerequisites - You are using a TiDB Cloud Dedicated tier or POC tier. Audit logging is not available for TiDB Cloud Developer Tier clusters. - You are the audit administrator of your organization in TiDB Cloud. Otherwise, you cannot see the audit-related options in the TiDB Cloud console. For more information, see [Configure member roles](manage-user-access.md#configure-member-roles). ## Enable audit logging for AWS or GCP To allow TiDB Cloud to write audit logs to your cloud bucket, you need to enable audit logging first.
### Enable audit logging for AWS To enable audit logging for AWS, take the following steps: #### Step 1. Create an Amazon S3 bucket Specify an Amazon S3 bucket in your corporate-owned AWS account as a destination to which TiDB Cloud writes the audit logs. For more information, see [Creating a bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/create-bucket-overview.html) in the AWS User Guide. #### Step 2. Configure Amazon S3 access > **Note:** > > Once the Amazon S3 access configuration is performed for one cluster in a project, you can use the same bucket as a destination for audit logs from all clusters in the same project. 1. Get the TiDB Cloud account ID and the External ID of the TiDB cluster that you want to enable audit logging. 1. In the TiDB Cloud console, choose a project and a cluster deployed on AWS. 2. Select **Settings** > **Audit Settings**. The **Audit Logging** dialog box is displayed. 3. In the **Audit Logging** dialog box, click **Show AWS IAM policy settings**. The corresponding TiDB Cloud Account ID and TiDB Cloud External ID of the TiDB cluster are displayed. 4. Record the TiDB Cloud Account ID and the External ID for later use. 2. In the AWS Management console, go to **IAM** > **Access Management** > **Policies**, and then check whether a storage bucket policy with the `s3:PutObject` write-only permission exists. - If yes, record the matched storage bucket policy for later use. - If not, go to **IAM** > **Access Management** > **Policies** > **Create Policy**, and define a bucket policy according to the following policy template. {{< copyable "" >}} ``` { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "s3:PutObject", "Resource": "/*" } ] } ``` In the template, `` is the Amazon Resource Name (ARN) of your S3 bucket. You can go to the **Properties** tab in your S3 bucket and get the Amazon Resource Name (ARN) value in the **Bucket Overview** area. In the `"Resource"` field, you need to add `/*` after the ARN. For example, if the ARN is `arn:aws:s3:::tidb-cloud-test`, you need to configure the value of the `"Resource"` field as `"arn:aws:s3:::tidb-cloud-test/*"`. 3. Go to **IAM** > **Access Management** > **Roles**, and then check whether a role whose trust entity corresponds to the TiDB Cloud Account ID and the External ID that you recorded earlier already exists. - If yes, record the matched role for later use. - If not, click **Create role**, select **Another AWS account** as the trust entity type, and then enter the TiDB Cloud Account ID value into the **Account ID** field. Then, choose the **Require External ID** option and enter the TiDB Cloud External ID value into the **External ID** field. 4. In **IAM** > **Access Management** > **Roles**, click the role name from the previous step to go to the **Summary** page, and then take the following steps: 1. Under the **Permissions** tab, check whether the recorded policy with the `s3:PutObject` write-only permission is attached to the role. If not, choose **Attach Policies**, search for the needed policy, and then click **Attach Policy**. 2. Return to the **Summary** page and copy the **Role ARN** value to your clipboard. #### Step 3. Enable audit logging In the TiDB Cloud console, go back to the **Audit Logging** dialog box where you got the TiDB Cloud account ID and the External ID values, and then take the following steps: 1. In the **Bucket URL** field, enter `` that corresponds to the same bucket information you specified in [Step 2. Configure Amazon S3 access](#step-2-configure-amazon-s3-access). 2. In the **Bucket Region** drop-down list, select the AWS region where the bucket locates. 3. In the **Role ARN** field, fill in the Role ARN value that you copied in [Step 2. Configure Amazon S3 access](#step-2-configure-amazon-s3-access). 4. Click **Test Connectivity** to verify whether TiDB Cloud can access and write to the bucket. If it is successful, **Pass** is displayed. Otherwise, check your access configuration. 5. In the upper-right corner, toggle the audit setting to **On**. TiDB Cloud is ready to write audit logs for the specified cluster to your Amazon S3 bucket. > **Note:** > > - After enabling audit logging, if you make any new changes to the bucket URL, location, or ARN, you must click **Restart** to load the changes and rerun the **Test Connectivity** check to make the changes effective. > - To remove Amazon S3 access from TiDB Cloud, simply delete the trust policy that you added.
### Enable audit logging for GCP To enable audit logging for GCP, take the following steps: #### Step 1. Create a GCS bucket Specify a Google Cloud Storage (GCS) bucket in your corporate-owned GCP account as a destination to which TiDB Cloud writes audit logs. For more information, see [Creating storage buckets](https://cloud.google.com/storage/docs/creating-buckets) in the Google Cloud Storage documentation. #### Step 2. Configure GCS access > **Note:** > > Once the GCS access configuration is performed for one cluster in a project, you can use the same bucket as a destination for audit logs from all clusters in the same project. 1. Get the Google Cloud Service Account ID of the TiDB cluster that you want to enable audit logging. 1. In the TiDB Cloud console, choose a project and a cluster deployed on Google Cloud Platform. 2. Select **Settings** > **Audit Settings**. The **Audit Logging** dialog box is displayed. 3. Click **Show Google Cloud Service Account ID**, and then copy the Service Account ID for later use. 2. In the Google Cloud Platform (GCP) Management Console, go to **IAM & Admin** > **Roles**, and then check whether a role with the following write-only permissions of the storage container exists. - storage.objects.create - storage.objects.delete If yes, record the matched role for the TiDB cluster for later use. If not, go to **IAM & Admin** > **Roles** > **CREATE ROLE** to define a role for the TiDB cluster. 3. Go to **Cloud Storage** > **Browser**, select the GCS bucket you want TiDB Cloud to access, and then click **SHOW INFO PANEL**. The panel is displayed. 4. In the panel, click **ADD PRINCIPAL**. The dialog box for adding principals is displayed. 5. In the dialog box, take the following steps: 1. In the **New Principals** field, paste the Google Cloud Service Account ID of the TiDB cluster. 2. In the **Role** drop-down list, choose the role of the target TiDB cluster. 3. Click **SAVE**. #### Step 3. Enable audit logging In the TiDB Cloud console, go back to the **Audit Logging** dialog box where you got the TiDB Cloud account ID，and then take the following steps: 1. In the **Bucket URL** field, enter your full GCS bucket name. 2. In the **Bucket Region** field, select the GCS region where the bucket locates. 3. Click **Test Connectivity** to verify whether TiDB Cloud can access and write to the bucket. If it is successful, **Pass** is displayed. Otherwise, check your access configuration. 4. In the upper-right corner, toggle the audit setting to **On**. TiDB Cloud is ready to write audit logs for the specified cluster to your Amazon S3 bucket. > **Note:** > > - After enabling audit logging, if you make any new changes to bucket URL or location, you must click **Restart** to load the changes and rerun the **Test Connectivity** check to make the changes effective. > - To remove GCS access from TiDB Cloud, simply delete the principal that you added.
## Specify auditing filter rules After enabling audit logging, you must specify auditing filter rules to control which user access events to capture and write to audit logs versus which events to ignore. If no filter rules are specified, TiDB Cloud does not log anything. To specify auditing filter rules for a cluster, take the following steps: 1. In the **Audit Logging** dialog box where you enable audit logging, scroll down and locate the **Filter Rules** section. 2. Add one or more filter rules, one rule per row, with each rule specifying a user expression, database expression, table expression, and access type. > **Note:** > > - The filter rules are regular expressions and case-sensitive. If you use the wildcard rule `.*`, all users, databases, or table events in the cluster are logged. > - Because audit logging consumes cluster resources, be prudent when specifying filter rules. To minimize the consumption, it is recommended that you specify filter rules to limit the scope of audit logging to specific database objects, users, and actions, where possible. ## View audit logs TiDB Cloud audit logs are readable text files with the log creation date, cluster ID, and Pod ID incorporated into the filenames. For example, `tidb-audit-2022-04-21T18-16-29.529.log`. ## Disable audit logging If you no longer want to audit a cluster, go to the page of the cluster, click **Settings** > **Audit Settings**, and then toggle the audit setting in the upper-right corner to **Off** .