StarRocks 分布式 Tracing 实战:基于 OpenTelemetry 与 Jaeger 追踪 FE/BE 全链路
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),如下图所示:
瀑布图展示了 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 的瀑布展开效果如下:
三、源码剖析: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 序列化为 W3Ctraceparent头格式(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 |
— |
需要说明的适用前提:
- 以上用法基于当前仓库的代码与文档状态,两个 endpoint 配置默认均为空串(禁用),需手动取消注释并指向本机或部署好的 Jaeger 实例后才生效;
- 当前仓库中,Trace 的既有埋点主要覆盖写入事务(load/insert/update/delete)链路及其向 BE 的传播,查询路径的埋点覆盖范围需结合当前版本源码自行确认;
- FE 侧若需对接非 Jaeger 的 OpenTelemetry 后端,可评估
otlp_exporter_grpc_endpoint配置项。


