OpenTelemetry 五分钟接入炬鲸 OBSERVE

前置准备

开始前准备三样东西：

• 一个炬鲸 OBSERVE 实例，记下 OTLP 接入地址（形如 https://ob.example.com/otlp）
• 一个带认证的 token（控制台 → 接入配置 → 生成 Token）
• 运行中的应用，语言不限（Java / Go / Python / Node 均可）

如果只是本地验证，可以用 docker 跑一个 Collector 单机版，下面会提到。如果已经有一套 OpenTelemetry 部署，可以直接跳过 Collector 这节，把现有的 exporter 指到平台即可。

配置 OTel Collector

推荐用 OpenTelemetry Collector 作为统一出口，应用不需要直连平台，同时它给你一个统一做批处理、重试、脱敏的地方。一个最小可用的 collector 配置：

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318
processors:
  batch:
    timeout: 5s
    send_batch_size: 512
  memory_limiter:
    check_interval: 1s
    limit_mib: 512
exporters:
  otlphttp:
    endpoint: https://ob.example.com/otlp
    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]

注意三件事：batch 处理器要放 memory_limiter 之后，避免背压时 OOM（顺序反了是生产环境 Collector 内存爆掉的最常见原因）；token 通过 header 传，不要写进代码，轮换时只在 Collector 改；三条 pipeline 分开配置，方便单独开关或迁移。

应用侧埋点

以 Java 为例，用 OpenTelemetry 自动埋点 agent，零侵入：

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

生产环境建议再加两个参数：otel.resource.attributes=service.version=<版本>，方便按版本对比延迟；otel.traces.sampler 设置采样比例，先 1.0，量上来再降。

Go 用 SDK 手动埋点（启动时建 trace provider，handler 套 otelhttp），Python 用 opentelemetry-instrument 命令包裹。无论哪种语言，最关键的是 service.name 要全局唯一且语义清晰（order-service、pay-gateway），它是后面按服务聚合、画拓扑图的 join 键，改名会打断历史视图。

埋点后大概 1 分钟内，控制台的"服务拓扑"和"链路追踪"页就应该能看到数据了。

验证与排错

如果看不到数据，按顺序查这几处：

1. 确认 collector 已收到：docker logs 看是否有 otlp 连接日志，没有说明应用没连上 4317/4318
2. 确认 exporter 没报错：401 是 token 错或过期，超时是 endpoint 从 collector 所在网络不可达
3. 确认应用真的在产生 span：开 DEBUG 日志看 exporter 发送次数，一直为 0 通常是 trace provider 没初始化
4. 时间对齐：应用、collector、平台三处时钟偏差过大会导致 trace 展示错乱，建议统一 NTP

验证链路完整性，可以在代码里打一个 trace_id 到日志，再到平台按 trace_id 反查，确认 logs 与 traces 能关联上；如果 trace 有但日志没挂上，说明日志管道没透传 trace context。