6.4.5.6 監査ログファイルの読取り

監査ログプラグインは、JSON 形式の監査ログファイルを読み取るための SQL インタフェースを提供するユーザー定義関数をサポートしています。 (この機能は、他の形式で書き込まれたログファイルには適用されません。)

監査ログプラグインが初期化され、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 監査イベントが実際に含まれていることを確認し、各ファイルの最初のイベントのタイムスタンプを使用してファイルをソートします。その結果、ログ読取りユーザー定義関数 (UDF) を使用してアクセスされる一連のファイルが生成されます:

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" }
```
start 品目は、MySQL 8.0.22 で許可されています。
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() に渡されると、使用可能なイベントの数に関係なく、最大 1 つのイベントを含む結果が生成されます。

MySQL 8.0.19 より前では、監査ログ UDF からの文字列の戻り値はバイナリ文字列です。バイナリ以外の文字列 (JSON 値を操作する関数など) を必要とする関数でバイナリ文字列を使用するには、バイナリ以外の文字列に変換します。たとえば、ブックマークを JSON_SET() に渡す前に、次のように utf8mb4 に変換します:

SET @mark = CONVERT(@mark USING utf8mb4);

このステートメントは、MySQL 8.0.19 以上でも使用できます。これらのバージョンでは、基本的に no-op であり、無害です。

audit_log_read() が読み取るバイト数の制限を設定するには、audit_log_read_buffer_size システム変数を設定します。 MySQL 8.0.12 では、この変数のデフォルトは 32KB で、実行時に設定できます。各クライアントは、audit_log_read() を使用するために audit_log_read_buffer_size のセッション値を適切に設定する必要があります。

audit_log_read() をコールするたびに、バッファサイズ内に収まる数の使用可能なイベントが返されます。バッファサイズ内に収まらないイベントはスキップされ、警告が生成されます。この動作では、アプリケーションの適切なバッファサイズを評価する際に次の要因を考慮してください:

audit_log_read() へのコール数とコールごとに返されるイベントとの間にはトレードオフがあります:
- バッファサイズを小さくすると、コールによって返されるイベントが少なくなるため、必要なコールが増えます。
- バッファサイズが大きいほど、コールはより多くのイベントを返すため、必要なコールは少なくなります。
デフォルトサイズの 32KB など、バッファサイズが小さいほど、イベントがバッファサイズを超えてスキップされる可能性が高くなります。

MySQL 8.0.12 より前では、audit_log_read_buffer_size のデフォルトは 1MB で、すべてのクライアントに影響し、サーバーの起動時にのみ変更できます。

監査ログ読み取り関数の詳細は、監査ログ関数を参照してください。