从获取接入信息、配置 OTLP exporter 到验证链路数据的完整步骤，覆盖 HTTP 与 gRPC 两种协议，并给出最常见的接入失败原因与排查方法，面向初次接入的开发者与运维。
链路追踪的接入成本，很大程度上决定了一个团队愿不愿意把它用起来。炬鲸 OBSERVE 完整兼容 OpenTelemetry，任何支持 OTLP 协议的 SDK 或采集器都能直连。下面以最常见的场景为例，走一遍从零到看到第一条链路的全过程。
登录 OBSERVE 控制台，进入「接入中心 → OpenTelemetry」，新建一个数据源后会得到两个关键参数：
https://otel.jjhub.cn（HTTP 协议，端口 4318；gRPC 端口 4317）jj_xxxxx，不要提交到公开仓库如果不想让每个应用都直连 OTLP 端点，可以先部署一个 OpenTelemetry Collector 做聚合，应用把数据发给本地的 Collector，再由 Collector 统一上报。生产环境推荐这种结构，能统一做采样、脱敏和重试。
以 Java 应用为例，用 OTel Java Agent 无需改业务代码，启动时挂上即可：
java -javaagent:opentelemetry-javaagent.jar -Dotel.resource.attributes=service.name=pay-svc,deployment.environment=prod -Dotel.exporter.otlp.endpoint=https://otel.jjhub.cn -Dotel.exporter.otlp.protocol=http/protobuf -Dotel.exporter.otlp.headers=Authorization=Bearer jj_xxxxx -jar pay-svc.jar
Go 应用则在 main 里初始化 SDK，用环境变量注入配置，保持与部署解耦：
OTEL_EXPORTER_OTLP_ENDPOINT=https://otel.jjhub.cn
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer%20jj_xxxxx
OTEL_SERVICE_NAME=pay-svc
注意两点：header 里 Bearer 与 token 之间的空格在环境变量里要写成 %20；服务名务必统一，否则后续按服务聚合会散成一堆。
上报后回到 OBSERVE，打开「链路追踪 → 服务列表」，应该能看到 pay-svc，并且 QPS、P99 延迟、错误率开始有数值。点开任意一条 trace，能看到完整的水滴图（span 瀑布），以及每个 span 的耗时、属性和关联日志。
如果服务列表里有了服务名，但看不到 trace，十有八九是采样率问题：OTel 默认的 parent-based 采样在无父 span 时按 OTEL_TRACES_SAMPLER 决定，默认是 parentbased_always_on，会全采；如果你改成了 traceidratio 且设得很低，就会有大量 trace 被丢弃。排查时先把采样率临时调到 100% 验证链路通不通，通了再调回来。
单有 trace 只能看到调用关系，看不到具体报错。把 trace_id 注入日志，就能在链路详情里直接关联到对应日志。以 Logback 为例，加一个 MDC 配置，把 OTel 的当前 trace_id 和 span_id 放进日志：
<pattern>%d %-5level [%X{trace_id}/%X{span_id}] %logger{36} - %msg%n</pattern>
然后在采集端把 trace_id 解析成字段。这样在 OBSERVE 里点开一个慢请求，不仅能看它调了哪些下游、各花了多久，还能直接跳到报错的那几行日志。
接入失败时按顺序检查：endpoint 是否能连通（telnet 或 curl）；token 是否写对、header 格式是否正确；协议是否匹配（HTTP 走 4318，gRPC 走 4317）；服务名是否设置了。九成的问题出在这四项里。确认无误后，再看 OBSERVE 侧的「接入诊断」页面，它会显示最近一次上报的时间戳和错误原因。