企业官网建设流程全解析

先说结论：Spring Boot 这个阶段你要是还在一套服务里同时维护 Prometheus 的埋点 SDK、Jaeger 的 Tracer 配置、还有一堆日志采集器配置，那技术债基本是翻倍往上涨。这篇把 Spring Boot 4 应用通过 OpenTelemetry 的 OTLP 协议，统一把链路数据给 Jaeger、指标数据给 Prometheus、日志数据给 Loki 的完整套路讲一遍。文章适合正在做微服务改造、或者想把三套监控体系收敛成一套的团队看，也适合刚接触可观测性的个人开发者——照着步骤走，两个小时能跑通全链路。

1. 先搞清楚这套可观测性方案到底在做什么

1.1 Metrics、Logging、Tracing 三者不是同一类东西

很多人刚开始接触监控的时候，都会陷入一个误区：觉得 Prometheus 能查指标、Loki 能查日志、Jaeger 能查链路，那把这仨装起来就行了。真到排查问题的时候才发现，三个系统各有各的数据模型，互相之间对不上号。

要理解 OpenTelemetry 的价值，先得理解这三类数据的本质区别。

Metrics（指标）本质是一串带时间戳的数值，比如 QPS、错误数、P99 延迟。它的特点是高频、轻量、适合聚合，但是丢失了上下文——你知道“下单接口错误率到了 20%”，但你不知道这个 20% 到底影响了哪一批用户、卡在哪个调用环节。

Logging（日志）本质是离散的事件记录，最典型的就是业务日志和异常堆栈。日志的信息含量最高，但它是非结构化的，而且量极大，查一上午日志找到一条关键堆栈的情况太常见了。

Tracing（链路追踪）本质是一条调用链路上一系列 Span（跨度）的集合。它不是数值也不是字符串，而是记录了“一个请求从入口到出口经过了哪些服务、每个环节耗时多少、有没有出错”的树状结构。它能告诉你“慢在谁身上”，但它的采样成本高，通常不可能全量采集。

这三者互相补充：指标负责“有没有问题”，日志负责“问题的细节是什么”，链路负责“问题出在哪个环节”。但问题在于，传统的做法里这三个体系是各自为战的——Prometheus 有自己的一套 client SDK，Jaeger 有自己的一套 Tracer API，日志系统又是另一套规范。每一套都有自己的依赖、配置和序列化格式，接入三套等于一次服务要写三份埋点代码。

1.2 OTLP 协议让三套体系共享一套“普通话”

OpenTelemetry 做的事情特别朴素：它不想重新发明监控系统，而是想定义一套统一的数据产生和传输规范。

OpenTelemetry 提供了统一的 API、SDK 和 Agent，你在代码里只需要调用一套 API 来创建 Span、记录指标、输出日志。至于这些数据怎么送到后端，全部通过 OTLP（OpenTelemetry Protocol）协议传输。

OTLP 是 OpenTelemetry 官方的标准协议，基于 gRPC 和 HTTP 双向传输，支持 Traces、Metrics、Logs 三类信号。换句话说，服务端只需要一个 Exporter（OTLP Exporter），把三类数据都推到同一个端口，然后由后端组件按需分流。

所以这套方案的核心思路是：

• 应用侧统一依赖 OpenTelemetry SDK（或直接用 Java Agent 零侵入接入）
• 三类数据都用 OTLP 协议传输
• Jaeger 原生接收链路数据，Prometheus 原生接收指标数据，Loki 接收日志数据
• 如果你还嫌不够统一，可以在中间加一个 OpenTelemetry Collector，作为统一接收端，再通过不同的 Exporter 分流给三个系统

这个架构最大的好处是：以后你换链路追踪系统，比如从 Jaeger 换成 Zipkin、从 Zipkin 换成 Grafana Tempo，只要后端支持 OTLP，应用侧一行代码都不用改。

1.3 这套方案的实际部署拓扑

我实际部署时用的是下面这种拓扑，画出来给大家一个整体感：

