StarRocks 分布式 Tracing 实战:基于 OpenTelemetry 与 Jaeger 追踪 FE/BE 全链路

原创2026-09-15 09:16:151,845 阅读
文章标签:数据库OLAP数据仓库列式数据库分布式数据库数据湖湖仓一体实时分析大数据数据分析

StarRocks 分布式 Tracing 实战:基于 OpenTelemetry 与 Jaeger 追踪 FE/BE 全链路

本篇聚焦 StarRocks 的分布式追踪(Distributed Tracing)能力:以 OpenTelemetry 作为埋点 SDK、以 Jaeger 作为可观测性后端,对 FE(Java)与 BE(C++)中写入事务(load/insert/update/delete)的执行路径进行全链路追踪。读完本文,你可以完成 Jaeger 的安装与 FE/BE 侧配置,在 Jaeger Web UI 中检索 TXN 级别的 Trace,并理解 StarRocks 中 TraceManager(Java)与 Tracer(C++)的 span 创建、跨进程传播机制,从而具备自行扩展埋点的能力。

一、背景:为什么分布式系统需要 Trace

分布式 Trace(更常见的叫法是 Trace)记录一个请求在微服务、Serverless 等多服务架构中传播时走过的路径。在分布式系统中,性能问题往往难以复现,没有追踪手段时很难定位根因;Tracing 能够提升系统健康度可见性,帮助调试那些在本地难以复现的行为。

Trace 由一个或多个 Span 组成:第一个 Span 称为 Root Span,每个 Root Span 代表一个从开始到结束的完整请求;其下层的子 Span 提供更细粒度的上下文,描述请求内部由哪些步骤构成。许多可观测性后端会把 Trace 可视化为瀑布图(waterfall diagram),如下图所示:

StarRocks Trace 在 Jaeger 中的瀑布图,展示 Root Span 与子 Span 的父子嵌套关系

瀑布图展示了 Root Span 与子 Span 之间的父子关系:当一个 Span 包含另一个 Span 时,二者构成嵌套关系。

StarRocks 近期引入了 tracing 框架,基于 OpenTelemetry 与 Jaeger 追踪系统内的分布式事件:

  • OpenTelemetry 是一个 instrumentation/tracing SDK,开发者可用它给代码埋点并向可观测性后端发送追踪数据,支持多种语言。StarRocks 中同时使用了 Java SDK(FE)和 C++ SDK(BE)。
  • Jaeger 被用作可观测性后端,负责接收、存储和展示 span 数据。

二、基础用法:四步启用 StarRocks 追踪

1. 安装 Jaeger

Jaeger 官方文档提供 docker 部署方式;为简化起见,也可以直接下载 binary 包在本地运行。下载解压后目录内包含 jaeger-all-in-one 等可执行文件,直接运行即可:

$ ll
total 215836
drwxr-xr-x  2 decster decster     4096 02-05 05:01:30 ./
drwxrwxr-x 28 decster decster     4096 05-18 18:24:07 ../
-rwxr-xr-x  1 decster decster 19323884 02-05 05:01:31 example-hotrod*
-rwxr-xr-x  1 decster decster 23430444 02-05 05:01:29 jaeger-agent*
-rwxr-xr-x  1 decster decster 51694774 02-05 05:01:29 jaeger-all-in-one*
-rwxr-xr-x  1 decster decster 41273869 02-05 05:01:30 jaeger-collector*
-rwxr-xr-x  1 decster decster 37576660 02-05 05:01:30 jaeger-ingester*
-rwxr-xr-x  1 decster decster 47698843 02-05 05:01:30 jaeger-query*

$ ./jaeger-all-in-one

2. 配置 FE & BE 启用 tracing

关键点:OpenTelemetry 的 Java SDK 与 C++ SDK 使用不同协议——Java 侧走 gRPC proto,C++ 侧走 thrift & UDP,因此两者的 endpoint 端口不同。

fe.conf 中设置 jaeger_grpc_endpoint(默认注释,置为空串即禁用上报):

# Enable jaeger tracing by setting jaeger_grpc_endpoint
# jaeger_grpc_endpoint = http://localhost:14250

be.conf(CN 场景对应 cn.conf,单元测试对应 be_test.conf)中设置 jaeger_endpoint:

# Enable jaeger tracing by setting jaeger_endpoint
# jaeger_endpoint = localhost:6831

