MySQL :: MySQL 9.0 參考手冊 :: 8.4.5.6 讀取稽核日誌檔案

版本 9.0

8.4 目前
8.0
5.7

8.0 日文

MySQL 9.0 參考手冊 / ... / 讀取稽核日誌檔案

8.4.5.6 讀取稽核日誌檔案

稽核日誌外掛程式支援提供 SQL 介面的函數，可讀取 JSON 格式的稽核日誌檔案。(此功能不適用於以其他格式撰寫的日誌檔案。)

當稽核日誌外掛程式初始化並設定為 JSON 記錄時，它會使用包含目前稽核日誌檔案的目錄作為搜尋可讀取稽核日誌檔案的位置。外掛程式會從 audit_log_file 系統變數的值判斷檔案位置、基本名稱和後綴，然後尋找名稱符合以下模式的檔案，其中 [...] 表示選擇性的檔案名稱部分

basename[.timestamp].suffix[.gz][[.pwd_id].enc]

如果檔案名稱以 .enc 結尾，則檔案會加密，且讀取其未加密的內容需要從金鑰環取得的解密密碼。稽核日誌外掛程式會如下判斷解密密碼的金鑰環 ID

如果 .enc 前面加上 pwd_id，則金鑰環 ID 為 audit_log-pwd_id。
如果 .enc 前面沒有加上 pwd_id，則該檔案的名稱是實作稽核日誌加密密碼歷程記錄之前的舊名稱。金鑰環 ID 為 audit_log。

如需加密稽核日誌檔案的詳細資訊，請參閱加密稽核日誌檔案。

外掛程式會忽略已手動重新命名且不符合模式的檔案，以及使用金鑰環中不再可用的密碼加密的檔案。外掛程式會開啟每個剩餘的候選檔案，驗證該檔案是否確實包含 JSON 稽核事件，並使用每個檔案第一個事件的時間戳記排序這些檔案。結果會是一系列可使用日誌讀取函數存取的檔案

audit_log_read() 會從稽核日誌讀取事件或關閉讀取程序。
audit_log_read_bookmark() 會傳回最近寫入稽核日誌事件的書籤。此書籤適用於傳遞給 audit_log_read()，以指示從何處開始讀取。

audit_log_read() 接受一個可選的 JSON 字串引數，而成功呼叫任一函式所傳回的結果都是 JSON 字串。

若要使用函式讀取稽核日誌，請遵循以下原則

呼叫 audit_log_read() 從指定位置或目前位置開始讀取事件，或關閉讀取
- 若要初始化稽核日誌讀取序列，請傳遞一個引數，指示從哪個位置開始。其中一種方法是傳遞 audit_log_read_bookmark() 所傳回的書籤
```
SELECT audit_log_read(audit_log_read_bookmark());
```
- 若要從序列中的目前位置繼續讀取，請呼叫 audit_log_read()，且不指定位置
```
SELECT audit_log_read();
```
- 若要明確關閉讀取序列，請傳遞 JSON null 引數
```
SELECT audit_log_read('null');
```
  不需要明確關閉讀取。當工作階段結束或透過呼叫 audit_log_read() 並使用指示從哪個位置開始的引數初始化新的讀取序列時，讀取會隱含關閉。
成功呼叫 audit_log_read() 以讀取事件會傳回包含稽核事件陣列的 JSON 字串
- 如果傳回陣列的最終值不是 JSON null 值，則表示剛讀取的事件後面還有更多事件，並且可以再次呼叫 audit_log_read() 以讀取更多事件。
- 如果傳回陣列的最終值是 JSON null 值，則表示目前的讀取序列中沒有剩餘可讀取的事件。
每個非 null 的陣列元素都是以 JSON 雜湊表示的事件。例如
```
[
  {
    "timestamp": "2020-05-18 13:39:33", "id": 0,
    "class": "connection", "event": "connect",
    ...
  },
  {
    "timestamp": "2020-05-18 13:39:33", "id": 1,
    "class": "general", "event": "status",
    ...
  },
  {
    "timestamp": "2020-05-18 13:39:33", "id": 2,
    "class": "connection", "event": "disconnect",
    ...
  },
  null
]
```
如需有關 JSON 格式稽核事件內容的詳細資訊，請參閱JSON 稽核日誌檔案格式。
在下列任何一種情況下，不指定位置的 audit_log_read() 呼叫以讀取事件會產生錯誤
- 尚未透過傳遞位置給 audit_log_read() 來初始化讀取序列。
- 目前的讀取序列中沒有剩餘可讀取的事件；也就是說，audit_log_read() 先前傳回的陣列以 JSON null 值結尾。
- 最近的讀取序列已透過傳遞 JSON null 值給 audit_log_read() 而關閉。
若要在這些情況下讀取事件，必須先透過呼叫 audit_log_read() 並使用指定位置的引數來初始化讀取序列。

若要指定 audit_log_read() 的位置，請加入一個引數，指示從何處開始讀取。例如，傳遞書籤，這是一個包含 timestamp 和 id 元素的 JSON 雜湊，可唯一識別特定事件。以下是透過呼叫 audit_log_read_bookmark() 函式所取得的範例書籤

mysql> SELECT audit_log_read_bookmark();
+-------------------------------------------------+
| audit_log_read_bookmark()                       |
+-------------------------------------------------+
| { "timestamp": "2020-05-18 21:03:44", "id": 0 } |
+-------------------------------------------------+

將目前的書籤傳遞給 audit_log_read() 會初始化從書籤位置開始的事件讀取

