5 分钟接入 OpenTelemetry：从采集器到全链路追踪

前置准备

你需要一个炬鲸 OBSERVE 租户，记下接入地址和访问 Token。本文假设环境是 Linux + Docker，业务是 Java / Go 微服务。整个接入分三步：部署 Collector 作为统一接收端、业务侧上报、验证链路。

部署 Collector

先跑一个 OpenTelemetry Collector，统一接收各服务的 trace / metrics / logs 并转发到 OBSERVE。用 docker-compose 起一个 collector：

otel-collector:
  image: otel/opentelemetry-collector-contrib:0.102.0
  volumes:
    - ./otel-collector-config.yaml:/etc/otelcol/config.yaml
  ports:
    - "4317:4317"   # OTLP gRPC
    - "4318:4318"   # OTLP HTTP
    - "8889:8889"   # Prometheus scrape

配置文件的关键在 exporter 和 pipelines：

receivers:
  otlp:
    protocols: { grpc: {}, http: {} }
  prometheus:
    config:
      scrape_configs:
        - job_name: 'otel-collector'
          scrape_interval: 15s
          static_configs: [{ targets: ['localhost:8888'] }]
exporters:
  otlp/jjhub:
    endpoint: "obs-gateway.jjhub.cn:4317"
    headers: { authorization: "Bearer <TOKEN>" }
service:
  pipelines:
    traces:  { receivers: [otlp], exporters: [otlp/jjhub] }
    metrics: { receivers: [otlp, prometheus], exporters: [otlp/jjhub] }
    logs:    { receivers: [otlp], exporters: [otlp/jjhub] }

业务侧上报

不改业务代码最快的方式是自动插桩（auto-instrumentation）。Java 服务启动时加 javaagent：

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

Go 服务用 otelhttp、otelgrpc 等库手动埋点，或者在无法插桩的遗留系统上用 eBPF 无侵入采集（见 v2.6.0 发布说明）。无论哪种方式，service.name 一定要设置且全局唯一，否则链路和指标会混在一起。

中间加一层 Collector 而不是让业务直连 OBSERVE，主要有三个原因：一是统一鉴权，Token 只配置在 Collector 一处，业务侧无需感知；二是集中做采样、批处理和重试，网络抖动时不丢数据；三是改 exporter 配置只改一处，几百个服务不用逐个改。Collector 建议和业务部署在同一机房，减少跨机房上报延迟。

另外建议给每个服务统一打上 resource attribute，例如 deployment.environment=prod、service.version=v1.2.0。这些属性会随 trace 和 metrics 一起上报，在 OBSERVE 里可以按环境、版本过滤，排查时能快速圈定"是不是某次发布引入的问题"。环境标签不要写错，否则线上和预发的数据会混在一起。

采样设置

全量采集在生产环境不现实，流量一大 Collector 和存储都会被打满。默认建议在 Collector 里用 tail_sampling 或 probabilistic_sampling 处理器，只保留慢请求和错误请求：

processors:
  probabilistic_sampler:
    sampling_percentage: 10
  tail_sampling:
    policies:
      - name: slow
        type: latency
        latency: { threshold_ms: 500 }
      - name: errors
        type: status_code
        status_code: { status_codes: [ERROR] }

慢请求和错误请求 100% 保留，正常请求按 10% 采样，既保住排障所需的完整链路，又控制存储成本。采样策略建议灰度调，先全量跑一天看数据量，再逐步收紧。

验证链路

1. 触发一次真实业务请求；
2. 在 OBSERVE「链路追踪」按 service.name 过滤，应看到一条完整 trace，含各 span 的耗时、状态码和错误信息；
3. 打开「监控」确认 metrics 有上报，指标名带 otel. 前缀；
4. 在「日志」里用 traceId 反查，确认日志与 span 已关联，点日志能跳回对应 span。

常见问题

• 上报无数据：先 curl -v http://localhost:4318 检查端口，再看 collector 日志里 export 是否报错，多半是 Token 或 endpoint 写错；
• trace 断链：确认所有服务用同一个 propagator（默认 W3C tracecontext），不要混用 b3；
• 时间轴错位：统一用 UTC 或统一配置本地时区，采集端与展示端时区不一致会导致 trace 时间轴对不上；
• 资源属性缺失：给每个服务统一打上 deployment.environment、service.version 等 resource attribute，方便按环境过滤，别都挤在 production 里。