View a markdown version of this page

监控流 - Amazon Aurora DSQL
流生命周期对受损或失败的流进行问题排查错误代码参考恢复受损的流监控流运行状况CDC 流的 CloudWatch 指标监控最佳实践

监控流

重要

此功能以 AWS 预览版形式提供，可能会发生变化。有关更多信息，请参阅 AWS Service Terms 中的第 2 部分“Betas and Previews”。要了解有关 CDC 流的定价的更多信息，请参阅 Aurora DSQL 定价页面。

在正式发布之前，我们将向流有效载荷添加新的操作类型（"op": "u" 表示更新）。要确保您的应用程序无需修改即可处理这些更改，请通过应用 after 有效载荷将任何无法识别的 op 值视为更新插入。有关详细信息，请参阅了解 CDC 记录。

如果 Aurora DSQL 在传输 CDC 记录时遇到错误，流会转换为 IMPAIRED 状态。受损的流会继续处理并传输其他记录，Aurora DSQL 仅重试失败的记录。Aurora DSQL 会根据最早的未传输记录来计算复制延迟，在该问题得到解决之前，延迟会不断增加。Aurora DSQL 会在内部将未传输的更改保留一周的时间。

如果您能够在此时段内解决根本问题，则下次重试将成功，错误状态将清除，并且流将转换回 ACTIVE 状态。修复外部问题（IAM 策略、AWS KMS 密钥、Amazon Kinesis 容量等）后，Aurora DSQL 会自动重试。

如果复制延迟超过失败阈值，流将转换为 FAILED 状态。

重要

失败的流无法恢复。您必须删除失败的流，然后创建一个新流。

流生命周期

流在其生命周期中会经历以下状态：

  • CREATING：Aurora DSQL 正在设置流，此时尚未传输 CDC 记录。

  • ACTIVE：流处于正常运行状态，并且正在向目标传输 CDC 记录。

  • IMPAIRED：流遇到了需要您处理的问题。Aurora DSQL 会以指数回退的方式重试失败的记录，而其他记录可继续传输。Aurora DSQL 会根据最早的未传输记录来计算复制延迟，在该问题得到解决之前，延迟会不断增加。Aurora DSQL 会在内部对未传输的更改进行缓存处理，时长为一周。请参阅错误代码参考。

  • FAILED：流遇到了持续性错误，不再传输 CDC 记录。失败的流无法恢复，您必须将其删除。有关导致流进入此状态的条件，请参阅错误代码参考。

  • DELETING：Aurora DSQL 正在移除流资源。

  • DELETED：Aurora DSQL 已删除流。删除操作完成后，GetStream 将返回 ResourceNotFoundException。

可随时调用 GetStream 来查看流状态。当流处于 IMPAIRED 或 FAILED 状态时，响应将包含一个带错误代码和时间戳的 statusReason 对象。有关 GetStream 响应字段的更多详细信息，请参阅《Amazon Aurora DSQL API 参考》中的 GetStream。

对受损或失败的流进行问题排查

当 CDC 流受损或失败时，请按照以下步骤操作。如果流处于 FAILED 状态，则无法将其恢复；请删除流，解决根本问题，然后创建一个新流。

  1. 获取流状态。调用 GetStream 并确认 status 字段。如果状态为 ACTIVE，则表示流运行正常。

    aws dsql get-stream \
  --cluster-identifier cluster-id \
  --stream-identifier stream-id \
  --region region

  2. 读取错误代码。如果状态为 IMPAIRED 或 FAILED，则响应将包含一个 statusReason 对象。error 字段包含错误代码。

    {
    "status": "IMPAIRED",
    "statusReason": {
        "error": "KINESIS_THROUGHPUT_EXCEEDED",
        "updatedAt": "2025-01-15T14:30:00Z"
    }
}

  3. 按照修复步骤进行操作。如果流处于 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 AccessDenied. 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 服务角色信任策略. 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 服务角色权限策略. 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 参考》中的 GetStream。

恢复受损的流

大多数错误首先会导致流转换为 IMPAIRED 状态。受损的流会继续处理其他记录，并自动重试失败的记录。FAILED 流无法恢复，您必须将其删除，然后创建一个新流。

  • 对于可恢复的错误：修复外部问题（IAM 策略、AWS KMS 密钥、Kinesis 容量或 Kinesis 记录大小限制）。下一次成功的重试会清除错误状态并将流转换回 ACTIVE 状态。

  • 对于 KINESIS_STREAM_NOT_FOUND：流会直接转换到 FAILED 状态。删除失败的流，然后创建一个指向有效 Kinesis 数据流的新流。