Spring Boot 4 应用 | | OTLP (gRPC/HTTP, 端口4317/4318) | OpenTelemetry Collector |--- Traces ---> Jaeger (或直接 OTLP) |--- Metrics ---> Prometheus (通过 OTLP Receiver) |--- Logs ---> Loki (通过 Loki exporter)

不经过 Collector 的简化版本也可以：Java Agent 直接配置OTEL_EXPORTER_OTLP_TRACES_ENDPOINT指向 Jaeger，用 Micrometer 暴露 Prometheus 格式指标，日志则让 Filebeat/Promtail 直接读到 Loki。但既然标题说了“用 OTLP 协议”，主推的还是经过 Collector 的统一方案。

我个人的建议是：小项目量级直接直连，运维复杂度最低；一旦你打算接多个服务、做多环境隔离、或者有接口鉴权和数据脱敏需求，Collector 这层基本是必选项。

2. 部署三个后端组件并逐一验证

2.1 Jaeger 从哪个版本开始原生支持 OTLP？

Jaeger 在 1.x 时代默认接收的是 Jaeger 自有的 thrift 格式，之后才加入了 OTLP 支持。到 Jaeger 3.x 版本，它已经完全转向基于 OpenTelemetry 的数据模型，直接原生接收 OTLP。

我用 Docker 部署 Jaeger 的方式如下：

docker run -d --name jaeger \ -p 16686:16686 \ -p 4317:4317 \ -p 4318:4318 \ jaegertracing/jaeger:3.1.0

启动后，16686 是 Jaeger UI，4317 是 OTLP gRPC 端点，4318 是 OTLP HTTP 端点。

注意：Jaeger 3.x 自带的 UI 已经变成了全新的 Jaeger UI（基于 Grafana 的改版），搜索方式跟老版本略有不同。老版本按服务名找服务的下拉框，新版本在左侧搜索框中直接输入服务名即可。

验证 Jaeger 是否正常工作，最方便的方式是用grpcurl检查 gRPC 端口是否响应：

grpcurl -plaintext localhost:4317 list

如果看到opentelemetry.proto.collector.trace.v1.TraceService，说明 OTLP Trace 端点已经就绪。

2.2 Prometheus 如何接入 OTLP 指标？

Prometheus 从 2.47 版本开始正式支持 OTLP Metrics Receiver，到了 2.53.0 这个版本已经比较成熟。需要特别提醒一点：这个 Receiver 是推送模式的，跟 Prometheus 经典的拉取模式（scrape）不是一回事。OTLP Receiver 会监听一个端口等待应用侧推送指标，推过来的时序数据会直接进入 Prometheus 的 TSDB。

我使用的是 Prometheus 2.53.0 + Docker 部署：

# prometheus.yml global: scrape_interval: 15s otlp: # 启用 OTLP Receiver，接收 OTLP 推送的指标 enabled: true listen_address: "0.0.0.0:4317" # 如果通过 HTTP 接收，可以再加一个 # listen_address_http: "0.0.0.0:4318" scrape_configs: - job_name: "spring-boot-app" metrics_path: "/actuator/prometheus" static_configs: - targets: ["host.docker.internal:8080"]

这里一个是 OTLP 接收（应用侧推过来），一个是常规拉取（Prometheus 主动抓/actuator/prometheus）。两条路我都建议配置：业务指标通过 Micrometer 暴露的端点拉取更稳妥，而 OpenTelemetry 产生的 Runtime 指标（例如 JVM 内存、GC 耗时）通过 OTLP 推送更顺。

启动 Prometheus：

docker run -d --name prometheus \ -p 9090:9090 \ -v $(pwd)/prometheus.yml:/etc/prometheus/prometheus.yml \ prom/prometheus:v2.53.0

验证方式：浏览器打开localhost:9090/targets，只要 Spring Boot 应用起来后 target 状态为 UP，同时localhost:9090/api/v1/status/otlp能查到 OTLP Receiver 接收指标的状态，就说明链路通了。

2.3 Loki 日志聚合的特性与部署

Loki 跟 Elasticsearch 这类传统日志系统最大的不同是：它几乎不索引日志内容，只对日志的标签（Label）建立索引。简单说，Elasticsearch 是“全文检索”，Loki 是“先按标签过滤，再在过滤后的流里做正则匹配”。

