ticdc: document Debezium source.start_ts option

ticdc/ticdc-changefeed-config.md

@@ -347,6 +347,14 @@ Info: {"upstream_id":7178706266519722477,"namespace":"default","id":"simple-repl
 - 是否输出行数据更改前的值。关闭后，UPDATE 事件不会输出 "before" 字段的数据。
 - 默认值：`true`
 
+##### `include-start-ts` <span class="version-mark">从 v8.5.9 版本开始引入</span>
+
+- 控制 Debezium JSON DML 消息是否包含 `source.start_ts`（源事务的原始 PD TSO）。
+- 默认值：`false`
+- 该参数只有当 sink 类型为 MQ 且输出协议为 Debezium JSON 时才生效。与 Debezium Avro 一起设置会被拒绝。
+- 你也可以设置等价的 URI 参数 `debezium-include-start-ts`。显式指定的 URI 参数优先于该配置项，包括使用 `false` 覆盖 `true`。
+- 关于消息格式和消费者精度要求，请参考 [TiCDC Debezium Protocol](/ticdc/ticdc-debezium.md#包含事务开始-tso)。
+
 ### consistent
 
 consistent 中的字段用于配置 Changefeed 的数据一致性。详细信息请参考[灾难场景的最终一致性复制](/ticdc/ticdc-sink-to-mysql.md#灾难场景的最终一致性复制)。

ticdc/ticdc-debezium.md

@@ -27,6 +27,47 @@ Debezium 输出格式中包含当前行的 Schema 信息，以便下游消费者
 
 此外，Debezium 原有格式中并不包含 TiDB 专有的 `CommitTS` 事务唯一标识等重要字段。为了保证数据的完整性，TiCDC 在 Debezium 格式中增加了 `CommitTs` 和 `ClusterID` 两个字段，用于标识 TiDB 数据变更的相关信息。
 
+### 包含事务开始 TSO <span class="version-mark">从 v8.5.9 版本开始引入</span>
+
+默认情况下，Debezium JSON DML 消息包含 `source.commit_ts`，但不包含事务开始 TSO。你可以选择仅在 DML 行事件中包含 `source.start_ts`（源事务开始时的原始 PD TSO）。该选项默认关闭。
+
+你可以通过以下任一方式开启该选项：
+
+- 在 `sink-uri` 中：
+
+    ```
+    kafka://127.0.0.1:9092/topic-name?protocol=debezium&debezium-include-start-ts=true
+    ```
+
+- 在 changefeed 配置文件中：
+
+    ```toml
+    [sink.debezium]
+    include-start-ts = true
+    ```
+
+显式指定的 URI 参数优先于配置文件，包括使用 `debezium-include-start-ts=false` 覆盖 `include-start-ts = true`。
+
+开启该选项后：
+
+- DML 消息的 value 会在 `commit_ts` 旁增加整型字段 `source.start_ts`，JSON schema 将该字段声明为 `int64`。
+- DDL 事件、WATERMARK 事件、key 消息和 Debezium Avro 不受影响。将该选项与 Debezium Avro 协议一起使用会被拒绝。
+- 如需回滚，关闭该选项即可。关闭期间产出的消息与此前格式保持兼容。
+
+> **注意：**
+>
+> `start_ts` 是原始的 uint64 PD TSO，不是毫秒时间戳。消费者必须将其作为 64 位整数或十进制字符串处理。不要将其解析为 JavaScript `Number` 或 IEEE-754 `float64`，后者无法精确表示 18 位 TSO。
+
+开启该选项后，`source` 字段类似如下：
+
+```json
+"source": {
+    "commit_ts": 447507027004751877,
+    "start_ts": 447507027004751800,
+    "cluster_id": "default"
+}
+```
+
 ## 消息格式定义
 
 本节介绍 DDL 事件、DML 事件和 WATERMARK 事件的消息格式。
@@ -570,6 +611,7 @@ Key 中的字段只包含主键或唯一索引列。字段解释如下：
 | `payload.before`    | JSON   | 这条事件语句变更前的数据值。对于 `"c"` 事件，`before` 字段的值为 `null`。  |
 | `payload.after`     | JSON   | 这条事件语句变更后的数据值。对于 `"d"` 事件，`after` 字段的值为 `null`。   |
 | `payload.source.commit_ts`     | 数值  | 该事件的 `CommitTs` 值。                    |
+| `payload.source.start_ts`      | 数值  | 源事务的开始 TSO。仅在启用 `debezium-include-start-ts` 或 `[sink.debezium] include-start-ts` 时出现。原始 uint64 PD TSO，不是毫秒时间戳。 |
 | `payload.source.db`     | 字符串   | 事件发生的数据库的名称。                    |
 | `payload.source.table`     | 字符串  |  事件发生的数据表的名称。                   |
 | `schema.fields`     | JSON   |  `payload` 中各个字段的类型信息，包括对应行数据变更前后 schema 的信息。      |

ticdc/ticdc-open-api-v2.md

@@ -371,6 +371,7 @@ curl -X GET http://127.0.0.1:8300/api/v2/health
 | 参数名                | 说明                                                                 |
 |:-------------------|:-------------------------------------------------------------------|
 | `output_old_value` | `BOOLEAN` 类型，是否输出行数据更改前的值。默认值为 `true`。关闭后，Update 事件不会输出 "before" 字段的数据。 |
+| `include_start_ts` | `BOOLEAN` 类型。从 v8.5.9 开始引入。控制 Debezium JSON DML 消息是否包含 `source.start_ts`（源事务的原始 PD TSO）。默认值为 `false`。 |
 
 ### 使用样例
 

ticdc/ticdc-sink-to-kafka.md

@@ -83,6 +83,7 @@ URI 中可配置的的参数如下：
 | `compression`        | 设置发送消息时使用的压缩算法（可选值为 `none`、`lz4`、`gzip`、`snappy` 和 `zstd`，默认值为 `none`）。注意 Snappy 压缩文件必须遵循[官方 Snappy 格式](https://github.com/google/snappy)。不支持其他非官方压缩格式。|
 | `auto-create-topic` | 当传入的 `topic-name` 在 Kafka 集群不存在时，TiCDC 是否要自动创建该 topic（可选，默认值 `true`）。 |
 | `enable-tidb-extension` | 可选，默认值是 `false`。当输出协议为 `canal-json` 时，如果该值为 `true`，TiCDC 会发送 [WATERMARK 事件](/ticdc/ticdc-canal-json.md#watermark-event)，并在 Kafka 消息中添加 TiDB 扩展字段。从 6.1.0 开始，该参数也可以和输出协议 `avro` 一起使用。如果该值为 `true`，TiCDC 会在 Kafka 消息中添加[三个 TiDB 扩展字段](/ticdc/ticdc-avro-protocol.md#tidb-扩展字段)。|
+| `debezium-include-start-ts` | 可选，从 v8.5.9 开始引入，默认值是 `false`。仅当 `protocol` 为 `debezium` 时生效。如果该值为 `true`，TiCDC 会在 Debezium JSON DML 消息中添加 `source.start_ts`（源事务的原始 PD TSO）。显式指定的 URI 参数优先于配置文件中的 `[sink.debezium] include-start-ts`。该选项与 Debezium Avro 一起使用会被拒绝。详情请参考 [TiCDC Debezium Protocol](/ticdc/ticdc-debezium.md#包含事务开始-tso)。 |
 | `max-batch-size` |  从 v4.0.9 开始引入。当消息协议支持把多条变更记录输出至一条 Kafka 消息时，该参数用于指定这一条 Kafka 消息中变更记录的最多数量。目前，仅当 Kafka 消息的 `protocol` 为 `open-protocol` 时有效（可选，默认值 `16`）。|
 | `enable-tls` | 连接下游 Kafka 实例是否使用 TLS（可选，默认值 `false`）。 |
 | `ca`       | 连接下游 Kafka 实例所需的 CA 证书文件路径（可选）。 |