15 分钟把 OpenTelemetry 接进炬鲸 OBSERVE

先想清楚要采什么

接入之前先明确三件事：要采哪些服务的指标和 Trace、数据量大概多大、采样率定多少。别一上来就 100% 采样，高流量服务先设 10%，等观察到瓶颈再调整。采样率写进配置，改起来比改代码快得多。

炬鲸 OBSERVE 的接入端点统一走 OTLP 协议，端口 4318（HTTP）和 4317（gRPC）都支持。建议生产用 gRPC，数据压缩后传输量更小。

部署 Collector

先把 Collector 跑起来。用容器部署最快：

docker run -d --name otel-collector \
  -v $(pwd)/otel-config.yaml:/etc/otelcol/config.yaml \
  otel/opentelemetry-collector-contrib:0.95.0

Collector 建议部署在离应用近的位置：每台宿主机一个，或者每个集群一个。不要所有服务跨机房连一个中心 Collector，网络抖动会让指标丢点。

配置 exporter

otel-config.yaml 里改 exporter 段：

exporters:
  otlp/jjhub:
    endpoint: "ob.jjhub.cn:4317"
    headers:
      Authorization: "Bearer <你的接入Token>"
    tls:
      insecure: false
service:
  pipelines:
    metrics:
      exporters: [otlp/jjhub]
    traces:
      exporters: [otlp/jjhub]

Token 在炬鲸控制台的"接入管理"里创建，每个环境一个，别把生产 Token 写进测试配置再复制出去。

应用侧改三行

应用端不推荐手工埋点。优先用自动注入：Java 用 -javaagent:opentelemetry-javaagent.jar，Python 用 opentelemetry-instrument，Node 用 --require @opentelemetry/auto-instrumentations-node/register。

以 Java 为例，启动参数加：

-javaagent:opentelemetry-javaagent.jar
-Dotel.exporter.otlp.endpoint=http://localhost:4318
-Dotel.resource.attributes=service.name=order-service,env=prod

service.name 一定要设，而且要和团队约定好命名规范（如订单服务统一叫 order-service），否则 Trace 和指标里会出现一堆 unknown_service。

验证收数

三条命令确认链路通了：

1. 指标：进控制台"指标浏览"，搜 service.name="order-service"，能看到 CPU 或请求数即可。
2. Trace：发一次真实请求，去"链路追踪"搜 trace_id，确认能看到调用链。
3. 校验字段：抽一条 Span 看 service.name、trace_id、span_kind 是否齐全，缺了说明自动注入没生效。

收数正常后，把采样策略、告警阈值、Dashboard 一次配齐。前两周建议每天看一次数据量曲线，确认没有突增或断点。