# ストリームのモニタリング
**重要**
この機能は AWS プレビューとして提供されており、変更される可能性があります。詳細については、「[AWS のサービス条件](https://aws.amazon.com/service-terms/)」のセクション 2、「ベータ版とプレビュー」を参照してください。CDC ストリームの料金の詳細については、「[Aurora DSQL の料金ページ](https://aws.amazon.com/rds/aurora/dsql/pricing/)」を参照してください。
一般提供する前に、ストリームペイロードに新しいオペレーションタイプ (`"op": "u"` 更新用) を追加します。アプリケーションがこれらの変更を修正せずに処理できるようにするには、`after` ペイロードを適用して、認識されない `op` 値をすべてアップサートとして扱います。詳細については、「[CDC レコードについて](cdc-record-format.md)」を参照してください。
Aurora DSQL で CDC レコードの配信エラーが発生すると、ストリームは `IMPAIRED` ステータスに移行します。障害のあるストリームは引き続き他のレコードを処理して配信します。Aurora DSQL は失敗したレコードのみを再試行します。Aurora DSQL は、最も古い未配信レコードからのレプリケーション遅延を測定し、問題を解決するまで遅延は増加し続けます。Aurora DSQL は、未配信の変更を内部で 1 週間保持します。
このウィンドウ内に根本的な問題が解決されれば、次の再試行は成功し、エラー状態はクリアされ、ストリームは `ACTIVE` に戻ります。外部の問題 (IAM ポリシー、AWS KMS キー、Amazon Kinesis の容量など) を修正すると Aurora DSQL は自動的に再試行します。
レプリケーション遅延が失敗しきい値を超えると、ストリームは `FAILED` に移行します。
**重要**
失敗したストリームは復旧できません。失敗したストリームを削除して、新しいストリームを作成する必要があります。
## ストリームライフサイクル
ストリームは、ライフサイクル中に次のステータスに移行します。
+ **`CREATING`** – Aurora DSQL はストリームをセットアップしています。Aurora DSQL はまだ CDC レコードを配信していません。
+ **`ACTIVE`** – ストリームは動作し、CDC レコードをターゲットに配信します。
+ **`IMPAIRED`** – ストリームで、アクションを必要とする問題が発生しました。Aurora DSQL は、失敗したレコードをエクスポネンシャルバックオフを使用して再試行しますが、他のレコードは引き続き配信できます。Aurora DSQL は、最も古い未配信レコードからのレプリケーション遅延を測定し、問題を解決するまで遅延は増加し続けます。Aurora DSQL は、未配信の変更を内部で 1 週間バッファします。「[エラーコードのリファレンス](#cdc-failure-reasons)」を参照してください。
+ **`FAILED`** – ストリームで永続的なエラーが発生し、CDC レコードが配信されなくなりました。失敗したストリームは復旧できないため、削除する必要があります。ストリームがこの状態になる条件については、「[エラーコードのリファレンス](#cdc-failure-reasons)」を参照してください。
+ **`DELETING`** – Aurora DSQL はストリームリソースを削除しています。
+ **`DELETED`** – Aurora DSQL がストリームを削除しました。削除が完了すると、`GetStream` は `ResourceNotFoundException` を返します。
`GetStream` を呼び出して、いつでもストリームのステータスを表示できます。ストリームが `IMPAIRED` または `FAILED` の場合、レスポンスにはエラーコードとタイムスタンプを含む `statusReason` オブジェクトが含まれます。`GetStream` レスポンスフィールドの詳細については、「Amazon Aurora DSQL API リファレンス」の「[GetStream](https://docs.aws.amazon.com/aurora-dsql/latest/APIReference/API_GetStream.html)」を参照してください。
## ストリームの障害または失敗のトラブルシューティング
CDC ストリームに障害が発生したり、失敗した場合は、以下の手順に従います。ストリームが `FAILED` の場合、復元できません。ストリームを削除し、根本的な問題を解決して、新しいストリームを作成します。
1. **ストリームのステータスを取得します。**`GetStream` を呼び出して `status` フィールドを確認します。ステータスが `ACTIVE` の場合、ストリームは正常です。
```
aws dsql get-stream \
--cluster-identifier {{cluster-id}} \
--stream-identifier {{stream-id}} \
--region {{region}}
```
1. **エラーコードを確認します。**ステータスが `IMPAIRED` または `FAILED` の場合、レスポンスには `statusReason` オブジェクトが含まれます。`error` フィールドにはエラーコードが含まれています。
```
{
"status": "IMPAIRED",
"statusReason": {
"error": "KINESIS_THROUGHPUT_EXCEEDED",
"updatedAt": "2025-01-15T14:30:00Z"
}
}
```
1. **修復手順に従います。**ストリームが `IMPAIRED` の場合、次の表のエラーコードを確認し、推奨される修正を適用します。根本的な問題が解決されると、Aurora DSQL は自動的に再試行します。ストリームが `FAILED` の場合は、ストリームを削除して、問題を解決してから、新しいストリームを作成します。
## エラーコードのリファレンス
次の表は、各エラーコード、その原因、ストリームが復旧できるかどうか、および解決する手順を示しています。
| エラーコード | 原因 | 回復可能か? | 解決方法 |
| --- |--- |--- |--- |
| KINESIS\_THROUGHPUT\_EXCEEDED | Your Kinesis data stream exceeded its throughput limit, or AWS KMS throttled encryption operations on the Kinesis data stream, and the replication lag has grown. | Yes | Increase the number of shards on your Kinesis data stream, or switch to on-demand capacity mode. If the Kinesis data stream uses an AWS KMS customer managed key, verify that the key's request quota is large enough. After you increase capacity, Aurora DSQL retries automatically. |
| KINESIS\_STREAM\_NOT\_FOUND | The target Kinesis data stream no longer exists. | No | The stream transitions directly to FAILED. Delete the CDC stream and create a new one pointing to a valid Kinesis data stream. |
| ROLE\_ACCESS\_DENIED | Aurora DSQL can't assume the IAM role specified in the target definition. The AWS STS AssumeRole call returned アクセス拒否. | Yes | Verify the role's trust policy allows the Aurora DSQL service principal (dsql.amazonaws.com) to assume it. Verify the aws:SourceAccount and aws:SourceArn conditions match your cluster. For details, see [サービスロール信頼ポリシー](cdc-iam.md#cdc-iam-trust-policy). After you fix the trust policy, Aurora DSQL retries automatically. |
| KINESIS\_ACCESS\_DENIED | The assumed role doesn't have permission to write to the Kinesis data stream. Kinesis returned AccessDeniedException. | Yes | Add kinesis:PutRecord and kinesis:PutRecords permissions to the role's policy for the target Kinesis data stream Amazon Resource Name (ARN). After you fix the policy, Aurora DSQL retries automatically. |
| KINESIS\_KMS\_ACCESS\_DENIED | The assumed role doesn't have permission to use the AWS KMS key that encrypts the Kinesis data stream. This error covers AWS KMS access denial and invalid key states. | Yes | Verify the role has kms:GenerateDataKey permission on the AWS KMS key that the Kinesis data stream uses. Also verify that the AWS KMS key is in an enabled and valid state. This key is the encryption key on the Kinesis data stream, not the cluster's AWS KMS key. For details, see [サービスロールのアクセス許可ポリシー](cdc-iam.md#cdc-iam-permissions-policy). After you fix the permissions or key state, Aurora DSQL retries automatically. |
| KINESIS\_OVERSIZE\_RECORD | A CDC record exceeded the maximum record size configured on the Kinesis data stream. | Yes | Increase MaxRecordSizeInKiB on the Kinesis data stream to 10240 (10 MiB). You can update this setting on an existing Kinesis data stream without deleting it. After you increase the limit, Aurora DSQL retries the oversized record automatically and the stream transitions back to ACTIVE. |
| CLUSTER\_CMK\_INACCESSIBLE | The AWS KMS customer managed key that encrypts the Aurora DSQL cluster is inaccessible. | Yes | Verify the AWS KMS key policy and key state. Re-enable or restore access to the key. After the key becomes accessible again, the stream transitions back to ACTIVE. |
上記の表には、すべての `StreamFailureErrorCode` の値が一覧表示されています。`statusReason` レスポンスフィールドの詳細については、「[Amazon Aurora DSQL API リファレンス](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/CHAP_api_reference.html)」の「[GetStream](https://docs.aws.amazon.com/aurora-dsql/latest/APIReference/API_GetStream.html)」を参照してください。
## 障害のあるストリームの復旧
ほとんどのエラーは、まずストリームを `IMPAIRED` に移行させます。障害のあるストリームは、引き続き他のレコードを処理し、失敗したレコードを自動的に再試行します。`FAILED` ストリームは復元できません。ストリームを削除して新しいストリームを作成する必要があります。
+ **回復可能なエラーの場合:** 外部の問題 (IAM ポリシー、AWS KMS キー、Kinesis の容量、または Kinesis レコードサイズ制限) を修正します。次の再試行が成功すると、エラー状態が解消され、ストリームは `ACTIVE` に戻ります。
+ **`KINESIS_STREAM_NOT_FOUND` の場合:** ストリームは `FAILED` に直接移行します。失敗したストリームを削除し、有効な Kinesis データストリームを指す新しいストリームを作成します。
その他のすべてのエラーコードでは、問題を解決する前にレプリケーション遅延が失敗しきい値を超えると、ストリームは `IMPAIRED` から `FAILED` に移行します。失敗したストリームを `ACTIVE` に戻すことはできません。失敗したストリームを削除し、根本的な問題を解決してから、新しいストリームを作成します。
## ストリームの状態のモニタリング
CloudWatch メトリクスと `GetStream` API を使用して、ストリームの状態をモニタリングします。CloudWatch メトリクスは、CDC パイプラインのパフォーマンスを継続的に可視化し、`GetStream` はストリームに障害が発生したり、失敗した場合に特定のエラーコードを提供します。
`IsImpaired`、`BehindSourceLag`、`PublishedBytes`、`PublishedRecords` を含む CDC メトリクスの完全なリストについては、「[CDC ストリームの CloudWatch メトリクス](#cdc-cloudwatch-metrics)」を参照してください。`GetStream` レスポンスフィールドの詳細については、「Amazon Aurora DSQL API リファレンス」の「[GetStream](https://docs.aws.amazon.com/aurora-dsql/latest/APIReference/API_GetStream.html)」を参照してください。
## CDC ストリームの CloudWatch メトリクス
次の CloudWatch メトリクスを使用して、各 CDC ストリームの状態とスループットをモニタリングします。Aurora DSQL は、これらのメトリクスを `AWS/AuroraDSQL` 名前空間に `ClusterId` と `StreamId` というディメンションとともに発行します。最後のメトリクスは、ダウンストリームの読み取り遅延を測定する `AWS/Kinesis` 名前空間内の標準の Amazon Kinesis メトリクスです。
**注記**
Aurora DSQL は、使用状況と請求の追跡のために、`AWS/AuroraDSQL` 名前空間に `BytesStreamed` および `StreamDPU` メトリクスも発行しています。説明については、「[CDC ストリームメトリクス](cloudwatch-monitoring.md#cdc-stream-metrics)」を参照してください。
| メトリクス名 | 有用な統計 | 説明 |
| --- |--- |--- |
| IsImpaired | Maximum | Indicates whether the stream is impaired. The value is 1 when the stream is in the IMPAIRED state, and 0 when the stream is healthy. Aurora DSQL emits this metric continuously for each active or impaired stream. Use this metric to create a CloudWatch alarm that notifies you when a stream becomes impaired. |
| BehindSourceLag | Average | The delay, in milliseconds, between when a transaction commits in Aurora DSQL and when the CDC system processes the resulting record. A rising value indicates that the CDC pipeline is falling behind the write workload. |
| PublishedBytes | Sum | The total bytes of CDC records that Aurora DSQL wrote to the target during the period. Use this metric together with your Kinesis shard count to determine whether you've provisioned enough write capacity. |
| PublishedRecords | Sum | The total number of CDC records that Aurora DSQL wrote to the target during the period. Each committed row change produces one record. |
| GetRecords.IteratorAgeMilliseconds (AWS/Kinesis) | Average | A standard Kinesis metric that reports the age of the last record read from the Kinesis data stream by your downstream app, in milliseconds. Use the StreamName dimension. A rising value indicates that your downstream app can't keep up with the rate at which Aurora DSQL writes CDC records to Kinesis. |
Aurora DSQL コンソールの **[モニタリング]** タブには、`BehindSourceLag` (CDC ソースのレイテンシー) と `GetRecords.IteratorAgeMilliseconds` (Kinesis リーダーのラグ) を組み合わせた **[エンドツーエンドの平均レイテンシー]** 値が表示されます。この結合値は、データベースへのコミットからダウンストリーム読み取りまでの遅延の合計を表します。
## モニタリングのベストプラクティス
次のプラクティスを使用して、ダウンストリームシステムに影響を与える前に CDC パイプラインの問題を検出して解決します。
**`BehindSourceLag` にアラームを設定する**
`BehindSourceLag` がワークロードにとって重要なしきい値を超えたときに発生する CloudWatch アラームを作成します。例えば、1 分間のレイテンシー目標に対して 60 秒を設定します。このメトリクスの継続的なな増加は、CDC パイプラインが遅れていることを意味します。遅延が失敗しきい値に達すると、ストリームは FAILED に移行します。トレンドをキャッチすることで、ストリームが劣化する前に Kinesis 容量を増やしたり、スループットのボトルネックを調査したりする時間を確保できます。
**Kinesis 側で `GetRecords.IteratorAgeMilliseconds` をモニタリングする**
Aurora DSQL がレコードを時間どおりに配信しても、ダウンストリームアプリケーションが遅延する可能性があります。`GetRecords.IteratorAgeMilliseconds` (`AWS/Kinesis` 名前空間のディメンション `StreamName`) で CloudWatch アラームを作成して、ダウンストリームの遅延を個別に検出します。このメトリクスが増加して、`BehindSourceLag` が横ばいに保たれる場合、ボトルネックは Aurora DSQL ではなくダウンストリームアプリケーションにあります。
**`PublishedBytes` を Kinesis シャード容量と比較して追跡する**
各 Kinesis シャードは、書き込みに対して 1 秒あたり最大 1 MiB をサポートします。1 分あたりの `PublishedBytes` の合計を、シャード書き込み容量 (シャード数 × 60 MiB/分) の合計と比較します。使用量が 80% に近づいた場合は、スロットリングが `KINESIS_THROUGHPUT_EXCEEDED` をトリガーする前に、シャードを追加するか、オンデマンドキャパシティモードに切り替えます。
**`IsImpaired` アラームで即時に障害を検出する**
1 つの評価期間で `IsImpaired` の Maximum が `1` 以上になったときに発生する CloudWatch アラームを作成します。これにより、API をポーリングしなくても、ストリームが `IMPAIRED` 状態になったときに、直接シグナルを受け取ることができます。アラームが発生したら、`GetStream` を呼び出して `statusReason.error` フィールドを読み取り、「[ストリームの障害または失敗のトラブルシューティング](#cdc-troubleshooting)」の修復ステップに従います。
**`GetStream` をポーリングして詳細ステータスを確認する**
`IsImpaired` メトリクスはストリームに障害があることを知らせますが、`GetStream` API は特定のエラーコードとタイムスタンプを提供します。`GetStream` をスケジュールに基づいて (5 分ごとなど) または `IsImpaired` アラームに応じてポーリングします。`statusReason.error` フィールドには、何が問題だったかが示されます。これを「[ストリームの障害または失敗のトラブルシューティング](#cdc-troubleshooting)」のトラブルシューティングステップと組み合わせて、迅速に解決します。
**ダッシュボードを使用してメトリクスを関連付ける**
`IsImpaired`、`BehindSourceLag`、`PublishedRecords`、`PublishedBytes`、および `GetRecords.IteratorAgeMilliseconds` を並べて表示する CloudWatch ダッシュボードを作成します。これらのメトリクスを相関させることで、CDC パイプラインの問題 (`BehindSourceLag` の上昇) とダウンストリームの読み取りの問題 (`BehindSourceLag` が安定していて `IteratorAge` が上昇) を区別できます。