从 BE 侧配置定义可以看到取值格式约束:config.h 中明确标注了合法与非法示例——jaeger_endpoint = localhost:14268 是合法写法(仅 host:port),而 jaeger_endpoint = http://localhost:14268 是非法写法(不能带 scheme 前缀);FE 侧的 jaeger_grpc_endpoint 则相反,需要 http:// 前缀。这一点在配置时极易踩坑,务必区分。

此外 FE 的 Config.java 中还定义了 otlp_exporter_grpc_endpoint(默认空串,空串即禁用),用于向标准 OTLP gRPC 后端导出 span,为后续接入其他 OpenTelemetry 后端预留了扩展位。

3. 打开 Jaeger Web UI

默认地址为 http://localhost:16686/search。

4. 执行数据写入并检索 TXN Trace

执行一些数据摄入操作(Stream Load 或 INSERT INTO),然后在 Web UI 中检索 TXN 相关的 Trace。检索结果与单个 Trace 的瀑布展开效果如下:

Jaeger Web UI 中检索到的 TXN Trace 列表

TXN Trace 展开后的 span 瀑布图,展示 FE 与 BE 之间的事务处理链路

三、源码剖析:FE 侧 TraceManager 与事务 Span

TraceManager:单例 Tracer 与无操作回退

FE 侧的追踪核心是 TraceManager.java,其关键设计如下:

  • 服务名:所有 span 挂在 starrocks-fe 这个 service name 下(SERVICE_NAME = "starrocks-fe"),因此你在 Jaeger 服务列表里看到的正是这个名字。
  • 懒加载单例:getTracer() 返回全局 Tracer 实例,未初始化时通过 getOrCreateTracer() 创建。
  • 按配置选择 exporter:getSpanProcessors() 读取配置构造 SpanProcessor 列表——若 Config.jaeger_grpc_endpoint 非空,则添加 JaegerGrpcSpanExporter(包裹在 BatchSpanProcessor 中批量导出);若 otlp_exporter_grpc_endpoint 非空,则额外添加 OtlpGrpcSpanExporter。
  • 无操作回退:若两个 endpoint 均为空(即未启用追踪),instance 会被设置为 OpenTelemetry.noop().getTracer(SERVICE_NAME),即 no-op Tracer。这意味着业务代码可以无脑调用 startSpan,未配置追踪时零开销、不抛错。
  • span 创建 API:startSpan(name) 创建 Root Span;startSpan(name, parent) 显式指定父 Span。
  • startNoopSpan():显式返回一个假的 noop span。源码注释解释了其存在原因:很多代码路径会在 replay(重放日志)流程中执行,这些事件大多是重复的,应当禁用追踪,但用 noop span 可以免除代码中大量的 null 判断。
  • toTraceParent(SpanContext):把 SpanContext 序列化为 W3C traceparent 头格式(00-{32位traceId}-{16位spanId}-{2位flags}),这就是 FE 向 BE 传播 trace 上下文的载体。

写入事务:txn Span 的创建与传播

追踪框架当前最重要的埋点场景是写入事务(load/insert/update/delete)。在 TransactionState.java 中:

  • 正常新建事务时,构造函数执行 this.txnSpan = TraceManager.startSpan("txn"),并写入两个属性 txn_id 与 label,随后 this.traceParent = TraceManager.toTraceParent(txnSpan.getSpanContext()) 生成传播字符串;
  • 从日志恢复(replay)的事务则使用 TraceManager.startNoopSpan(),避免重放产生重复 span——正好对应上文 startNoopSpan() 注释中描述的场景。

也就是说,每个写入事务对应一个名为 "txn" 的 Root Span,你在 Jaeger 中检索到的 TXN Trace 由此而来。

跨进程传播:txn_trace_parent 字段

FE 与 BE 是两种语言实现的两个独立进程,trace 上下文必须显式传播。StarRocks 的做法是在 Thrift RPC 结构体中携带 txn_trace_parent 字段:

  • AgentService.thrift:TPublishVersionRequest 中定义 5: optional string txn_trace_parent,用于 publish version(事务发布)阶段的传播;
  • DataSinks.thrift:TOlapTableSink 中定义 16: optional string txn_trace_parent,用于数据写入路径的传播。

FE 侧通过 AgentTask.java、PublishVersionTask.java 与 OlapTableSink.java 等文件将 traceParent 填入这些 RPC 请求,从而把 BE 侧 span 挂接到同一个 Trace 之下。

四、源码剖析:BE 侧 Tracer 的接入

BE 侧的封装是 tracer.h / tracer.cpp 中的 Tracer 类(全局单例,Tracer::Instance()),它对 opentelemetry::trace::Tracer 提供兼容接口。Span 组织成一棵层级树:通过 start_trace() 新建的 span 成为无父的 Root Span;通过 add_span() 创建的新 span 挂载到父 span 之下。头文件中的示例:

