15 分钟接入 OpenTelemetry：从部署 Collector 到 Trace 可视化

前置准备

开始前确认三件事：已部署炬鲸 OBSERVE 并拿到 OTLP 接入地址（形如 https://obs.example.com/otlp）；有一个 Java 8+ 服务用于演示；服务器能出网或与 Collector 在同一内网。

架构很简单：应用通过 OTel SDK 把 Trace 数据用 OTLP 协议推到 Collector，Collector 统一做缓冲、脱敏、采样后导出到炬鲸 OBSERVE。

部署 Collector 并配置导出

先起一个 OpenTelemetry Collector，用 Docker 最省事：

receivers:
  otlp:
    protocols:
      grpc:
      http:
exporters:
  otlphttp:
    endpoint: https://obs.example.com/otlp
service:
  pipelines:
    traces:
      receivers: [otlp]
      exporters: [otlphttp]

把配置挂载后运行：

docker run -p 4317:4317 -p 4318:4318 \
  -v $PWD/otel-config.yaml:/etc/otelcol/config.yaml \
  otel/opentelemetry-collector-contrib

4317 是 gRPC 端口，4318 是 HTTP 端口。只是试跑也可以跳过 Collector，应用直接连 OBSERVE 的 OTLP 端点；但生产环境务必保留 Collector，它是缓冲、脱敏、采样三件事的统一落点。

应用侧自动埋点（Java）

用 Java Agent 零代码接入。下载 opentelemetry-javaagent.jar，启动时加上：

java -javaagent:opentelemetry-javaagent.jar \
  -Dotel.service.name=order-service \
  -Dotel.exporter.otlp.endpoint=http://localhost:4317 \
  -Dotel.traces.exporter=otlp \
  -Dotel.metrics.exporter=none \
  -jar app.jar

service.name 会作为链路里的服务名，务必取有业务含义的名字，建议「环境-服务」格式。自动埋点覆盖 Spring MVC、HTTP Client、数据库驱动、Redis、Kafka 等主流组件，不用改一行业务代码。

验证与排查

启动后发几个请求，到炬鲸 OBSERVE 的「链路追踪」页面：

1. 按服务名 order-service 过滤，能看到请求列表。
2. 点进一条 Trace，看 Span 树：入口 Span、数据库调用、下游 HTTP 调用应有清晰的父子关系。
3. 重点看耗时最长的 Span，通常就是瓶颈。

常见坑：

• 连不上 Collector：确认 4317 端口可达，检查 endpoint 是否写了 http:// 前缀。
• 有 Trace 但字段不全：确认 OBSERVE 侧已开启该服务的数据接收，检查采样率是否过低。
• 下游调用丢失：下游服务也要挂 Agent，否则父 Span 的下游节点是空的。

采样与成本

默认采样是全量，压测或高流量场景会推爆。建议在 Collector 配 probabilistic_sampler，平时保留 10%～20%，出问题时再临时调高。链路追踪的价值在「能不能定位」，不在「存了多少」。