# Migração para o formato de tabela única para KCL 3.5.x\+
A partir da KCL 3.5, você pode consolidar todos os metadados do DynamoDB em uma única tabela de concessão usando o **formato de tabela única**. Por padrão, a KCL 3.x cria três tabelas do DynamoDB para cada aplicação: a tabela de concessão, a tabela de métricas de operador e a tabela de estado de coordenador. O formato de tabela única reduz essas três tabelas para uma, o que ajuda a evitar os limites de tabelas no nível da conta do DynamoDB.
## Como funciona o formato de tabela única
No formato de tabela única, a KCL armazena as métricas de operador e as entradas de estado do coordenador na tabela de concessão junto com as entradas de concessão. Cada item inclui um atributo `entityType` que distingue os diferentes tipos de registro.
As métricas de operador e os itens de estado do coordenador usam a mesma estrutura de chave primária da tabela de concessão, mas incluem um valor `entityType` diferente. Esse atributo permite que a KCL identifique a finalidade de cada item durante as verificações de tabela.
Cada componente da KCL filtra as entradas necessárias para a lógica de negócios com base no atributo `entityType`. Por exemplo, o Lease Assignment Manager (LAM) filtra as entradas de concessão e de métricas de operador para realizar a atribuição de concessão.
## Configurar o formato de tabela única
A forma como você habilita o formato de tabela única depende da sua versão atual da KCL:
+ **Se você estiver usando a KCL 2.x:** siga o guia de migração atualizado para atualizar para a KCL 3.5. O formato de tabela única é usado por padrão para novas migrações da versão 2.x para a 3.5.
+ **Se você estiver usando a KCL 3.0–3.4:** execute uma implantação em duas fases para migrar para o formato de tabela única. Confira as etapas de configuração e migração a seguir.
Para clientes existentes da KCL 3.x, defina a opção de configuração `migrateAllEntitiesToLeaseTable` em `CoordinatorConfig`. Essa opção controla se a KCL armazena todos os tipos de entidade de metadados na tabela de concessão.
**Valores de configuração para `migrateAllEntitiesToLeaseTable`**
| Valor | Padrão | Efeito |
| --- | --- | --- |
| false | Sim | A KCL usa tabelas separadas para métricas de operador e estado do coordenador. O código do aplicativo oferece suporte ao formato de tabela única, mas não o ativa. |
| true | Não | A KCL começa a gravar as métricas de operador e os dados do estado do coordenador na tabela de concessão. Defina esse valor na implantação da Fase 2 depois que `TableMigrationStatus` atingir `DEPLOYED` e você tiver verificado que não há regressões. |
A migração da KCL 3.x para o formato de tabela única requer uma implantação em duas fases:
1. **Fase 1:** implante o código KCL 3.5 atualizado com `migrateAllEntitiesToLeaseTable` definido como `false` (o padrão). Isso instala o novo código que oferece suporte ao formato de tabela única, mas não ativa a migração.
1. **Fase 2:** depois que todos os operadores executarem o novo código e o `TableMigrationStatus` atingir `DEPLOYED`, e você tiver verificado que não há regressões, implante novamente com `migrateAllEntitiesToLeaseTable` definido como `true` para iniciar a migração.
## Estados de migração
A `TableMigrationStateMachine` gerencia a transição do formato de várias tabelas para o formato de tabela única. A KCL rastreia o estado atual da migração em uma entrada separada do estado do coordenador chamada `TableMigration3.5` na tabela de estado do coordenador. Para ver a lista completa de estados, transições e descrições, consulte [Estados de migração de tabela única da KCL](https://github.com/awslabs/amazon-kinesis-client/blob/master/amazon-kinesis-client/src/main/java/software/amazon/kinesis/coordinator/migration/TableMigrationStatus.java) no site do GitHub.
**Estados de migração em formato de tabela única**
| Estado | Descrição | Condição de transição |
| --- | --- | --- |
| INIT | Estado inicial. Todos os operadores estão emitindo o código mínimo de suporte nas estatísticas de métricas de operador. Os operadores continuam emitindo métricas de operador na tabela legada e lendo as métricas de operador e o estado do coordenador nas tabelas legada e de concessão. Funcionalmente, não há diferença entre INIT e DEPLOYED. | Todos os operadores emitem o código mínimo de suporte de forma constante durante o tempo de incorporação. O aplicativo está pronto para passar para a implantação da Fase 2. |
| DEPLOYED | Todos os operadores foram implantados com o novo código (Fase 1 concluída). O aplicativo oferece suporte ao formato de tabela única, mas não o ativou. | A implantação da Fase 2 começa com `migrateAllEntitiesToLeaseTable` definido como `true`. |
| PENDING | Todos os operadores executam o novo código. A KCL migra dados das métricas de operador e das tabelas de estado do coordenador para a tabela de concessão. | Um tempo de incorporação padrão de 24 horas é decorrido após a conclusão da migração. |
| COMPLETE | A migração foi concluída. A KCL usa a tabela de concessão exclusivamente para todas as leituras e gravações. As antigas métricas de operador e as tabelas de estado do coordenador não são mais usadas. | Estado de terminal. Nenhuma outra transição ocorre. |
Para obter informações detalhadas sobre cada estado, condições de transição e o comportamento completo da máquina de estado, consulte [Máquina de estado de migração de tabela única da KCL](https://github.com/awslabs/amazon-kinesis-client/blob/master/amazon-kinesis-client/src/main/java/software/amazon/kinesis/coordinator/migration/TableMigrationStatus.java) no site do GitHub.
**nota**
O tempo de incorporação padrão entre os estados PENDING e COMPLETE é de 24 horas, mas você pode configurá-lo em até uma semana. Durante esse período, a KCL usa a tabela de concessão para todas as leituras e gravações, mas não exclui as tabelas antigas. Você deve excluir manualmente as tabelas antigas de métricas de operador e de estado do coordenador depois de confirmar que a migração foi bem-sucedida. A KCL não exclui essas tabelas automaticamente.
## Métricas de migração
Com a KCL, você pode monitorar o andamento e a integridade da migração de tabela única usando as métricas do CloudWatch. Use essas métricas para confirmar se os operadores adotaram o novo código e para acompanhar a migração à medida que ela percorre os estados. Você também pode detectar falhas de leitura, gravação ou exclusão do DynamoDB durante a migração. As tabelas a seguir agrupam as métricas pela operação da KCL (dimensão de métrica) que as emite e por quando cada métrica é emitida.
O operador líder eleito emite continuamente as seguintes métricas, independentemente de uma migração estar em andamento:
**Métricas emitidas pelo líder sempre**
| Operation | Métrica | Unidade | Descrição |
| --- | --- | --- | --- |
| `TableMigration` | `StatusOrdinal` | Nenhum | Ordinal do status de migração atual do DynamoDB: `0` = UNKNOWN, `1` = INIT, `2` = DEPLOYED, `3` = PENDING, `4` = COMPLETE. |
| `WorkerMetrics` | `FleetMinSupportCode` | Nenhum | Código mínimo de suporte em todos os operadores proprietários de concessão na frota. |
O operador líder eleito emite as seguintes métricas somente enquanto uma migração está em andamento:
**Métricas emitidas pelo líder durante a migração**
| Operation | Métrica | Unidade | Descrição |
| --- | --- | --- | --- |
| `TableMigration` | `Phase1Worker` | Contagem | Número de operadores que oferecem suporte à operação com uma única tabela do DynamoDB, mas que ainda não migraram para usar a tabela única. |
| `TableMigration` | `Phase2Worker` | Contagem | Número de operadores que migraram para a gravação em uma única tabela. Esses operadores ainda podem ler de várias tabelas até que a migração da tabela seja concluída. |
| `TableMigration` | `PrePhase1Worker` | Contagem | Número de operadores em uma versão anterior à 3.5 que não oferecem suporte à operação em uma única tabela do DynamoDB. |
| `TableMigration` | `WriteFault` | Contagem | `1` em caso de falha de gravação do DynamoDB, `0` em caso de sucesso. |
| `TableMigration` | `DeleteFault` | Contagem | `1` em caso de falha de exclusão do DynamoDB, `0` em caso de sucesso. |
| `TableMigration` | `CompletionFault` | Contagem | `1` quando a gravação transacional do status `COMPLETE` falha, `0` em caso de sucesso. |
| `TableMigrationAsyncMove` | `Success` | Contagem | `1` em uma movimentação transacional bem-sucedida das entradas do CoordinatorState, `0` em caso de falha. |
| `TableMigrationAsyncMove` | `Time` | Milissegundos | Duração da operação de movimentação assíncrona. |
| `TableMigrationAsyncMove` | `BatchCount` | Contagem | Número de lotes que foram movidos. |
Todos os operadores emitem as seguintes métricas enquanto a migração está em andamento:
**Métricas emitidas por todos os operadores durante a migração**
| Operation | Métrica | Unidade | Descrição |
| --- | --- | --- | --- |
| `TableMigration` | `ReadFault` | Contagem | `1` em caso de falha na leitura do `TableMigrationState` do DynamoDB, `0` em caso de sucesso. |
| `TableMigration` | `Time` | Milissegundos | Duração da execução da máquina de estado. |
| `TableMigrationInitialize` | `Success` | Contagem | `1` em uma inicialização bem-sucedida, `0` em caso de falha. |
| `TableMigrationInitialize` | `Time` | Milissegundos | Duração da operação de inicialização. |
Use essas métricas para decidir quando avançar na migração. Quando `StatusOrdinal` é sempre `2` (DEPLOYED) e `PrePhase1Worker` é `0`, todos os operadores oferecem suporte ao formato de tabela única, e você pode passar para a fase 2 da implantação da migração de tabelas. Depois que `StatusOrdinal` atingir `4` (COMPLETE), você pode excluir com segurança as tabelas herdadas.
## Considerações sobre reversão
O suporte à reversão depende do `TableMigrationStatus` atual:
+ **Durante a Fase 1** (`TableMigrationStatus` é `DEPLOYED` ou ainda não foi definido): você pode reverter com segurança para a versão anterior. O novo código é executado em um modo compatível com versões anteriores e nenhum dado foi gravado em entradas que não sejam de concessão na tabela de concessão.
+ **Durante a Fase 2** (`TableMigrationStatus` é `DEPLOYED` ou `PENDING`): você pode voltar para a Fase 1. Os operadores voltam a usar as tabelas legadas (formato de várias tabelas) para métricas de operador e estado do coordenador. A migração é desfeita.
+ **Após o estado COMPLETE**: a reversão não é suportada. A KCL usa somente a tabela de concessão para todas as entidades. Mesmo que o código volte para a Fase 1, o operador continua usando a tabela de concessão para todas as entidades e a configuração é ignorada.
**Atenção**
Depois que a migração atinge o estado COMPLETE, o aplicativo opera exclusivamente no modo de tabela única. A configuração `migrateAllEntitiesToLeaseTable` é ignorada e a KCL não volta a usar tabelas separadas. O tempo de incorporação antes de passar para COMPLETE deve ser suficiente porque, depois disso, mesmo uma reversão de código não volta para várias tabelas.
## Práticas recomendadas
Siga estas práticas recomendadas ao adotar o formato de tabela única:
+ Após a implantação da Fase 1, verifique se a entrada do estado do coordenador `TableMigration3.5` atinge o status `DEPLOYED`. Verifique se não há regressões antes de prosseguir para a Fase 2.
+ Monitore o `TableMigrationStatus` na entrada de estado do coordenador `TableMigration3.5` para acompanhar o progresso nos estados DEPLOYED, PENDING e COMPLETE. O status é armazenado na tabela de estado do coordenador como uma entrada separada (não na tabela de concessão) até que a migração atinja COMPLETE.
+ O tempo de incorporação antes de passar para COMPLETE deve ser suficiente porque, depois disso, mesmo uma reversão de código não volta para várias tabelas. O aplicativo funciona somente no modo de tabela única.
+ Depois que a migração atingir o estado COMPLETE, exclua manualmente as antigas métricas de operador e tabelas de estado do coordenador. A KCL não exclui essas tabelas automaticamente — ela apenas deixa de usá-las.
+ Se você tiver configurado `CoordinatorConfig.coordinatorStateTableConfig` ou `LeaseManagementConfig.workerUtilizationAwareAssignmentConfig.workerMetricsTableConfig`, poderá remover essas configurações após a conclusão da migração. Essas configurações estão obsoletas na KCL 3.5 e em versões posteriores.