对于所有其他错误代码，如果在您解决问题之前，复制延迟超过了失败阈值，则流将从 IMPAIRED 状态转换为 FAILED 状态。失败的流无法转换回 ACTIVE 状态。删除失败的流，解决根本问题，然后创建一个新流。

监控流运行状况

使用 CloudWatch 指标和 GetStream API 监控流运行状况。CloudWatch 指标提供对 CDC 管道性能的持续可见性，而在流受损或失败时，GetStream 会提供特定的错误代码。

有关 CDC 指标的完整列表（包括 IsImpaired、BehindSourceLag、PublishedBytes 和 PublishedRecords），请参阅 CDC 流的 CloudWatch 指标。有关 GetStream 响应字段的更多详细信息，请参阅《Amazon Aurora DSQL API 参考》中的 GetStream。

CDC 流的 CloudWatch 指标

使用以下 CloudWatch 指标可监控每个 CDC 流的运行状况和吞吐量。Aurora DSQL 在 AWS/AuroraDSQL 命名空间中发布这些指标，并使用 ClusterId 和 StreamId 维度。最后一个指标是 AWS/Kinesis 命名空间中的标准 Amazon Kinesis 指标，用于测量下游读取延迟。

注意

Aurora DSQL 还在 AWS/AuroraDSQL 命名空间中发布 BytesStreamed 和 StreamDPU 指标，用于跟踪使用情况和计费。有关说明，请参阅 CDC 流指标。

指标名称 有用的统计数据 说明
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 设置警报

创建一个 CloudWatch 警报，该警报会在 BehindSourceLag 超过与您的工作负载相关的阈值时触发。例如，设置 60 秒作为一分钟延迟目标。如果该指标持续增长，则意味着 CDC 管道的性能已落后。如果延迟达到失败阈值，则流将转换为 FAILED 状态。及时发现这一趋势可以为您争取时间，在流性能降级之前增加 Kinesis 容量或排查吞吐量瓶颈问题。

在 Kinesis 端监控 GetRecords.IteratorAgeMilliseconds

即使 Aurora DSQL 按时传输记录，您的下游应用程序的性能也可能落后。针对 GetRecords.IteratorAgeMilliseconds（在 AWS/Kinesis 命名空间中，维度为 StreamName）创建 CloudWatch 警报以单独检测下游延迟。如果该指标上升而 BehindSourceLag 保持平稳，则瓶颈出现在下游应用程序，而非 Aurora DSQL 中。

根据 Kinesis 分片容量跟踪 PublishedBytes

每个 Kinesis 分片支持最多每秒 1 MiB 的写入。将每分钟的 PublishedBytes 总和与分片写入总容量（分片数 × 每分钟 60 MiB）进行比较。如果使用量接近 80%，请在节流触发 KINESIS_THROUGHPUT_EXCEEDED 之前，添加分片或切换到按需容量模式。

针对 IsImpaired 设置警报以实现即时受损检测

创建一个 CloudWatch 警报，当 IsImpaired 最大值在一个评估期内大于或等于 1 时，将触发该警报。这可以在流进入 IMPAIRED 状态时为您提供直接信号，而无需轮询 API。在该警报触发后，调用 GetStream 以读取 statusReason.error 字段，并按照对受损或失败的流进行问题排查中的修复步骤进行操作。

轮询 GetStream 以获取详细状态

IsImpaired 指标会告知您流处于受损状态，而 GetStream API 提供了特定的错误代码和时间戳。按计划（例如，每五分钟一次）或在收到 IsImpaired 警报后轮询 GetStream。statusReason.error 字段会告知您出了什么问题。将这些信息与对受损或失败的流进行问题排查中的问题排查步骤相结合，快速解决问题。

使用控制面板来关联指标

创建一个 CloudWatch 控制面板来并排显示 IsImpaired、BehindSourceLag、PublishedRecords、PublishedBytes 和 GetRecords.IteratorAgeMilliseconds。关联这些指标有助于区分 CDC 管道问题（BehindSourceLag 上升）和下游读取问题（IteratorAge 上升但 BehindSourceLag 保持稳定）。