# 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](https://aws.amazon.com/service-terms/). Para saber mais sobre precificação para fluxos de CDC, consulte a [página de precificação do Aurora DSQL](https://aws.amazon.com/rds/aurora/dsql/pricing/).
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](cdc-record-format.md).
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](#cdc-failure-reasons).
+ **`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](#cdc-failure-reasons) 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](https://docs.aws.amazon.com/aurora-dsql/latest/APIReference/API_GetStream.html) 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}}
```
1. **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"
}
}
```
1. **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](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 [Política de permissões do perfil de serviço](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. |
A tabela anterior lista todos os valores `StreamFailureErrorCode`. Para obter detalhes sobre o campo de resposta `statusReason`, consulte [GetStream](https://docs.aws.amazon.com/aurora-dsql/latest/APIReference/API_GetStream.html) na [Referência de API do Amazon Aurora DSQL](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/CHAP_api_reference.html).
## 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](#cdc-cloudwatch-metrics). Para obter mais detalhes sobre os campos de resposta `GetStream`, consulte [GetStream](https://docs.aws.amazon.com/aurora-dsql/latest/APIReference/API_GetStream.html) 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](cloudwatch-monitoring.md#cdc-stream-metrics).
| 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](#cdc-troubleshooting).
**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](#cdc-troubleshooting) 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).