Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.
# Migrazione al formato a tabella singola per KCL 3.5.x\+
**A partire da KCL 3.5, puoi consolidare tutti i metadati DynamoDB in un'unica tabella di leasing utilizzando il formato a tabella singola.** Per impostazione predefinita, KCL 3.x crea tre tabelle DynamoDB per ogni applicazione: la tabella di lease, la tabella delle metriche dei lavoratori e la tabella dello stato del coordinatore. Il formato a tabella singola riduce queste tre tabelle a una sola, il che aiuta a evitare i limiti delle tabelle a livello di account DynamoDB.
## Come funziona il formato a tabella singola
In formato tabella singola, KCL memorizza le metriche dei lavoratori e le voci dello stato del coordinatore nella tabella di leasing insieme alle voci del leasing. Ogni elemento include un `entityType` attributo che distingue tra i diversi tipi di record.
Le metriche dei lavoratori e gli elementi relativi allo stato del coordinatore utilizzano la stessa struttura di chiavi primarie della tabella di leasing ma includono un valore distinto. `entityType` Questo attributo consente a KCL di identificare lo scopo di ogni elemento durante le scansioni della tabella.
Ogni componente di KCL filtra le voci necessarie per la sua logica aziendale in base all'attributo. `entityType` Ad esempio, il Lease Assignment Manager (LAM) filtra le voci relative alle metriche relative al leasing e al lavoratore per eseguire l'assegnazione del leasing.
## Configura il formato a tabella singola
Il modo in cui abiliti il formato a tabella singola dipende dalla tua attuale versione di KCL:
+ **Se utilizzi KCL 2.x:** segui la guida alla migrazione aggiornata per eseguire l'aggiornamento a KCL 3.5. Il formato a tabella singola viene utilizzato per impostazione predefinita per le nuove migrazioni da 2.x a 3.5.
+ **Se utilizzi KCL 3.0—3.4:** devi eseguire una distribuzione in due fasi per migrare al formato a tabella singola. Vedi i seguenti passaggi di configurazione e migrazione.
Per i clienti esistenti di KCL 3.x, imposta l'opzione di `migrateAllEntitiesToLeaseTable` configurazione in. `CoordinatorConfig` Questa opzione controlla se KCL memorizza tutti i tipi di entità di metadati nella tabella di leasing.
**`Valori di configurazione per la migrazione AllEntitiesToLeaseTable`**
| Valore | Default (Predefinito) | Effetto |
| --- | --- | --- |
| false | Sì | KCL utilizza tabelle separate per le metriche dei lavoratori e lo stato del coordinatore. Il codice dell'applicazione supporta il formato a tabella singola ma non lo attiva. |
| true | No | KCL inizia a scrivere le metriche dei lavoratori e i dati sullo stato dei coordinatori nella tabella dei contratti di locazione. Imposta questo valore nella fase 2 di implementazione dopo i reach `DEPLOYED` e il gioco è fatto `TableMigrationStatus` per non subire regressioni. |
La migrazione da KCL 3.x al formato a tabella singola richiede una distribuzione in due fasi:
1. **Fase 1:** distribuisci il codice KCL 3.5 aggiornato con `migrateAllEntitiesToLeaseTable` set to (impostazione predefinita). `false` Questo installa il nuovo codice che supporta il formato a tabella singola ma non attiva la migrazione.
1. **Fase 2:** dopo che tutti i worker hanno eseguito il nuovo codice e `TableMigrationStatus` i dati `DEPLOYED` di accesso e dopo aver verificato che non vi siano regressioni, eseguite nuovamente la distribuzione con `migrateAllEntitiesToLeaseTable` set `true` to per iniziare la migrazione.
## Stati di migrazione
`TableMigrationStateMachine`Gestisce la transizione dal formato multitabella al formato a tabella singola. KCL tiene traccia dello stato di migrazione corrente in una voce separata dello stato del coordinatore chiamata `TableMigration3.5` nella tabella dello stato del coordinatore. Per l'elenco completo di stati, transizioni e descrizioni, consulta gli stati di [migrazione a tabella singola di KCL](https://github.com/awslabs/amazon-kinesis-client/blob/master/amazon-kinesis-client/src/main/java/software/amazon/kinesis/coordinator/migration/TableMigrationStatus.java) sul sito Web. GitHub
**Stati di migrazione in formato a tabella singola**
| Stato | Description | Condizione di transizione |
| --- | --- | --- |
| INIT | Stato iniziale. Tutti i lavoratori emettono il codice di supporto minimo nelle statistiche metriche dei lavoratori. I lavoratori continuano a inserire le metriche dei lavoratori nella tabella precedente e a leggere le metriche dei lavoratori e lo stato del coordinatore sia dalla tabella precedente che da quella di leasing. Dal punto di vista funzionale, non c'è differenza tra INIT e DEPLOYED. | Tutti i lavoratori emettono costantemente il codice di supporto minimo per il tempo di cottura. L'applicazione è pronta per passare alla fase 2 della distribuzione. |
| DEPLOYED | Tutti i lavoratori sono stati impiegati con il nuovo codice (Fase 1 completata). L'applicazione supporta il formato a tabella singola ma non lo ha attivato. | La fase 2 di distribuzione inizia con `migrateAllEntitiesToLeaseTable` impostato su`true`. |
| PENDING | Tutti i lavoratori eseguono il nuovo codice. KCL migra i dati dalle metriche dei lavoratori e dalle tabelle degli stati dei coordinatori alla tabella delle locazioni. | Una volta completata la migrazione, trascorre un tempo di cottura predefinito di 24 ore. |
| COMPLETE | La migrazione è completa. KCL utilizza la tabella di lease esclusivamente per tutte le letture e le scritture. Le vecchie metriche dei lavoratori e le tabelle degli stati dei coordinatori non vengono più utilizzate. | Stato terminale. Non si verificano ulteriori transizioni. |
Per informazioni dettagliate su ogni stato, sulle condizioni di transizione e sul comportamento completo della macchina a stati, consulta [KCL Single Table Migration State Machine](https://github.com/awslabs/amazon-kinesis-client/blob/master/amazon-kinesis-client/src/main/java/software/amazon/kinesis/coordinator/migration/TableMigrationStatus.java) sul GitHub sito Web.
**Nota**
Il tempo di cottura predefinito tra gli stati PENDING e COMPLETE è di 24 ore, ma puoi configurarlo fino a una settimana. Durante questo periodo, KCL utilizza la tabella di lease per tutte le letture e le scritture ma non elimina le vecchie tabelle. È necessario eliminare manualmente le vecchie metriche dei lavoratori e le tabelle degli stati dei coordinatori dopo aver confermato che la migrazione è avvenuta correttamente. KCL non elimina queste tabelle automaticamente.
## Metriche di migrazione
Con KCL, puoi monitorare l'avanzamento e lo stato della migrazione di una singola tabella utilizzando CloudWatch le metriche. Utilizza queste metriche per confermare che i lavoratori abbiano adottato il nuovo codice e per monitorare la migrazione man mano che passa attraverso i suoi stati. Puoi anche rilevare errori di lettura, scrittura o eliminazione di DynamoDB durante la migrazione. Le tabelle seguenti raggruppano le metriche in base all'operazione KCL (dimensione metrica) che le emette e in base al momento in cui ogni metrica viene emessa.
Il lavoratore dirigente eletto emette continuamente le seguenti metriche, indipendentemente dal fatto che sia in corso una migrazione:
**Metriche emesse dal leader in ogni momento**
| Operation | Metrica | Unità | Description |
| --- | --- | --- | --- |
| `TableMigration` | `StatusOrdinal` | Nessuno | Ordinale dello stato corrente della migrazione DynamoDB`0`: = UNKNOWN`1`, = INIT, = DEPLOYED, = `2` PENDING, = COMPLETE. `3` `4` |
| `WorkerMetrics` | `FleetMinSupportCode` | Nessuno | Codice di supporto minimo per tutti i lavoratori della flotta titolari di leasing. |
Il lavoratore dirigente eletto emette le seguenti metriche solo mentre è in corso una migrazione:
**Metriche emesse dal leader durante la migrazione**
| Operation | Metrica | Unità | Description |
| --- | --- | --- | --- |
| `TableMigration` | `Phase1Worker` | Conteggio | Numero di lavoratori che supportano l'utilizzo di una singola tabella DynamoDB ma non sono ancora passati all'utilizzo della tabella singola. |
| `TableMigration` | `Phase2Worker` | Conteggio | Numero di lavoratori che sono passati alla scrittura sulla tabella singola. Questi lavoratori potrebbero continuare a leggere da più tabelle fino al completamento della migrazione delle tabelle. |
| `TableMigration` | `PrePhase1Worker` | Conteggio | Numero di worker in una versione precedente alla 3.5 che non supporta il funzionamento su una singola tabella DynamoDB. |
| `TableMigration` | `WriteFault` | Conteggio | `1`in caso di errore di scrittura in DynamoDB, in caso di successo`0`. |
| `TableMigration` | `DeleteFault` | Conteggio | `1`in caso di errore di eliminazione di DynamoDB, in caso di successo`0`. |
| `TableMigration` | `CompletionFault` | Conteggio | `1`quando la scrittura transazionale `COMPLETE` dello stato fallisce, in caso di successo. `0` |
| `TableMigrationAsyncMove` | `Success` | Conteggio | `1`in caso di trasferimento transazionale di CoordinatorState voci con esito positivo, in caso di fallimento. `0` |
| `TableMigrationAsyncMove` | `Time` | Millisecondi | Durata dell'operazione di spostamento asincrono. |
| `TableMigrationAsyncMove` | `BatchCount` | Conteggio | Numero di batch che sono stati spostati con successo. |
Tutti i lavoratori emettono le seguenti metriche mentre è in corso una migrazione:
**Metriche emesse da tutti i lavoratori durante la migrazione**
| Operation | Metrica | Unità | Description |
| --- | --- | --- | --- |
| `TableMigration` | `ReadFault` | Conteggio | `1`in caso di mancata lettura `TableMigrationState` da DynamoDB, in caso di successo. `0` |
| `TableMigration` | `Time` | Millisecondi | Durata del funzionamento della macchina a stati. |
| `TableMigrationInitialize` | `Success` | Conteggio | `1`in caso di inizializzazione riuscita, `0` in caso di errore. |
| `TableMigrationInitialize` | `Time` | Millisecondi | Durata dell'operazione di inizializzazione. |
Utilizza queste metriche per decidere quando far avanzare la migrazione. Quando `StatusOrdinal` è coerente `2` (IMPLEMENTATO) e lo `PrePhase1Worker` è`0`, tutti i lavoratori supportano il formato a tabella singola ed è possibile passare alla fase 2 della distribuzione della migrazione delle tabelle. Una volta `StatusOrdinal` raggiunta `4` (COMPLETE), è possibile eliminare in sicurezza le tabelle precedenti.
## Considerazioni sul rollback
Il supporto per il rollback dipende dalla versione attuale: `TableMigrationStatus`
+ **Durante la Fase 1** (`TableMigrationStatus`è `DEPLOYED` o non è ancora impostata): puoi tornare alla versione precedente in tutta sicurezza. Il nuovo codice viene eseguito in una modalità compatibile con le versioni precedenti e nessun dato è stato scritto nelle voci non di lease nella tabella di lease.
+ **Durante la Fase 2** (`TableMigrationStatus`è `DEPLOYED` o`PENDING`): è possibile tornare alla Fase 1. I lavoratori tornano a utilizzare le tabelle precedenti (formato multitavola) per le metriche dei lavoratori e lo stato del coordinatore. La migrazione è stata annullata.
+ **Dopo lo stato COMPLETE**: il rollback non è supportato. KCL utilizza solo la tabella di leasing per tutte le entità. Anche se il codice torna alla Fase 1, il lavoratore continua a utilizzare la tabella di leasing per tutte le entità e la configurazione viene ignorata.
**avvertimento**
Dopo che la migrazione ha raggiunto lo stato COMPLETE, l'applicazione funziona esclusivamente in modalità a tabella singola. La `migrateAllEntitiesToLeaseTable` configurazione viene ignorata e KCL non torna a utilizzare tabelle separate. Assicurati che il tempo di cottura prima di passare a COMPLETE sia sufficiente, perché dopo di che anche un rollback del codice non torna a più tabelle.
## Best practice
Segui queste best practice quando adotti il formato a tabella singola:
+ Dopo l'implementazione della Fase 1, verifica che l'ingresso dello stato coordinatore `TableMigration3.5` raggiunga `DEPLOYED` lo stato. Assicurati che non vi siano regressioni prima di procedere alla Fase 2.
+ Monitora l'ingresso nello stato `TableMigration3.5` coordinatore per tenere traccia dei progressi `TableMigrationStatus` negli stati DEPLOYED, PENDING e COMPLETE. Lo stato viene memorizzato nella tabella degli stati del coordinatore come voce separata (non nella tabella di leasing) fino a quando la migrazione non raggiunge COMPLETE.
+ Assicurati che il tempo di cottura prima di passare a COMPLETE sia sufficiente, perché dopo di che anche un rollback del codice non ritorna a più tabelle. L'applicazione funziona solo in modalità tabella singola.
+ Una volta completata la migrazione, elimina manualmente le vecchie metriche dei lavoratori e le tabelle degli stati dei coordinatori. KCL non elimina queste tabelle automaticamente, ma smette solo di usarle.
+ Se hai configurato `CoordinatorConfig.coordinatorStateTableConfig` o`LeaseManagementConfig.workerUtilizationAwareAssignmentConfig.workerMetricsTableConfig`, puoi rimuovere queste configurazioni al termine della migrazione. Queste configurazioni sono obsolete in KCL 3.5 e versioni successive.