mysql> SELECT audit_log_read(audit_log_read_bookmark());
+-----------------------------------------------------------------------+
| audit_log_read(audit_log_read_bookmark())                             |
+-----------------------------------------------------------------------+
| [ {"timestamp":"2020-05-18 22:41:24","id":0,"class":"connection", ... |
+-----------------------------------------------------------------------+

audit_log_read() 的引數是可選的。如果存在，它可以是 JSON null 值以關閉讀取序列，也可以是 JSON 雜湊。

在 audit_log_read() 的雜湊引數中，項目是可選的，並控制讀取作業的各方面，例如開始讀取的位置或要讀取的事件數量。以下項目很重要（其他項目會被忽略）

start：要讀取的第一個事件在稽核日誌中的位置。位置以時間戳記給定，且讀取從時間戳記值當天或之後發生的第一個事件開始。start 項目具有此格式，其中 value 是文字時間戳記值
```
"start": { "timestamp": "value" }
```
timestamp、id：要讀取的第一個事件在稽核日誌中的位置。timestamp 和 id 項目共同組成一個書籤，可唯一識別特定事件。如果 audit_log_read() 引數包含任一項目，則必須同時包含兩者才能完整指定位置，否則會發生錯誤。
max_array_length：要從日誌讀取的最大事件數。如果省略此項目，則預設為讀取到日誌結尾或直到讀取緩衝區已滿為止，以先到者為準。

若要指定 audit_log_read() 的起始位置，請傳遞一個雜湊引數，其中包含 start 項目或由 timestamp 和 id 項目組成的書籤。如果雜湊引數同時包含 start 項目和書籤，則會發生錯誤。

如果雜湊引數未指定起始位置，則讀取會從目前位置繼續。

如果時間戳記值不包含時間部分，則假設時間部分為 00:00:00。

audit_log_read() 接受的範例引數

從給定時間戳記當天或之後發生的第一個事件開始讀取事件
```
audit_log_read('{ "start": { "timestamp": "2020-05-24 12:30:00" } }')
```

與上一個範例類似，但最多讀取 3 個事件

audit_log_read('{ "start": { "timestamp": "2020-05-24 12:30:00" }, "max_array_length": 3 }')

從 2020-05-24 00:00:00 當天或之後發生的第一個事件開始讀取事件（時間戳記不包含時間部分，因此假設為 00:00:00）
```
audit_log_read('{ "start": { "timestamp": "2020-05-24" } }')
```
從具有確切時間戳記和事件 ID 的事件開始讀取事件
```
audit_log_read('{ "timestamp": "2020-05-24 12:30:00", "id": 0 }')
```

與上一個範例類似，但最多讀取 3 個事件

audit_log_read('{ "timestamp": "2020-05-24 12:30:00", "id": 0, "max_array_length": 3 }')

從讀取序列中的目前位置讀取事件
```
audit_log_read()
```
從讀取序列中的目前位置開始，最多讀取 5 個事件
```
audit_log_read('{ "max_array_length": 5 }')
```
關閉目前的讀取序列
```
audit_log_read('null')
```

從任一日誌讀取函式傳回的 JSON 字串可以視需要進行操作。假設呼叫以取得書籤會產生此值

mysql> SET @mark := audit_log_read_bookmark();
mysql> SELECT @mark;
+-------------------------------------------------+
| @mark                                           |
+-------------------------------------------------+
| { "timestamp": "2020-05-18 16:10:28", "id": 2 } |
+-------------------------------------------------+

使用該引數呼叫 audit_log_read() 可以傳回多個事件。若要將 audit_log_read() 限制為最多讀取 N 個事件，請將具有該值的 max_array_length 項目新增至字串。例如，若要讀取單個事件，請修改字串如下

mysql> SET @mark := JSON_SET(@mark, '$.max_array_length', 1);
mysql> SELECT @mark;
+----------------------------------------------------------------------+
| @mark                                                                |
+----------------------------------------------------------------------+
| {"id": 2, "timestamp": "2020-05-18 16:10:28", "max_array_length": 1} |
+----------------------------------------------------------------------+

修改後的字串在傳遞給 audit_log_read() 時，會產生最多包含一個事件的結果，無論有多少事件可用。

如果從 mysql 用戶端內呼叫稽核日誌函式，則二進位字串結果會使用十六進位表示法顯示，具體取決於 --binary-as-hex 的值。如需有關該選項的詳細資訊，請參閱第 6.5.1 節，「mysql — MySQL 命令列用戶端」。

若要設定 audit_log_read() 讀取的位元組數上限，請設定 audit_log_read_buffer_size 系統變數。此變數的預設值為 32KB，並且可以在執行階段設定。每個用戶端都應針對其 audit_log_read() 的使用情況，適當設定其 audit_log_read_buffer_size 的工作階段值。

每次呼叫 audit_log_read() 都會傳回符合緩衝區大小的盡可能多的可用事件。不符合緩衝區大小的事件會被跳過並產生警告。鑑於這種行為，在評估應用程式的適當緩衝區大小時，請考慮以下因素

在呼叫 audit_log_read() 的次數與每次呼叫傳回的事件數之間存在權衡
- 使用較小的緩衝區大小，呼叫會傳回較少的事件，因此需要更多呼叫。
- 使用較大的緩衝區大小，呼叫會傳回更多事件，因此需要較少的呼叫。
使用較小的緩衝區大小（例如預設大小 32KB），事件超出緩衝區大小而被跳過的機率較大。

如需有關稽核日誌讀取函式的其他資訊，請參閱稽核日誌函式。