# 迁移到 KCL 3.5.x\+ 的单表格式
<a name="kcl-single-table-format"></a>

从 KCL 3.5 开始，您可以使用**单表格式**，将所有 DynamoDB 元数据整合到单个租约表中。默认情况下，KCL 3.x 会为每个应用程序创建三个 DynamoDB 表：租约表、工作线程指标表和协调器状态表。单表格式将这三个表缩减为一个，有助于避免 DynamoDB 账户级别的表限制。

## 单表格式的工作方式
<a name="kcl-single-table-how-it-works"></a>

在单表格式中，KCL 将工作线程指标条目和协调器状态条目与租约条目一起存储在租约表中。每个项目都包含一个 `entityType` 属性，用于区分不同的记录类型。

工作线程指标和协调器状态项目使用与租约表相同的主键结构，但包含不同的 `entityType` 值。通过此属性，KCL 可在表扫描期间识别每个项目的用途。

KCL 的每个组件都会根据 `entityType` 属性，筛选出其业务逻辑所需的条目。例如，租约分配管理器（LAM）筛选租约和工作线程指标条目以执行租约分配。

## 配置单表格式
<a name="kcl-single-table-config"></a>

启用单表格式的方式取决于您当前的 KCL 版本：
+ **使用 KCL 2.x 时：**请按照更新的迁移指南升级到 KCL 3.5。默认情况下，从 2.x 到 3.5 的新迁移使用单表格式。
+ **使用 KCL 3.0-3.4 时：**您必须执行两阶段部署来迁移到单表格式。请参阅以下配置和迁移步骤。

对于现有的 KCL 3.x 客户，请在 `CoordinatorConfig` 中设置 `migrateAllEntitiesToLeaseTable` 配置选项。此选项控制 KCL 是否在租约表中存储所有元数据实体类型。


**`migrateAllEntitiesToLeaseTable` 的配置值**  

| 值 | 默认值 | 效果 | 
| --- | --- | --- | 
| false | 是 | KCL 为工作线程指标和协调器状态使用单独的表。应用程序代码支持单表格式，但未将其激活。 | 
| true | 否 | KCL 开始将工作线程指标和协调器状态数据写入租约表。在 `TableMigrationStatus` 进入 `DEPLOYED` 状态且您已进行了充分的烘焙测试、没有回归问题后，在第 2 阶段部署中设置此值。 | 

从 KCL 3.x 迁移到单表格式需要分两个阶段进行部署：

1. **第 1 阶段：**部署更新后的 KCL 3.5 代码，将 `migrateAllEntitiesToLeaseTable` 设置为 `false`（默认）。这将安装支持单表格式的新代码，但不会激活迁移。

1. **第 2 阶段：**在所有工作线程都运行新代码、`TableMigrationStatus` 进入 `DEPLOYED` 状态并且您已验证没有回归问题之后，重新部署并将 `migrateAllEntitiesToLeaseTable` 设置为 `true` 以开始迁移。

## 迁移状态
<a name="kcl-single-table-states"></a>

