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 di 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 dei 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, il che aiuta a evitare i limiti delle tabelle a livello di account di DynamoDB.
## Come funziona il formato a tabella singola
In formato tabella singola, KCL memorizza le metriche dei lavoratori e le voci relative allo stato del coordinatore nella tabella dei contratti di locazione insieme alle voci del leasing. Ogni articolo 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 ciascun elemento durante le scansioni delle tabelle.
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 delle metriche relative al leasing e al lavoratore per eseguire l'assegnazione del leasing.
## Configurare il formato di tabella singola
Il modo in cui abiliti il formato a tabella singola dipende dalla tua attuale versione di KCL:
+ **Se usi KCL 2.x: ** segui la guida alla migrazione aggiornata per passare a KCL 3.5. Il formato a tabella singola viene utilizzato di default 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 KCL 3.x esistenti, 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 migrate `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 del coordinatore nella tabella di locazione. Imposta questo valore sulla distribuzione di Fase 2 dopo i punti `TableMigrationStatus` raggiunti `DEPLOYED` e non avrai bisogno di 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 `DEPLOYED` reach e verificato che non vi siano regressioni, esegui 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 sullo stato del coordinatore chiamata `TableMigration3.5` nella tabella dello stato del coordinatore. Per l'elenco completo degli stati, delle transizioni e delle descrizioni, consulta gli stati di migrazione a tabella singola di [ KCL sul sito web. ](https://github.com/awslabs/amazon-kinesis-client/blob/master/amazon-kinesis-client/src/main/java/software/amazon/kinesis/coordinator/migration/TableMigrationStatus.java) 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 delle 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 dei 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 di implementazione. |
| DEPLOYED | Tutti i lavoratori sono stati impiegati con il nuovo codice (Fase 1 completa). L'applicazione supporta il formato a tabella singola ma non lo ha attivato. | La distribuzione della fase 2 inizia con l'`migrateAllEntitiesToLeaseTable`impostazione di`true`. |
| PENDING | Tutti i lavoratori eseguono il nuovo codice. KCL migra i dati dalle metriche dei lavoratori e dalle tabelle di stato del coordinatore nella tabella dei contratti di locazione. | Una volta completata la migrazione, trascorre un tempo di attesa predefinito di 24 ore. |
| COMPLETE | La migrazione è completa. KCL utilizza la tabella di leasing esclusivamente per tutte le letture e le scritture. Le vecchie metriche dei lavoratori e le tabelle dello stato 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, vedi [ 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 attesa predefinito tra gli stati PENDING e COMPLETE è di 24 ore, ma è possibile 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 di stato dei coordinatori dopo aver confermato che la migrazione è avvenuta con successo. 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 mentre attraversa i suoi stati. Puoi anche rilevare gli 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 a quando viene emessa ciascuna metrica.
Il lavoratore leader 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 | Numero ordinale dello stato attuale della migrazione di DynamoDB: `0` = UNKNOWN, = INIT, `1` = DEPLOYED, `2` = PENDING, = COMPLETE. `3` `4` |
| `WorkerMetrics` | `FleetMinSupportCode` | Nessuno | Codice di supporto minimo per tutti i lavoratori in leasing della flotta. |
Il lavoratore leader eletto emette le seguenti metriche solo durante la 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 singola tabella. |
| `TableMigration` | `Phase2Worker` | Conteggio | Numero di lavoratori che sono passati alla scrittura sulla singola tabella. Questi lavoratori potrebbero continuare a leggere da più tabelle fino al completamento della migrazione della tabella. |
| `TableMigration` | `PrePhase1Worker` | Conteggio | Numero di worker su 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 di 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 riuscito delle CoordinatorState voci, in caso di fallimento. `0` |
| `TableMigrationAsyncMove` | `Time` | Millisecondi | Durata dell'operazione di spostamento asincrono. |
| `TableMigrationAsyncMove` | `BatchCount` | Conteggio | Numero di batch che sono stati spostati correttamente. |
Tutti i lavoratori emettono le seguenti metriche durante 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 dell'esecuzione della macchina a stati. |
| `TableMigrationInitialize` | `Success` | Conteggio | `1`in caso di inizializzazione riuscita, `0` in caso di fallimento. |
| `TableMigrationInitialize` | `Time` | Millisecondi | Durata dell'operazione di inizializzazione. |
Usa queste metriche per decidere quando far avanzare la migrazione. Se `StatusOrdinal` è coerente `2` (IMPLEMENTATO) e lo `PrePhase1Worker` è`0`, tutti i lavoratori supportano il formato a tabella singola ed è possibile passare alla fase 2 dell'implementazione della migrazione delle tabelle. Dopo aver `StatusOrdinal` raggiunto il livello `4` (COMPLETATO), è possibile eliminare in modo sicuro le tabelle precedenti.
## Considerazioni sul rollback
Il supporto per il rollback dipende dalla situazione attuale: `TableMigrationStatus`
+ **Durante la Fase 1 ** (`TableMigrationStatus`impostata `DEPLOYED` o non ancora impostata): è possibile ripristinare in sicurezza la versione precedente. Il nuovo codice viene eseguito in una modalità compatibile con le versioni precedenti e nessun dato è stato scritto nelle voci non relative al lease nella tabella dei leasing.
+ **Durante la Fase 2 ** (`TableMigrationStatus`è `DEPLOYED` o`PENDING`): è possibile tornare alla Fase 1. I lavoratori tornano a utilizzare le tabelle precedenti (formato multitabella) per le metriche dei lavoratori e lo stato del coordinatore. La migrazione è annullata.
+ **Dopo lo stato COMPLETO**: il rollback non è supportato. KCL utilizza la tabella di leasing solo 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 COMPLETO, l'applicazione funziona esclusivamente in modalità 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 la distribuzione della Fase 1, verificate che lo stato inserito dal coordinatore `TableMigration3.5` `DEPLOYED` raggiunga lo stato. Assicuratevi che non vi siano regressioni prima di procedere alla Fase 2.
+ Monitora l'ingresso nello stato di `TableMigration3.5` coordinatore per tenere traccia dei progressi `TableMigrationStatus` negli stati DEPLOYED, PENDING e COMPLETE. Lo stato viene memorizzato nella tabella dello stato del coordinatore come voce separata (non nella tabella dei lease) fino a quando la migrazione non viene completata.
+ Assicuratevi che il tempo di attesa prima di passare a COMPLETE sia sufficiente, perché dopo tale termine anche il rollback del codice non torna 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 di stato dei coordinatori. KCL non elimina queste tabelle automaticamente, ma smette solo di utilizzarle.
+ 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.