OpenTelemetry 接入实战：30 分钟把服务数据送进炬鲸 OBSERVE

团队要上可观测性，最省事的路子不是自研埋点，而是直接用 OpenTelemetry（OTel）这套社区标准。下面的步骤假设你已经有一个跑着的服务，我们要做三件事：装 Collector、配导出、验证数据。全程不碰业务代码也能先看到 Trace 和指标。

准备：拿到接入地址和 Token

登录炬鲸 OBSERVE 控制台，进入「接入中心 → OpenTelemetry」，会看到两个信息：

• OTLP Endpoint：https://otlp.ob.jjhub.cn:4318
• Token：用于鉴权，写进配置的 Authorization 头

端口 4318 是 HTTP 协议，4317 是 gRPC。内网环境建议优先 gRPC，省带宽；跨公网用 HTTP，穿透防火墙更省心。

部署 Collector

生产上不要每个服务直连平台，中间加一层 OpenTelemetry Collector 做聚合和脱敏。用 Docker 起一个：

# otel-collector.yaml
receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318
processors:
  batch:
    timeout: 5s
    send_batch_size: 1024
  memory_limiter:
    check_interval: 1s
    limit_mib: 512
exporters:
  otlphttp:
    endpoint: https://otlp.ob.jjhub.cn:4318
    headers:
      Authorization: "Bearer <你的 Token>"
service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [memory_limiter, batch]
      exporters: [otlphttp]
    metrics:
      receivers: [otlp]
      processors: [memory_limiter, batch]
      exporters: [otlphttp]
    logs:
      receivers: [otlp]
      processors: [memory_limiter, batch]
      exporters: [otlphttp]

启动：

docker run -d --name otel-collector   -v $PWD/otel-collector.yaml:/etc/otelcol/config.yaml   otel/opentelemetry-collector-contrib:latest

一个常见的坑：batch processor 会攒够一批才发送，测试时如果迟迟看不到数据，把 timeout 调成 1s 或者先去掉 batch。

给服务接 SDK

以 Java（Spring Boot）为例，挂 agent 即可，不用改代码：

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

agent 会自动捕获 HTTP 请求、数据库调用、消息队列等常见跨度。Python 侧安装 opentelemetry-instrument 后同样一条命令启动，原理一致。

验证数据

部署后到控制台「链路追踪」页，随便触发几个请求，1 分钟内应该能看到 Trace 进来。三处要检查：

1. Trace 列表里能看到 order-service 的调用
2. 点开某条 Trace，Span 之间的父子关系和耗时合理
3. 「日志」页勾选「关联 Trace」，看日志是否带上了 trace_id

如果 Trace 进来了但日志没有，多半是日志 pipeline 没配，或者应用日志库没接 OTel 的日志桥接。Java 下检查 logback 是否挂了 opentelemetry-logback-appender。

到这里数据流已经打通。下一步建议给关键接口手动加自定义 Span，把业务维度（订单号、用户 ID）放进 attribute，排查时就能直接按订单号搜 Trace。