这个设计让它存储成本极低，但代价是查询速度依赖 Label 设计得好不好。所以如果服务里日志没有规范地加上service_name、trace_id、level这类的标签，后面查日志会非常痛苦。

Loki 本身 Docker 部署很简单：

docker run -d --name loki \ -p 3100:3100 \ -v $(pwd)/loki-config.yaml:/etc/loki/local-config.yaml \ grafana/loki:3.0.0 \ -config.file=/etc/loki/local-config.yaml

最简单的 Loki 配置可以直接用官方推荐的本地模式。验证写读是否正常：

# 写入一条测试日志（这里用 curl 模拟 Promtail 推送） curl -H "Content-Type: application/json" \ -X POST \ -d '{"streams":[{"stream":{"service_name":"test","level":"info"},"values":[["'$(date +%s%N)'","hello loki"]]}]}' \ http://localhost:3100/loki/api/v1/push # 查询 curl "http://localhost:3100/loki/api/v1/query_range?query={service_name=\"test\"}"

返回结果里能看到hello loki，说明 Loki 就绪了。注意这里推送的数据格式，它是 Loki 的 push API，跟 OTLP 是两回事——Loki 本身不接收 OTLP，需要通过 OpenTelemetry Collector 的 Loki Exporter 转换，或者直接用 Promtail 采集日志文件。

2.4 用 Grafana 一次性串联三个数据源

三个后端如果没有一个统一的展示入口，那就是三个孤岛。Grafana 是这里最好的粘合剂。

docker run -d --name grafana \ -p 3000:3000 \ grafana/grafana:11.0.0

进入localhost:3000，默认账号admin/admin，在 Connections -> Data Sources 里分别添加：

• Prometheus：URLhttp://prometheus:9090
• Jaeger：URLhttp://jaeger:16686，类型选 Jaeger
• Loki：URLhttp://loki:3100

全部配置完成后，Grafana 里可以同时做指标面板、日志面板，还可以用自带的数据源联动功能实现“从日志面板点击 traceId 跳转到 Jaeger 链路详情”。这个联动的关键配置后面我会细说。

3. Spring Boot 4 应用接入 OpenTelemetry

3.1 Spring Boot 4 的版本背景与兼容性

先给大家交个底：Spring Boot 4 目前还是以里程碑版本为主，正式 GA 后基线是 Spring Framework 7、Java 17+、Jakarta EE 11。如果你现在还在用 Spring Boot 3.x，也不用担心，这套 OpenTelemetry 的接入方式在 Boot 3.5 和 Boot 4 上基本完全一致。

我在下面的配置中使用了 Spring Boot 4 M 版本结合 OpenTelemetry Java Agent 来演示，实际上这套步骤适用于所有 Boot 3.x/4.x 工程。唯一要注意的是，Spring Boot 3 之后从javax.*迁到了jakarta.*，如果以前的老代码有大量javax.servlet之类的引包，升级时要先处理这个兼容问题。

3.2 方式一：零侵入的 Java Agent 接入

我强烈推荐 Java Agent 作为首选接入方式，因为它的侵入性为零——不需要改业务代码，只需要启动命令加一个参数。

到 OpenTelemetry 官方 GitHub 下载opentelemetry-javaagent.jar（建议选择 1.31 以上版本，OTLP 支持更完整），然后启动 Spring Boot 应用：

java \ -javaagent:opentelemetry-javaagent.jar \ -Dotel.service.name=order-service \ -Dotel.exporter.otlp.endpoint=http://localhost:4318 \ -Dotel.traces.exporter=otlp \ -Dotel.metrics.exporter=otlp \ -Dotel.logs.exporter=otlp \ -jar your-spring-boot-app.jar

这串参数干的事情是：

• -Dotel.service.name：设置服务名，后面 Jaeger、Prometheus、Loki 里找数据都靠这个名字区分
• -Dotel.exporter.otlp.endpoint：OTLP 端点的基础地址，端口 4318 是 HTTP 模式，4317 是 gRPC 模式
• traces.exporter / metrics.exporter / logs.exporter都指定为otlp，表示三类数据统一走 OTLP 协议发送