`TableMigrationStateMachine` 管理从多表格式向单表格式的过渡。KCL 使用协调器状态表中名为 `TableMigration3.5` 的单独的协调器状态条目，来跟踪当前的迁移状态。有关状态、过渡和说明的完整列表，请参阅 GitHub 网站上的 [KCL single table migration states](https://github.com/awslabs/amazon-kinesis-client/blob/master/amazon-kinesis-client/src/main/java/software/amazon/kinesis/coordinator/migration/TableMigrationStatus.java)。


**单表格式迁移状态**  

| 州 | 说明 | 过渡条件 | 
| --- | --- | --- | 
| INIT | 初始状态。所有工作线程都在工作线程指标统计数据中发送最低支持代码。工作线程继续将工作线程指标发送到旧表中，并从旧表和租约表中读取工作线程指标和协调器状态。从功能上讲，INIT 与 DEPLOYED 没有区别。 | 在烘焙时间内，所有工作线程都会稳定地发送最低支持代码。应用程序已准备好进入第 2 阶段部署。 | 
| DEPLOYED | 所有工作线程都已使用新代码进行部署（第 1 阶段完成）。应用程序支持单表格式，但未将其激活。 | 第 2 阶段部署在开始时将 `migrateAllEntitiesToLeaseTable` 设置为 `true`。 | 
| PENDING | 所有工作线程都运行新代码。KCL 将工作线程指标表和协调器状态表中的数据迁移到租约表中。 | 迁移完成后，需要经过 24 小时的默认烘焙时间。 | 
| COMPLETE | 迁移已完成。KCL 对所有读取和写入仅使用租约表。不再使用旧的工作线程指标表和协调器状态表。 | 最终状态。不会再继续过渡。 | 

有关每种状态、过渡条件和完整状态机行为的详细信息，请参阅 GitHub 网站上的 [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)。

**注意**  
PENDING 和 COMPLETE 状态之间的默认烘焙时间为 24 小时，不过最多可以配置为一周。在此期间，KCL 为所有读取和写入使用租约表，但不删除旧表。确认迁移成功后，您必须手动删除旧的工作线程指标表和协调器状态表。KCL 不会自动删除这些表。

## 迁移指标
<a name="kcl-single-table-metrics"></a>

使用 KCL 时，您可以通过 CloudWatch 指标监控单表迁移的进度和运行状况。使用这些指标来确认工作线程已经采用了新代码，并跟踪迁移在各个状态中的进展情况。在迁移过程中，您还可以检测 DynamoDB 的读取、写入或删除故障。下表按发送指标的 KCL 操作（指标维度）和每个指标的发送时间，对指标进行分组。

无论迁移是否正在进行，当选的领导工作线程都会持续发送以下指标：


**领导工作线程始终发送的指标**  

| 操作 | 指标 | 单位 | 说明 | 
| --- | --- | --- | --- | 
| `TableMigration` | `StatusOrdinal` | 无 | 当前 DynamoDB 迁移状态的序数：`0` = UNKNOWN，`1` = INIT，`2` = DEPLOYED，`3` = PENDING，`4` = COMPLETE。 | 
| `WorkerMetrics` | `FleetMinSupportCode` | 无 | 队列中所有拥有租约的工作线程的最低支持代码。 | 

只有当迁移正在进行时，当选的领导工作线程才会发送以下指标：


**领导工作线程在迁移期间发布的指标**  

| 操作 | 指标 | 单位 | 说明 | 
| --- | --- | --- | --- | 
| `TableMigration` | `Phase1Worker` | 计数 | 支持使用单个 DynamoDB 表进行操作、但尚未迁移为使用单表的工作线程数量。 | 
| `TableMigration` | `Phase2Worker` | 计数 | 已迁移到写入单表的工作线程数量。在表迁移完成之前，这些工作线程可能仍会从多个表中读取数据。 | 
| `TableMigration` | `PrePhase1Worker` | 计数 | 3.5 之前版本的工作线程数量，这些工作线程不支持在单个 DynamoDB 表上进行操作。 | 
| `TableMigration` | `WriteFault` | 计数 | DynamoDB 写入失败时为 `1`，成功时为 `0`。 | 
| `TableMigration` | `DeleteFault` | 计数 | DynamoDB 删除失败时为 `1`，成功时为 `0`。 | 
| `TableMigration` | `CompletionFault` | 计数 | 事务写入 `COMPLETE` 状态失败时为 `1`，成功时为 `0`。 | 
| `TableMigrationAsyncMove` | `Success` | 计数 | CoordinatorState 条目的事务移动成功时为 `1`，失败时为 `0`。 | 
| `TableMigrationAsyncMove` | `Time` | 毫秒 | 异步移动操作的持续时间。 | 
| `TableMigrationAsyncMove` | `BatchCount` | 计数 | 成功移动的批次数量。 | 

在迁移过程中，所有工作线程都会发送以下指标：


**迁移期间所有工作线程发送的指标**  

| 操作 | 指标 | 单位 | 说明 | 
| --- | --- | --- | --- | 
| `TableMigration` | `ReadFault` | 计数 | 未能从 DynamoDB 读取 `TableMigrationState` 时为 `1`，读取成功时为 `0`。 | 
| `TableMigration` | `Time` | 毫秒 | 状态机运行的持续时间。 | 
| `TableMigrationInitialize` | `Success` | 计数 | 成功初始化时为 `1`，失败时为 `0`。 | 
| `TableMigrationInitialize` | `Time` | 毫秒 | 初始化操作的持续时间。 | 

使用这些指标来决定何时继续进行迁移。当 `StatusOrdinal` 持续为 `2`（DEPLOYED）且 `PrePhase1Worker` 为 `0` 时，所有工作线程都支持单表格式，您可以进入表迁移部署的第 2 阶段。在 `StatusOrdinal` 成为 `4`（COMPLETE）后，您可以安全地删除旧表。

## 回滚注意事项
<a name="kcl-single-table-rollback"></a>

回滚支持取决于当前 `TableMigrationStatus`：
+ **在第 1 阶段**（`TableMigrationStatus` 为 `DEPLOYED` 或尚未设置）：您可以安全地回滚到以前的版本。新代码在向后兼容模式下运行，并且未向租约表中的非租约条目写入任何数据。
+ **在第 2 阶段**（`TableMigrationStatus` 为 `DEPLOYED` 或 `PENDING`）：您可以回滚到第 1 阶段。对于工作线程指标和协调器状态，工作线程恢复为使用旧表（多表格式）。迁移已撤消。
+ **进入 COMPLETE 状态之后**：不支持回滚。KCL 对所有实体都仅使用租约表。即使代码回滚到第 1 阶段，工作线程仍会为所有实体继续使用租约表，并且忽略配置。

**警告**  
迁移过程进入 COMPLETE 状态后，应用程序仅在单表模式下运行。`migrateAllEntitiesToLeaseTable` 配置将被忽略，KCL 不会恢复为使用单表。请确保在进入 COMPLETE 状态之前有足够长的烘焙时间，因为进入该状态后，即使进行代码回滚也不会切换回多表。

## 最佳实践
<a name="kcl-single-table-best-practices"></a>

采用单表格式时，请遵循以下最佳实践：
+ 第 1 阶段部署后，验证协调器状态条目 `TableMigration3.5` 是否成为 `DEPLOYED` 状态。在进入阶段 2 之前，请确保没有回归问题。
+ 监控 `TableMigration3.5` 协调器状态条目中的 `TableMigrationStatus`，跟踪在 DEPLOYED、PENDING 和 COMPLETE 状态中的进度。在迁移过程变为 COMPLETE 之前，状态作为单独的条目存储在协调器状态表中（而不是租约表中）。
+ 请确保在进入 COMPLETE 状态之前有足够长的烘焙时间，因为进入该状态后，即使进行代码回滚也不会切换回多表。应用程序仅在单表模式下运行。
+ 迁移过程变为 COMPLETE 之后，请手动删除旧的工作线程指标表和协调器状态表。KCL 不自动删除这些表，只是停止使用。
+ 如果您已配置 `CoordinatorConfig.coordinatorStateTableConfig` 或 `LeaseManagementConfig.workerUtilizationAwareAssignmentConfig.workerMetricsTableConfig`，则可以在迁移完成后移除这些配置。在 KCL 3.5 及更高版本中，这些配置已弃用。