View a markdown version of this page

Monitoramento de fluxos - Amazon Aurora DSQL
Ciclo de vida do fluxoSolução de problemas em um fluxo danificado ou com falhaReferência de código de erroRecuperação de um fluxo danificadoMonitoramento da integridade do fluxoMétricas do CloudWatch para fluxos de CDCPráticas recomendadas de monitoramento

Monitoramento de fluxos

Importante

Esse recurso é fornecido como visualização prévia da AWS e está sujeito a alterações. Para obter mais informações, consulte a seção 2, Versões beta e visualizações prévias, nos Termos de serviço da AWS. Para saber mais sobre precificação para fluxos de CDC, consulte a página de precificação do Aurora DSQL.

Antes da disponibilidade geral, adicionaremos novos tipos de operação ("op": "u" para atualizações) à carga útil do fluxo. Para garantir que seu aplicativo processe essas alterações sem modificações, trate qualquer valor op não reconhecido como um acréscimo aplicando a carga útil after. Para mais detalhes, consulte Noções básicas sobre os registros de CDC.

Quando o Aurora DSQL encontra um erro ao entregar um registro de CDC, o fluxo muda para o status IMPAIRED. Um fluxo danificado continua processando e entregando outros registros; o Aurora DSQL tenta novamente somente o registro com falha. O Aurora DSQL mede o atraso de replicação em relação ao registro mais antigo não entregue, e o atraso aumenta até que o problema seja resolvido. O Aurora DSQL retém as alterações não entregues internamente por uma semana.

Se você resolver o problema subjacente nessa janela, a próxima tentativa será bem-sucedida, o estado de erro será eliminado e o fluxo voltará para ACTIVE. Corrija o problema externo (política do IAM, chave do AWS KMS, capacidade do Amazon Kinesis etc.), e o Aurora DSQL tentará outra vez automaticamente.

Se o atraso de replicação exceder o limite de falha, o fluxo mudará para FAILED.

Importante

Um fluxo com falha não pode ser recuperado. Nesse caso, você deverá excluir o fluxo com falha e criar um novo.

Ciclo de vida do fluxo

Um fluxo passa pelos seguintes status durante o ciclo de vida:

  • CREATING: o Aurora DSQL está configurando o fluxo. O Aurora DSQL ainda não fornece registros de CDC.

  • ACTIVE: o fluxo está funcionando e entregando registros de CDC ao destino.

  • IMPAIRED: o fluxo encontrou um problema que exige sua ação. O Aurora DSQL tenta novamente o registro com falha com um recuo exponencial, embora outros registros possam continuar sendo entregues. O Aurora DSQL mede o atraso de replicação em relação ao registro mais antigo não entregue, e o atraso aumenta até que o problema seja resolvido. O Aurora DSQL armazena internamente as alterações não entregues por uma semana. Consulte Referência de código de erro.

  • FAILED: o fluxo encontrou um erro persistente e não está mais entregando registros de CDC. Um fluxo com falha não pode ser recuperado e deve ser excluído. Consulte Referência de código de erro para conferir as condições que fazem com que um fluxo entre nesse estado.

  • DELETING: o Aurora DSQL está removendo os recursos do fluxo.

  • DELETED: o Aurora DSQL excluiu o fluxo. Após a conclusão da exclusão, GetStream retorna para ResourceNotFoundException.

Chame GetStream para ver o status do fluxo a qualquer momento. Quando o fluxo é IMPAIRED ou FAILED, a resposta inclui um objeto statusReason com o código de erro e o carimbo de data/hora. Para obter mais detalhes sobre os campos de resposta GetStream, consulte GetStream na Referência de API do Amazon Aurora DSQL.

Solução de problemas em um fluxo danificado ou com falha

Siga estas etapas quando um fluxo de CDC for comprometido ou falhar. Se o fluxo estiver FAILED, você não poderá recuperá-lo. Exclua o fluxo, resolva o problema subjacente e crie um novo.

  1. Obtenha o status do fluxo. Chame GetStream e verifique o campo status. Se o status for ACTIVE, o fluxo está íntegro.

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

  2. Leia o código de erro. Se o status for IMPAIRED ou FAILED, a resposta incluirá um objeto statusReason. O campo error contém o código de erro.

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

  3. Siga a correção. Se o stream estiver IMPAIRED, consulte o código de erro na tabela a seguir e aplique a correção recomendada. O Aurora DSQL tenta outra vez automaticamente depois que você resolve o problema subjacente. Se o fluxo estiver FAILED, exclua-o, resolva o problema e crie um novo fluxo.

Referência de código de erro

A tabela a seguir descreve cada código de erro, a causa, se o fluxo pode ser recuperado e as etapas para resolvê-lo.

Código de erro Causa Recuperável? Como resolver
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 Política de confiança do perfil de serviço. 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 Política de permissões do perfil de serviço. 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.

A tabela anterior lista todos os valores StreamFailureErrorCode. Para obter detalhes sobre o campo de resposta statusReason, consulte GetStream na Referência de API do Amazon Aurora DSQL.

Recuperação de um fluxo danificado