用 Java Agent 会自动做插桩，Spring MVC 的每个 Controller 请求自动生成一个 Span 链路；JDBC 调用、RestTemplate、Redis 客户端等常见组件也会自动埋点。对于大多数业务来说，链路追踪这一块不用手写任何代码。

注意：Metrics 这一块，Java Agent 默认同时导出 JVM 运行时指标（JVM 内存、垃圾回收等），这就省去了额外引入 Micrometer JVM 相关依赖的麻烦。

3.3 方式二：通过依赖注入 SDK 配置

如果你对 Agent 有顾虑（比如插桩影响到性能，或者需要更精细化的埋点控制），也可以直接用 OpenTelemetry SDK 放进 Spring Boot 工程里，作为 Bean 管理。

<dependency> <groupId>io.opentelemetry</groupId> <artifactId>opentelemetry-api</artifactId> </dependency> <dependency> <groupId>io.opentelemetry</groupId> <artifactId>opentelemetry-sdk</artifactId> </dependency> <dependency> <groupId>io.opentelemetry</groupId> <artifactId>opentelemetry-exporter-otlp</artifactId> </dependency> <dependency> <groupId>io.opentelemetry.instrumentation</groupId> <artifactId>opentelemetry-spring-boot-starter</artifactId> </dependency>

配置类里初始化：

@Configuration public class OpenTelemetryConfig { @Bean public OpenTelemetry openTelemetry() { OtlpGrpcSpanExporter spanExporter = OtlpGrpcSpanExporter.builder() .setEndpoint("http://localhost:4317") .build(); OtlpGrpcMetricExporter metricExporter = OtlpGrpcMetricExporter.builder() .setEndpoint("http://localhost:4317") .build(); SdkTracerProvider tracerProvider = SdkTracerProvider.builder() .addSpanProcessor(BatchSpanProcessor.builder(spanExporter).build()) .setResource(Resource.getDefault().put(AttributeKey.stringKey("service.name"), "order-service")) .build(); SdkMeterProvider meterProvider = SdkMeterProvider.builder() .registerMetricReader(PeriodicMetricReader.builder(metricExporter).setInterval(30, TimeUnit.SECONDS).build()) .setResource(Resource.getDefault().put(AttributeKey.stringKey("service.name"), "order-service")) .build(); return OpenTelemetrySdk.builder() .setTracerProvider(tracerProvider) .setMeterProvider(meterProvider) .build(); } }

手工配置的路子适合需要精细化控制的人，但代码量明显上去了。论省事，还是 Agent 舒服。

3.4 日志怎么带 traceId

链路追踪的数据不光要能看，更要在日志里能查到对应的 traceId。这样你才能在 Grafana 的日志面板里点一个 traceId 直接跳到 Jaeger 查看这次请求完整调用链。

使用 Java Agent 时，OpenTelemetry 的Logback集成会自动把trace_id和span_id注入到 MDC（Mapped Diagnostic Context）中。

只需要在 logback 配置文件里把trace_id、span_id加到输出 pattern 中：

<pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] [trace_id=%X{trace_id}] [span_id=%X{span_id}] %-5level %logger{36} - %msg%n</pattern>

在日志里就能看到类似这样的一行：

2025-07-01 14:23:45.123 [http-nio-8080-exec-3] [trace_id=5c2d4e7a9f8b3c2d] [span_id=1a2b3c4d5e6f7a8b] INFO c.example.OrderController - create order success

这个trace_id会跟 Jaeger 里的 trace ID 保持一致，是链路、日志联动的关键。我见过不少团队在配置这步被坑了：输出日志里没有 traceId，找问题要两边对时间戳，非常痛苦。

4. 让 Jaeger、Prometheus、Loki 在真实排障里联动起来

4.1 用 OTLP Collector 统一接收、按需分发

如果选择了容器化+微服务架构，我认为最稳妥的输出路径是中间加一个 OpenTelemetry Collector。

原因有三点：

