Quarkus 中使用 OpenTelemetry 实现分布式追踪与日志输出-java教程-PHP中文网

Quarkus 中使用 OpenTelemetry 实现分布式追踪与日志输出

本文介绍如何在 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 Alibaba-Quark-Transoffice

由夸克扫描王提供的文件格式转换工具。当用户需要将图片、截图或扫描件转换为 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 微服务可观测性的坚实基础。