在Java项目中配置可观测性环境，核心目标是让系统运行时的指标、日志和链路追踪数据可被统一收集与分析。OpenTelemetry提供了与语言无关的标准和Java生态的官方SDK，能够帮助开发者以较低侵入的方式完成数据采集搭建。
一、可观测性与OpenTelemetry基础
可观测性通常包含三大支柱：日志（Logs）、指标（Metrics）和追踪（Traces）。OpenTelemetry简称OTel，是一个CNCF毕业项目，定义了数据采集的API、SDK以及协议（如OTLP）。在Java项目中，我们一般通过Java Agent实现自动埋点，减少业务代码改动。
1.1 为什么选择OpenTelemetry
- 厂商中立，后端可对接Jaeger、Tempo、Prometheus等
- 支持自动和手动埋点，兼容Spring Boot等主流框架
- 社区活跃，Java Agent覆盖JDBC、HTTP客户端等常见组件
二、环境准备与依赖配置
最简单的方式是使用OpenTelemetry Java Agent。下载对应版本的jar包，在启动Java应用时通过-javaagent参数挂载即可。
2.1 下载Agent
可以从官方发布页获取opentelemetry-javaagent.jar。假设放在/opt/otel目录下。
2.2 启动参数示例
以下命令演示如何将采集数据通过OTLP协议发送到本地Collector：
java -javaagent:/opt/otel/opentelemetry-javaagent.jar -Dotel.service.name=order-service -Dotel.exporter.otlp.endpoint=http://127.0.0.1:4317 -Dotel.traces.exporter=otlp -Dotel.metrics.exporter=otlp -jar your-app.jar
三、在代码中手动补充埋点
自动埋点覆盖大部分场景，但业务自定义跨度（Span）仍需手动写入。使用OpenTelemetry API可创建子Span记录方法耗时。
3.1 获取Tracer并创建Span
import io.opentelemetry.api.OpenTelemetry;
import io.opentelemetry.api.trace.Span;
import io.opentelemetry.api.trace.Tracer;
import io.opentelemetry.context.Scope;
// 假设全局OpenTelemetry已通过Agent初始化
OpenTelemetry otel = OpenTelemetry.noop();
Tracer tracer = otel.getTracer("com.example.demo");
Span span = tracer.spanBuilder("processOrder").startSpan();
try (Scope scope = span.makeCurrent()) {
// 业务逻辑：处理订单
span.setAttribute("order.id", "1001");
Thread.sleep(50);
} catch (Exception e) {
span.recordException(e);
} finally {
span.end();
}
注意上述代码在Agent环境下应使用全局获取的实例，实际项目可通过GlobalOpenTelemetry.get()获得，避免直接构造noop对象。
四、对接后端进行数据查看
搭建一个OpenTelemetry Collector，接收4317端口的OTLP数据，再转发给Jaeger做界面展示。Collector基础配置如下：
receivers:
otlp:
protocols:
grpc:
endpoint: 0.0.0.0:4317
exporters:
jaeger:
endpoint: "127.0.0.1:14250"
service:
pipelines:
traces:
receivers: [otlp]
exporters: [jaeger]
| 配置项 | 作用 |
|---|---|
| otel.service.name | 设置服务名，便于在追踪系统中区分应用 |
| otel.exporter.otlp.endpoint | 指定Collector地址，支持gRPC与HTTP |
| otel.metrics.exporter | 配置指标导出方式，如otlp或prometheus |
五、常见问题与调优
如果Agent启动后无数据，先确认防火墙是否放行4317端口，以及Collector是否正常运行。
采样率可通过otel.traces.sampler调整，生产环境建议用parentbased_always_on配合尾部采样。对于高并发接口，可关闭部分无关插件的埋点以减少开销。
通过以上步骤，Java项目即可拥有基础的可观测性环境，OpenTelemetry数据采集搭建完成后，开发与运维人员能从统一面板观察请求链路与资源消耗，显著提升故障排查效率。
JavaOpenTelemetry可观测性数据采集分布式追踪修改时间：2026-07-25 01:45:25