1. 应用侧的 OTLP Exporter 只管把数据推到 Collector，无需感知后端组件地址的变化。
2. Collector 可以统一做数据脱敏、过滤、采样，避免无用数据直接压垮后端。
3. 当你把 Jaeger 换成 Tempo、或者把 Prometheus 换成 Thanos 时，应用不用动。

Collector 的 Docker 启动方式：

# otel-collector-config.yaml receivers: otlp: protocols: grpc: endpoint: 0.0.0.0:4317 http: endpoint: 0.0.0.0:4318 processors: batch: timeout: 1s exporters: # 链路数据给 Jaeger（Jaeger 原生 OTLP gRPC） otlp/jaeger: endpoint: jaeger:4317 tls: insecure: true # 指标数据给 Prometheus 的 OTLP Receiver otlp/prometheus: endpoint: prometheus:4317 tls: insecure: true # 日志给 Loki 的 Loki Exporter # 需要先安装 loki exporter loki: endpoint: http://loki:3100/loki/api/v1/push labels: attributes: - service.name service: pipelines: traces: receivers: [otlp] processors: [batch] exporters: [otlp/jaeger] metrics: receivers: [otlp] processors: [batch] exporters: [otlp/prometheus] logs: receivers: [otlp] processors: [batch] exporters: [loki]

这里面lokiexporter 并不是 OpenTelemetry Collector 内置的，它属于收集器发布组件中的独立包，需要预先添加到 Collector 的镜像中。如果不想折腾自定义镜像，也可以用 Promtail 直接采集应用日志文件来给 Loki，性能更稳定。

这两个方案我的选择标准很简单：

• 团队规模小、日志格式统一、环境单一，直接用 Promtail 文件采集，省心。
• 你要把日志也纳入统一 OTLP 管线、做多环境日志路由，那就花点时间构建一个含 Loki Exporter 的 Collector 镜像。

4.2 真实排障场景演示：订单失败怎么连环定位

把三个系统串起来后，排查一次线上故障的路径可以非常顺。这里用一个真实的例子说明。

某天 Grafana 的订单服务监控面板上，Prometheus 指标显示orders_failed_total从 0 突然涨到 500。第一反应肯定是看错误日志。

进入 Grafana 的 Explore 页面，在 Loki 数据源里输入：

{service_name="order-service"} |= "ERROR" | json | line_format "{{.msg}}"

这里标签service_name="order-service"是日志推送时从 OpenTelemetry 资源属性里带上去的。Loki 会根据这个标签快速锁定该服务当天的日志流，再用正则过滤ERROR级别日志。

找到一条关键的报错日志：

ERROR c.example.OrderService - create order failed: stock insufficient, trace_id=9f3a2b7c8d1e4f5a, order_id=20250701001

点击日志里的trace_id=9f3a2b7c8d1e4f5a，通过 Grafana 的“Data links to another data source”功能直接跳转到 Jaeger 中这条链路。这时你看到链路各 Span 的平均耗时，发现耗时主要集中在order-service调用inventory-service这一段，耗时才 18ms，而数据库查询这一段耗时高达 620ms。

于是问题被精确定位到“数据库查询慢”，再回去看日志就能确定是复杂的库存 SQL 触发了全表扫描。整个排查过程十分钟内解决，完全不用手工在三个系统之间来回切换对时间戳。

4.3 如何让 Grafana 日志与 Jaeger 跳转真正生效

实现上面说的“点日志里的 traceId 跳 Jaeger”，需要在 Grafana 里做两步配置。

以 Loki 数据源为例。在 Logs 数据源配置中，进入 Logs 页签，设置 Derived fields（派生字段）：

• 正则表达式匹配日志中的trace_id=(\w+)或"trace_id":"(\w+)"
• 字段名填trace_id
• 内部链接目标选择 Jaeger 数据源
• Query 为${__value.raw}

配置完成后，Loki 展示的日志会自动提取出trace_id栏，点击就能跳转 Jaeger 里对应链路。这个操作每个字段只需要配一次，但对实际排查效率的提升极大。

4.4 生产环境还需要注意的采样、基数和保留策略

这套体系跑起来容易，跑稳了难。上生产前，我认为有三个问题必须先想清楚。