const Tracer& tracer = Tracer::Instance();

void f1(const Tracer& tracer) {
    auto root = tracer.start_trace("root");
    sleepFor(Milliseconds(1));
    {
        auto child = tracer.add_span("child", root);
        sleepFor(Milliseconds(2));
    }
}

与 FE 跨进程传播对接的核心 API:

// If trace_parent is empty, create a new trace, else add a span
Span start_trace_or_add_span(const std::string& name, const std::string& trace_parent);

// Construct a SpanContext from Traceparent header
static SpanContext from_trace_parent(const std::string& trace_parent);

// Construct a Traceparent header from SpanContext
static std::string to_trace_parent(const SpanContext& context);

start_trace_or_add_span 的语义是:若 trace_parent 为空则创建一条新 trace,否则解析出父上下文并挂接为子 span。真实使用示例:

  • 发布版本阶段:publish_version.cpp 中 Tracer::Instance().start_trace_or_add_span("run_publish_version_task", publish_version_req.txn_trace_parent),并设置属性 txn_id——BE 端的该 span 通过 FE 传来的 txn_trace_parent 挂到 "txn" Root Span 之下,形成跨进程嵌套;
  • 数据加载阶段:load_channel.cpp 的 LoadChannel 构造函数中 Tracer::Instance().start_trace_or_add_span("load_channel", txn_trace_parent),设置属性 load_id。

至此一条完整的写入 Trace 链路为:FE "txn"(Root)→ 传播 txn_trace_parent → BE "load_channel"(写入阶段)、"run_publish_version_task"(发布阶段),全部呈现于同一个 Trace 的瀑布图中。

五、如何为自己的代码添加 Trace

按照官方文档的建议,扩展埋点前请先熟悉 tracer、span、trace propagation 等基础概念(可阅读 OpenTelemetry 的 Observability Primer),然后重点阅读 StarRocks 中的工具类及其现有用法,再仿照已有模式添加自己的 trace:

FE(Java)侧——调用 TraceManager 静态 API:

import com.starrocks.common.TraceManager;

Span span = TraceManager.startSpan("my_operation");      // Root Span
span.setAttribute("key", "value");
// ... 业务逻辑 ...
span.end();

// 有父 Span 时:
Span child = TraceManager.startSpan("my_child_op", parentSpan);

// 需要兼容 replay 等重复执行路径时:
Span s = /* 正常路径 */ TraceManager.startSpan("my_operation");
       /* 重放路径 */ TraceManager.startNoopSpan();

BE(C++)侧——使用全局 Tracer 单例:

#include "common/tracer.h"
using namespace starrocks;

// 进程内:创建 root 与 child span
auto root = Tracer::Instance().start_trace("my_trace");
{
    auto child = Tracer::Instance().add_span("my_child", root);
    child->SetAttribute("key", "value");
    // ... 业务逻辑 ...
}

// 跨进程:解析 FE 传来的 traceparent,挂接为子 span
auto span = Tracer::Instance().start_trace_or_add_span("my_span", trace_parent);

埋点时注意保持与现有风格一致:为关键 span 设置可检索的业务属性(如 txn_id、label、load_id),并在 RPC 边界上通过 to_trace_parent / from_trace_parent 序列化与反序列化上下文,保证 Trace 跨进程不断链。

六、小结与适用前提

侧 SDK 配置项 协议 / 端口 配置文件
FE OpenTelemetry Java SDK jaeger_grpc_endpoint(如 http://localhost:14250) gRPC proto conf/fe.conf
BE/CN OpenTelemetry C++ SDK jaeger_endpoint(如 localhost:6831,不能带 scheme) thrift & UDP conf/be.conf、conf/cn.conf
Jaeger Web UI — — http://localhost:16686/search —

需要说明的适用前提:

  1. 以上用法基于当前仓库的代码与文档状态,两个 endpoint 配置默认均为空串(禁用),需手动取消注释并指向本机或部署好的 Jaeger 实例后才生效;
  2. 当前仓库中,Trace 的既有埋点主要覆盖写入事务(load/insert/update/delete)链路及其向 BE 的传播,查询路径的埋点覆盖范围需结合当前版本源码自行确认;
  3. FE 侧若需对接非 Jaeger 的 OpenTelemetry 后端,可评估 otlp_exporter_grpc_endpoint 配置项。
登录后查看全文
starrocks