跳到主要内容

Transaction ID (Txid)

概述​

TXID Policy 的设计目的是为每个传入请求分配一个唯一的事务 ID。这个 ID 允许在不同服务之间跟踪请求，便于在分布式系统中进行调试、监控和日志记录。该策略确保每个请求都带有 x-txid 头部，后者可以用于追踪和分析。

为什么使用 TXID？​

  • 有助于 troubleshooting 和识别 API 事务中的问题。
  • 改善 observability 在分布式系统中的表现。
  • 使 logging consistency 在不同 API 层之间得以实现。

配置详情​

事务 ID 头部 (x-txid)​

  • 该策略会为每个传入请求自动生成一个唯一的 x-txid 头部。
  • 这个 ID 在请求的整个生命周期内保持一致，确保在不同服务之间的可追溯性。
  • 示例：
x-txid: 550e8400-e29b-41d4-a716-446655440000
  • 如果服务尚未包含 x-txid 头部，系统会自动生成一个。

W3C 激活​

该策略提供了一个可选的 W3C 激活 设置。当启用时，系统遵循 W3C Trace Context Specification，而不是使用 x-txid 头部。

  • 当 W3C 被禁用（默认）：
    • 系统将事务 ID 分配给 x-txid 头部。
  • 当 W3C 被启用：
    • 传递一个名为 traceparent 的 HTTP 头部，而不是 x-txid。
    • traceparent 头部根据 W3C Trace Context 标准进行格式化。
    • 这允许与支持 W3C 标准的外部日志记录和追踪工具进行互操作。
    • 示例：
traceparent: 00-3fcf0fea8f014021927305eb2842715b-59ee61718d864a72-01
  • 当与 stdout-log 结合时，跟踪信息将作为日志数据存储。

配置字段​

字段描述默认值备注
x-txid Header自动为每个请求分配一个唯一的事务 ID。启用不能更改。
W3C Activation启用 traceparent 头而不是 x-txid。禁用如果需要与 W3C 跟踪工具的互操作性，可以启用。
Choosing between x-txid and W3C traceparent:
  • 如果系统依赖于标准 API 跟踪机制，应使用 x-txid。
  • 如果需要与外部可观察性工具（如 OpenTelemetry）的互操作性，请启用 W3C traceparent。