在Ballerina服务中启用traceId的相关技术问询

内置日志分组与追踪ID支持 #

Ballerina 自带分布式追踪能力，基于 OpenTelemetry 实现，默认支持自动生成、管理 traceId 和 spanId，并自动关联到日志条目，无需手动实现核心追踪逻辑。

• 快速启用：在项目根目录的 Ballerina.toml 中添加以下配置即可开启追踪：

  [ballerina.runtime]
  observabilityEnabled = true
  
  [ballerina.observability.tracing]
  enabled = true
  # 可根据需求选择导出器，如 otlp、zipkin 等
  exporter = "otlp"
  otlpEndpoint = "http://localhost:4317"
  

• 日志自动关联：开启追踪后，Ballerina 默认日志会自动携带当前的 traceId 和 spanId，实现同一次请求的日志自动分组，日志输出示例：

  [2024-05-20 14:30:00] INFO  [traceId: 0123456789abcdef0123456789abcdef, spanId: 0123456789abcdef] - Processing request
  

服务间传递 Trace ID #

Ballerina 默认遵循W3C Trace Context 规范，自动处理跨服务的追踪上下文传递：

• HTTP 场景：自动通过 traceparent 标准请求头传递 traceId，接收方服务会自动解析并延续追踪链路，无需额外代码。
• gRPC 场景：通过 grpc-trace-bin 二进制头传递追踪上下文，同样自动处理。

若需手动操作或自定义传递逻辑：

• 获取当前 Trace ID：使用 ballerina/observability 包的 API 直接获取：

  import ballerina/observability;
  
  string? currentTraceId = observability:tracing:getCurrentTraceId();
  

• 自定义 Correlation ID 传递：如果需要使用自定义头（如 X-Correlation-ID），可在客户端手动添加头，服务端解析后绑定到追踪上下文：
  服务端示例：

  import ballerina/http;
  import ballerina/observability;
  
  service /api on new http:Listener(8080) {
      resource function get users(http:Request req) returns string {
          // 从自定义头获取关联ID
          string? corrId = req.getHeader("X-Correlation-ID");
          if corrId is string {
              // 将自定义ID绑定到当前追踪上下文
              observability:tracing:setCorrelationId(corrId);
          }
          return "User list";
      }
  }
  

  客户端示例：

  import ballerina/http;
  
  public function main() returns error? {
      http:Client apiClient = check new ("http://localhost:8080");
      http:Request req = new;
      // 设置自定义关联ID头
      req.setHeader("X-Correlation-ID", "corr-2024-0520-1001");
      string response = check apiClient->/api/users;
  }
  

是否需要自行实现？ #

绝大多数场景下无需手动实现：

• 标准的 traceId 生成、日志关联、跨服务传递都由内置的 OpenTelemetry 集成自动完成。
• 仅当需要使用非标准的关联ID头、或者在非HTTP/gRPC协议中传递追踪上下文时，才需要补充少量自定义代码。

内容的提问来源于stack exchange，提问作者Tharindu Udupitiya