第一个是采样率。链路追踪全量采集，高流量服务下 Jaeger 会撑不住，日志也是同理。常见做法是头部采样固定比例（比如 10%），再加尾部采样器按错误和耗时的规则保留下慢请求和异常链路。OpenTelemetry Java Agent 默认采样比率为 10，也就是 10% 的请求被采样。排查问题时不建议直接改成 100，先按需调。

第二个是指标高基数。Prometheus 对标签组合的基数非常敏感，url路径这种标签如果接入了用户 ID、订单 ID，那内存就会暴涨。OpenTelemetry 的指标语义约定里，HTTP 服务端指标http.server.request.duration的http.route会被规范化成路由模板（比如/api/orders/{id}），而不是真实的一条条 URL。这个设计就是给 Prometheus 用的，生产接入时务必确认这一点。

第三个是数据保留周期。Loki 和 Prometheus 默认把数据写进本地磁盘，我没有建议生产环境直接单机长期跑，而是这类时间序列数据会有明显的价值衰减：今天的实时指标最有价值，一周前的数据查询频率显著下降。建议在存储规划时把热数据保留 7 天、冷数据一个月，超出部分通过对象存储迁移降低成本。

5. 实战中的高频问题与排查速查

5.1 常见问题速查表

我把实际接入过程中踩过的、以及帮别人排查过的问题列成一张表，供大家直接对照。

5.2 最容易踩的坑：链路通了，指标和日志还各自为政

这一节是我最想提醒大家的。很多人接入 OpenTelemetry 后，链路的图出来了，听到“指标”“日志也统一了”，就以为收工了。但实际上指标端有很大概率没有把所有 Runtime 数据推过去，日志也只是简单接入了 Loki，但没有将service.name和trace_id打成标签。

你需要在验证阶段就做一次“全链路数据互查”：

1. 在 Jaeger 里看到一条 Trace 的 service name 是order-service
2. 去 Prometheus 里查jvm_memory_used_bytes{service_name="order-service"}
3. 再去 Loki 里查{service_name="order-service"} |= "ERROR"

三处都定位到同一个服务，才说明整条数据管线真正通了。我见过太多团队第一阶段只通了 Trace，后面两列其实就是脱节的。

5.3 本地调试时推荐的临时配置组合

为了减少排查障碍，本地调试阶段我推荐一个“全力输出”的配置组合，能让所有数据都全量上报、日志全打 DEBUG。

java \ -javaagent:opentelemetry-javaagent.jar \ -Dotel.service.name=order-service \ -Dotel.exporter.otlp.endpoint=http://localhost:4318 \ -Dotel.traces.sampler=always_on \ -Dotel.metrics.exporter=otlp \ -Dotel.logs.exporter=otlp \ -Dotel.javaagent.logging=application \ -Dlogging.level.io.opentelemetry=DEBUG \ -jar app.jar

等确认数据都正常上报后，再把sampler调回parentbased_traceidratio，把日志级别调回 INFO。线上环境绝不要长期跑always_on，我曾经看到有高并发服务因为这个直接把 Jaeger 磁盘打满。

6. 一点个人体会

最后说点题外话。这套方案我前后在好几个项目里实践过，最大的感触是：技术上最重的活其实不是“接通三个系统”，而是统一约定。

你需要在团队里定好几条规则：

• 服务名规范：order-service、user-service这种统一小写中划线格式，不要出现orderService和order_service混用
• 日志格式规范：JSON 结构化、关键字段名统一（trace_id、span_id、service.name）
• 关键指标的命名规范：用 OpenTelemetry 语义约定（Semantic Conventions），不要自创五花八门的指标名

这些约定没有做好，就算你链路、指标、日志全部接入成功，到了排障现场依然是各查各的，所谓“统一可观测性”就形同虚设了。

我目前的方式是把这套约定直接固化到团队的脚手架工程里：新服务创建时默认集成 OpenTelemetry Agent、日志输出 JSON、指标通过 OTLP 上报。新服务上线后不需要额外配置，监控体系自动接入，这才是这套方案真正的长期价值。