Skip to content

cloud: update Premium audit logging #22784

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
qqqdan wants to merge 6 commits into
base: release-8.5
Choose a base branch
from
Open

cloud: update Premium audit logging #22784

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
0d74757
Update tidb-cloud-auditing-premium.md
qqqdan Apr 20, 2026
f2488a9
Apply suggestions from code review
qqqdan Apr 22, 2026
ee10bc2
Apply suggestions from code review
qqqdan Apr 22, 2026
8c499e5
Update tidb-cloud-auditing-premium.md
qqqdan Apr 22, 2026
53f10bb
Merge branch 'Premium-audit-log-page-change' of https://github.com/pi…
qqqdan Apr 22, 2026
1592c9b
revise wording
Oreoxmt Apr 24, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
105 changes: 58 additions & 47 deletions tidb-cloud/premium/tidb-cloud-auditing-premium.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -233,54 +233,65 @@ If you no longer want to audit an instance, go to the page of the instance, clic
>
> Each time the size of the log file reaches 10 MiB, the log file is pushed to the cloud storage bucket. Therefore, after audit logging is disabled, the log file whose size is smaller than 10 MiB will not be automatically pushed to the cloud storage bucket. To get the log file in this situation, contact [TiDB Cloud Support](/tidb-cloud/tidb-cloud-support.md).

## Audit log fields
## 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

All classes of audit logs contain the following fields:

| Field | Description |
|---------------|-----------------------------------------------------------------------------------------------|
| `ID` | The unique identifier that identifies the audit record of an operation. |
| `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. |
| `REASON` | The error message of the audit record. Only recorded when an error occurs during the operation.|
Comment on lines +246 to +253
Copy link
Copy Markdown
Collaborator

@Oreoxmt Oreoxmt Apr 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
| `ID` | The unique identifier that identifies the audit record of an operation. |
| `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. |
| `REASON` | The error message of the audit record. Only recorded when an error occurs during the operation.|
| `ID` | The unique identifier of the audit record. |
| `EVENT` | The event classes of the audit record. Multiple event classes are separated by commas (`,`). |
| `USER` | The name of the user who performed the operation. |
| `ROLES` | The roles assigned to the user at the time of the operation. |
| `CONNECTION_ID` | The identifier of the user's connection. |
| `TABLES` | The tables accessed during the operation. |
| `STATUS_CODE` | The status code of the operation. `1` indicates success, and `0` indicates failure. |
| `REASON` | The error message of the operation. Recorded only when an error occurs. |


### SQL statement information

When the event class is `QUERY` or a subclass of `QUERY`, the audit logs contain the following fields:

| 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`. |
Comment on lines +262 to +264
Copy link
Copy Markdown
Collaborator

@Oreoxmt Oreoxmt Apr 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
| `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`. |
| `SQL_TEXT` | The executed SQL statement. If audit log redaction is enabled, the redacted statement is recorded instead. |
| `EXECUTE_PARAMS` | The parameters passed to the `EXECUTE` statement. Recorded only when the event classes include `EXECUTE` and redaction is disabled. |
| `AFFECTED_ROWS` | The number of rows affected by the SQL statement. Recorded only when the event classes include `QUERY_DML`. |


### Connection information

When the event class is `CONNECTION` or a subclass of `CONNECTION`, the audit logs contain the following fields:

| 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. |
Comment on lines +272 to +280
Copy link
Copy Markdown
Collaborator

@Oreoxmt Oreoxmt Apr 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
| `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. Not recorded when the event classes include `DISCONNECT`. |
| `CONNECTION_TYPE` | The type of the connection, such as Socket, UnixSocket, or SSL/TLS. |
| `PID` | The process ID of the current connection. |
| `SERVER_VERSION` | The version of the connected TiDB server. |
| `SSL_VERSION` | The version of SSL in use. |
| `HOST_IP` | The IP address of the connected TiDB server. |
| `HOST_PORT` | The port of the connected TiDB server. |
| `CLIENT_IP` | The IP address of the client. |
| `CLIENT_PORT` | The port of the client. |


> **Note:**
>
> In the following tables, the empty maximum length of a field means that the data type of this field has a well-defined constant length (for example, 4 bytes for INTEGER).

