Update the log redaction documentation

Signed-off-by: JmPotato <ghzpotato@gmail.com>
pingcap · Jul 2, 2024 · fdda754 · fdda754
1 parent 2a259a3
commit fdda754
Show file tree

Hide file tree

Showing 3 changed files with 30 additions and 6 deletions.
diff --git a/log-redaction.md b/log-redaction.md
@@ -9,12 +9,12 @@ TiDB 在提供详细的日志信息时，可能会把数据库敏感的数据（
 
 ## TiDB 组件日志脱敏
 
-TiDB 侧的日志脱敏需要将 [`global.tidb_redact_log`](/system-variables.md#tidb_redact_log) 的值设为 `1`。该变量值默认为 `0`，即关闭脱敏。
+TiDB 侧的日志脱敏需要将 [`global.tidb_redact_log`](/system-variables.md#tidb_redact_log) 的值设为 `ON` 或 `MARKER`。该变量值默认为 `OFF`，即关闭脱敏。
 
 可以通过 `set` 语法，设置全局系统变量 `tidb_redact_log`，示例如下：
 
 ```sql
-set @@global.tidb_redact_log=1;
+set @@global.tidb_redact_log = ON;
 ```
 
 设置后，所有新 session 产生的日志都会脱敏：
@@ -30,18 +30,40 @@ ERROR 1062 (23000): Duplicate entry '1' for key 't.a'
 打印出的错误日志如下：
 
 ```
-[2020/10/20 11:45:49.539 +08:00] [INFO] [conn.go:800] ["command dispatched failed"] [conn=5] [connInfo="id:5, addr:127.0.0.1:57222 status:10, collation:utf8_general_ci,  user:root"] [command=Query] [status="inTxn:0, autocommit:1"] [sql="insert into t values ( ? ) , ( ? )"] [txn_mode=OPTIMISTIC] [err="[kv:1062]Duplicate entry '?' for key 't.a'"]
+[2024/07/02 11:35:32.686 +08:00] [INFO] [conn.go:1146] ["command dispatched failed"] [conn=1482686470] [session_alias=] [connInfo="id:1482686470, addr:127.0.0.1:52258 status:10, collation:utf8mb4_0900_ai_ci, user:root"] [command=Query] [status="inTxn:0, autocommit:1"] [sql="insert into `t` values ( ... )"] [txn_mode=PESSIMISTIC] [timestamp=450859193514065921] [err="[kv:1062]Duplicate entry '?' for key 't.a'"]
 ```
 
-从以上报错日志可以看到，开启 `tidb_redact_log` 后，报错信息里的敏感内容被隐藏掉了（目前是用问号替代）。TiDB 日志中会把敏感信息隐藏掉，以此规避数据安全风险。
+从以上报错日志可以看到，当把 `tidb_redact_log` 的值设为 `ON` 后，TiDB 日志中会把敏感信息隐藏掉（以问号 ? 替换），以此规避数据安全风险。同时，TiDB 还提供了 `MARKER` 选项，当设置 `tidb_redact_log` 的值为 `MARKER` 时，TiDB 会在日志中用单角形引号 `‹›` 标记出敏感信息，而不是直接隐藏，以便用户能够自定义脱敏规则。
+
+```sql
+set @@global.tidb_redact_log = MARKER;
+```
+
+设置后，所有新 session 产生的日志都会对敏感信息进行标记，而不进行替换：
+
+```sql
+create table t (a int, unique key (a));
+Query OK, 0 rows affected (0.07 sec)
+
+insert into t values (1),(1);
+ERROR 1062 (23000): Duplicate entry '‹1›' for key 't.a'
+```
+
+打印出的错误日志如下：
+
+```
+[2024/07/02 11:35:01.426 +08:00] [INFO] [conn.go:1146] ["command dispatched failed"] [conn=1482686470] [session_alias=] [connInfo="id:1482686470, addr:127.0.0.1:52258 status:10, collation:utf8mb4_0900_ai_ci, user:root"] [command=Query] [status="inTxn:0, autocommit:1"] [sql="insert into `t` values ( ‹1› ) , ( ‹1› )"] [txn_mode=PESSIMISTIC] [timestamp=450859185309483010] [err="[kv:1062]Duplicate entry '‹1›' for key 't.a'"]
+```
+
+从以上报错日志可以看到，当把 `tidb_redact_log` 的值设为 `MARKER` 后，TiDB 日志中会用单角形引号 `‹›` 标记出敏感信息，用户可以根据自己的需求自定义脱敏规则来处理日志中的敏感信息。
 
 ## TiKV 组件日志脱敏
 
 TiKV 侧的日志脱敏需要将 [`security.redact-info-log`](/tikv-configuration-file.md#redact-info-log-从-v408-版本开始引入) 的值设为 `true`。该配置项值默认为 `false`，即关闭脱敏。
 
 ## PD 组件日志脱敏
 
-PD 侧的日志脱敏需要将 [`security.redact-info-log`](/pd-configuration-file.md#redact-info-log-从-v50-版本开始引入) 的值设为 `true`。该配置项值默认为 `false`，即关闭脱敏。
+PD 侧的日志脱敏需要将 [`security.redact-info-log`](/pd-configuration-file.md#redact-info-log-从-v50-版本开始引入) 的值设为 `true` 或 `"MARKER"`。该配置项值默认为 `false`，即关闭脱敏。
 
 ## TiFlash 组件日志脱敏
 

diff --git a/pd-configuration-file.md b/pd-configuration-file.md
@@ -193,8 +193,9 @@ pd-server 相关配置项。
 ### `redact-info-log` <span class="version-mark">从 v5.0 版本开始引入</span>
 
 + 控制 PD 日志脱敏的开关
-+ 该配置项值设为 true 时将对 PD 日志脱敏，遮蔽日志中的用户信息。
++ 可选值：false, true, "MARKER"
 + 默认值：false
++ 具体使用方法请参考 [日志脱敏](/log-redaction.md#pd-组件日志脱敏)。
 
 ## log
 

diff --git a/tikv-configuration-file.md b/tikv-configuration-file.md
@@ -2046,6 +2046,7 @@ Raft Engine 相关的配置项。
 
 + 若开启该选项，日志中的用户数据会以 `?` 代替。
 + 默认值：`false`
++ 具体使用方法请参考 [日志脱敏](/log-redaction.md#tikv-组件日志脱敏)。
 
 ## security.encryption