A maioria dos erros primeiro muda o fluxo para IMPAIRED. Um fluxo danificado continua processando outros registros e repete o registro com falha automaticamente. Um fluxo FAILED não é recuperável. Você deve excluí-lo e criar outro.

  • Para erros recuperáveis: corrija o problema externo (política do IAM, chave do AWS KMS, capacidade do Kinesis ou limite de tamanho de registro do Kinesis). A próxima tentativa bem-sucedida elimina o estado de erro e faz a transição do fluxo de volta para ACTIVE.

  • Para KINESIS_STREAM_NOT_FOUND: o fluxo muda diretamente para FAILED. Exclua o fluxo com falha e crie um novo que aponte para um fluxo de dados do Kinesis válido.

Para todos os outros códigos de erro, se o atraso de replicação exceder o limite de falha antes de você resolver o problema, o fluxo mudará de IMPAIRED para FAILED. Um fluxo com falha não pode voltar para ACTIVE. Exclua o fluxo com falha, resolva o problema subjacente e crie um novo.

Monitoramento da integridade do fluxo

Use as métricas do CloudWatch e a API GetStream para monitorar a integridade do fluxo. As métricas do CloudWatch fornecem visibilidade contínua do desempenho do pipeline de CDC e GetStream fornece o código de erro específico quando um fluxo é danificado ou falha.

Para obter a lista completa das métricas de CDC, incluindo IsImpaired, BehindSourceLag, PublishedBytes e PublishedRecords, consulte Métricas do CloudWatch para fluxos de CDC. Para obter mais detalhes sobre os campos de resposta GetStream, consulte GetStream na Referência de API do Amazon Aurora DSQL.

Métricas do CloudWatch para fluxos de CDC

Use as métricas do CloudWatch a seguir para monitorar a integridade e o throughput de cada fluxo de CDC. O Aurora DSQL publica essas métricas no namespace AWS/AuroraDSQL com as dimensões ClusterId e StreamId. A última métrica é uma métrica padrão do Amazon Kinesis no namespace AWS/Kinesis que mede o atraso de leitura posterior.

nota

O Aurora DSQL também publica as métricas BytesStreamed e StreamDPU no namespace AWS/AuroraDSQL para rastreamento de uso e faturamento. Para obter descrições, consulte Métricas de fluxo de CDC.

Nome da métrica Estatística útil Descrição
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.

A guia Monitoramento do console do Aurora DSQL mostra um valor Latência média de ponta a ponta que combina BehindSourceLag (latência da origem de CDC) e GetRecords.IteratorAgeMilliseconds (atraso do leitor do Kinesis). Esse valor combinado representa o atraso total da confirmação do banco de dados até a leitura posterior.

Práticas recomendadas de monitoramento

Use as práticas a seguir para detectar e resolver problemas de pipeline de CDC antes que eles afetem seus sistemas downstream.

Configurar alarmes em BehindSourceLag

Crie um alarme do CloudWatch que é acionado quando BehindSourceLag excede um limite importante para sua workload. Por exemplo, defina 60 segundos para uma meta de latência de um minuto. Um aumento sustentado nessa métrica significa que o pipeline de CDC está ficando para trás. Se o atraso atingir o limite de falha, o fluxo mudará para FAILED. Perceber a tendência dá tempo para aumentar a capacidade do Kinesis ou investigar gargalos de throughput antes que o fluxo se degrade.

Monitorar GetRecords.IteratorAgeMilliseconds no lado do Kinesis

Mesmo quando o Aurora DSQL entrega registros no prazo, seu aplicativo downstream pode ficar para trás. Crie um alarme do CloudWatch em GetRecords.IteratorAgeMilliseconds (no namespace AWS/Kinesis, dimensão StreamName) para detectar o atraso no downstream de forma independente. Se essa métrica aumentar e BehindSourceLag permanecer estável, o gargalo está no seu aplicativo downstream, não no Aurora DSQL.

Acompanhar PublishedBytes com relação à capacidade de fragmentos do Kinesis

Cada fragmento do Kinesis suporta até 1 MiB por segundo para gravações. Compare a soma por minuto de PublishedBytes com sua capacidade total de gravação de fragmentos (número de fragmentos × 60 MiB por minuto). Se o uso se aproximar de 80%, adicione fragmentos ou mude para o modo de capacidade sob demanda antes do controle de utilização acionar KINESIS_THROUGHPUT_EXCEEDED.

Alarme em IsImpaired para detecção instantânea de comprometimento

Crie um alarme do CloudWatch que será acionado quando o IsImpaired máximo for maior ou igual a 1 por um período de avaliação. Isso fornece um sinal direto quando um fluxo entra no estado IMPAIRED, sem pesquisar a API. Depois que o alarme disparar, chame GetStream para ler o campo statusReason.error e siga as etapas de correção em Solução de problemas em um fluxo danificado ou com falha.

Pesquisar GetStream para status detalhado

A métrica IsImpaired indica que um fluxo está comprometido, mas a API GetStream fornece o código de erro e o carimbo de data/hora específicos. Pesquise GetStream de acordo com uma programação (por exemplo, a cada cinco minutos) ou em resposta a um alarme IsImpaired. O campo statusReason.error mostra o que deu errado. Combine isso com as etapas de solução de problemas em Solução de problemas em um fluxo danificado ou com falha para uma resolução rápida.

Usar painéis para correlacionar métricas

Crie um painel do CloudWatch que mostre IsImpaired, BehindSourceLag, PublishedRecords, PublishedBytes e GetRecords.IteratorAgeMilliseconds lado a lado. A correlação dessas métricas ajuda a distinguir entre um problema de pipeline de CDC (aumentando BehindSourceLag) e um problema de leitura posterior (aumentando IteratorAge com BehindSourceLag estável).