本文介绍如何在 quarkus 应用中基于 opentelemetry（替代已废弃的 opentracing）实现分布式追踪，并同时将 trace 数据发送至 jaeger 可视化平台和本地服务日志，兼顾可观测性与调试便利性。
本文介绍如何在 quarkus 应用中基于 opentelemetry（替代已废弃的 opentracing）实现分布式追踪，并同时将 trace 数据发送至 jaeger 可视化平台和本地服务日志，兼顾可观测性与调试便利性。
自 Quarkus 2.13 起，OpenTracing 扩展已被正式弃用，官方明确推荐迁移到 OpenTelemetry（OTel）作为统一的观测性标准。这意味着：不再维护 quarkus-opentracing，也不再支持 Jaeger 原生客户端直连；所有新项目应使用 quarkus-opentelemetry 及配套组件。
✅ 正确配置 OpenTelemetry 追踪
首先，在 pom.xml 中引入核心依赖：
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-opentelemetry</artifactId>
</dependency>
<dependency>
<groupId>io.opentelemetry</groupId>
<artifactId>opentelemetry-exporter-logging</artifactId>
</dependency>⚠️ 注意：opentelemetry-exporter-logging 是关键——它提供将 span 数据以结构化 JSON 或文本格式输出到应用日志的能力，无需修改业务代码。
?️ 同时输出到 Jaeger + 日志的两种方式
方式一：通过 OpenTelemetry Collector（推荐）
这是生产级推荐方案：由 Collector 统一接收、处理并分发 trace 数据。你可配置其同时导出至 Jaeger 和文件/控制台日志。
示例 otel-collector-config.yaml（关键片段）：
由夸克扫描王提供的文件格式转换工具。当用户需要将图片、截图或扫描件转换为 Office 文档（Word/Excel）或 PDF 时，使用此技能。适用于包含复杂表格、合同或图文混排内容的图片或扫描件，可尽量还原原始版式并生成可编辑文档。即使用户未明确提到格式转换，只要用户的需求涉及将图片内容转换为可编辑文档（如 .docx、.xlsx 或 .pdf），也应触发此技能。请勿用于提取纯文本或识别文字内容、图像增强处理或从零创建文档
exporters:
jaeger:
endpoint: "jaeger:14250" # gRPC endpoint
logging:
loglevel: debug
sampling: 100 # 100% 日志输出（生产环境建议调低）
service:
pipelines:
traces:
receivers: [otlp]
exporters: [jaeger, logging] # ← 同时启用两个出口配合 docker-compose.yml 启动 Quarkus 应用 + OTel Collector + Jaeger：
services:
app:
build: .
environment:
- OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4317
otel-collector:
image: otel/opentelemetry-collector:latest
volumes:
- ./otel-collector-config.yaml:/etc/otelcol/config.yaml
jaeger:
image: jaegertracing/all-in-one:latest
ports:
- "16686:16686"此时，每个 HTTP 请求生成的 trace 既可在 http://localhost:16686 查看完整链路图，也会实时打印到 app 容器的标准输出（即 Quarkus 日志中），格式类似：
{
"trace_id": "a1b2c3d4e5f67890a1b2c3d4e5f67890",
"span_id": "0123456789abcdef",
"name": "HTTP GET /api/greeting",
"start_time": "2024-06-10T14:22:33.123Z",
"end_time": "2024-06-10T14:22:33.456Z",
"attributes": {"http.status_code":200,"http.method":"GET"}
}方式二：应用内直连（开发调试适用）
若暂不引入 Collector，也可在 Quarkus 应用中直接配置双 exporter（需手动注册）：
@ApplicationScoped
public class TracerConfig {
@PostConstruct
void setupTracing() {
SdkTracerProviderBuilder tracerProviderBuilder = SdkTracerProvider.builder();
// 导出到 Jaeger
tracerProviderBuilder.addSpanProcessor(
JaegerGrpcSpanExporter.builder()
.setEndpoint("http://localhost:14250")
.build()
);
// 导出到日志（结构化 JSON）
tracerProviderBuilder.addSpanProcessor(
LoggingSpanExporter.builder()
.setLogLevel(Level.FINE)
.build()
);
OpenTelemetrySdk.builder()
.setTracerProvider(tracerProviderBuilder.build())
.buildAndRegisterGlobal();
}
}? 提示：此方式绕过 OTel SDK 自动配置，适用于快速验证；但生产环境强烈建议使用 Collector，以解耦、增强可靠性与扩展性（如采样、过滤、协议转换等）。
✅ 补充说明与最佳实践
- 自动 Instrumentation：Quarkus 的 quarkus-opentelemetry 默认自动注入 HTTP、RESTEasy、gRPC、DB 等常见组件的 span，无需手动埋点。
- 采样控制：通过 quarkus.opentelemetry.tracer.sampler.type=parentbased_traceidratio 和 ...ratio=0.1 控制日志输出密度，避免日志爆炸。
- 日志集成：如使用 quarkus-logging-json，可将 OTel 日志自动转为 JSON 格式，便于 ELK/Splunk 解析。
- 迁移提示：若原有 OpenTracing 代码（如 Tracer 注入、Span 手动创建），需替换为 OpenTelemetry API（Tracer → io.opentelemetry.api.trace.Tracer）。
总之，OpenTelemetry 不仅提供了更现代、标准化的追踪能力，还通过灵活的 exporter 机制，轻松实现“Jaeger 可视化 + 本地日志留存”的双重保障，是 Quarkus 微服务可观测性的坚实基础。