| Col # | Field name | TiDB data type | Maximum length | Description |
|---|---|---|---|---|
| 1 | N/A | N/A | N/A | Reserved for internal use |
| 2 | N/A | N/A | N/A | Reserved for internal use |
| 3 | N/A | N/A | N/A | Reserved for internal use |
| 4 | ID | INTEGER | | Unique event ID |
| 5 | TIMESTAMP | TIMESTAMP | | Time of event |
| 6 | EVENT_CLASS | VARCHAR | 15 | Event type |
| 7 | EVENT_SUBCLASS | VARCHAR | 15 | Event subtype |
| 8 | STATUS_CODE | INTEGER | | Response status of the statement |
| 9 | COST_TIME | FLOAT | | Time consumed by the statement |
| 10 | HOST | VARCHAR | 16 | Server IP |
| 11 | CLIENT_IP | VARCHAR | 16 | Client IP |
| 12 | USER | VARCHAR | 17 | Login username |
| 13 | DATABASE | VARCHAR | 64 | Event-related database |
| 14 | TABLES | VARCHAR | 64 | Event-related table name |
| 15 | SQL_TEXT | VARCHAR | 64 KB | Masked SQL statement |
| 16 | ROWS | INTEGER | | Number of affected rows (`0` indicates that no rows are affected) |

Depending on the EVENT_CLASS field value set by TiDB, database event records in audit logs also contain additional fields as follows:

- If the EVENT_CLASS value is `CONNECTION`, database event records also contain the following fields:

| Col # | Field name | TiDB data type | Maximum length | Description |
|---|---|---|---|---|
| 17 | CLIENT_PORT | INTEGER | | Client port number |
| 18 | CONNECTION_ID | INTEGER | | Connection ID |
| 19 | CONNECTION_TYPE | VARCHAR | 12 | Connection via `socket` or `unix-socket` |
| 20 | SERVER_ID | INTEGER | | TiDB server ID |
| 21 | SERVER_PORT | INTEGER | | The port that the TiDB server uses to listen to client communication via the MySQL protocol |
| 22 | SERVER_OS_LOGIN_USER | VARCHAR | 17 | The username of the TiDB process startup system |
| 23 | OS_VERSION | VARCHAR | N/A | The version of the operating system where the TiDB server is located |
| 24 | SSL_VERSION | VARCHAR | 6 | The current SSL version of TiDB |
| 25 | PID | INTEGER | | The PID of the TiDB process |

- If the EVENT_CLASS value is `TABLE_ACCESS` or `GENERAL`, database event records also contain the following fields:

| Col # | Field name | TiDB data type | Maximum length | Description |
|---|---|---|---|---|
| 17 | CONNECTION_ID | INTEGER | | Connection ID |
| 18 | COMMAND | VARCHAR | 14 | The command type of the MySQL protocol |
| 19 | SQL_STATEMENT | VARCHAR | 17 | The SQL statement type |
| 20 | PID | INTEGER | | The PID of the TiDB process |
> To improve traffic visibility, `CLIENT_IP` now displays the real client IP address for connections via AWS PrivateLink, instead of the Load Balancer (LB) IP. Currently, this feature is in beta and is available only in the AWS region `Frankfurt (eu-central-1)`.
Copy link
Copy Markdown
Collaborator

@Oreoxmt Oreoxmt Apr 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
> To improve traffic visibility, `CLIENT_IP` now displays the real client IP address for connections via AWS PrivateLink, instead of the Load Balancer (LB) IP. Currently, this feature is in beta and is available only in the AWS region `Frankfurt (eu-central-1)`.
> To improve traffic visibility, `CLIENT_IP` displays the actual client IP address for connections through AWS PrivateLink instead of the load balancer IP. This feature is in beta and is available only in the AWS region `Frankfurt (eu-central-1)`.


### Audit operation information

When the event class is `AUDIT` or a subclass of `AUDIT`, the audit logs contain the following fields:

| Field | Description |
|----------------|---------------------------------------------------------------------------------------------------------------|
| `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. |
Comment on lines +292 to +293
Copy link
Copy Markdown
Collaborator

@Oreoxmt Oreoxmt Apr 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
| `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_OP_TARGET`| The target object of the TiDB Cloud database audit setting change. |
| `AUDIT_OP_ARGS` | The arguments used in the TiDB Cloud database audit setting change. |


## Audit logging limitations

{{{ .premium }}} does not guarantee the sequential order of audit logs, which means that you might have to review all log files to find the most recent events. To sort the logs chronologically, you can use the `TIME` field in the audit logs.
Copy link
Copy Markdown
Collaborator

@Oreoxmt Oreoxmt Apr 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
{{{ .premium }}} does not guarantee the sequential order of audit logs, which means that you might have to review all log files to find the most recent events. To sort the logs chronologically, you can use the `TIME` field in the audit logs.
{{{ .premium }}} does not guarantee that audit logs are written in chronological order. To find the most recent events, you might need to review all log files. To sort logs chronologically, use the `TIME` field in each audit record.

Loading