十分钟接入：用 OpenTelemetry 把 Java 服务接进炬鲸 OBSERVE

把 Java 服务接进可观测平台，最省事的方式是 Java agent 零侵入埋点。这篇按步骤走完一遍，顺带解决两个最常见的坑：401 认证失败和 exporter 协议不匹配。

前置条件

• Java 8 及以上的服务，任意框架（Spring Boot、Dubbo 等均可）
• 炬鲸 OBSERVE 已开通，拿到 OTLP 接入端点和租户 Token

第一步：挂 agent，先跑通 trace

下载 opentelemetry-javaagent.jar 放到部署目录，启动参数加上：

java -javaagent:opentelemetry-javaagent.jar   -Dotel.exporter.otlp.endpoint=https://ob.jjhub.cn/otlp   -Dotel.resource.attributes=service.name=order-service   -Dotel.traces.exporter=otlp   -Dotel.metrics.exporter=otlp   -Dotel.logs.exporter=otlp   -jar order-service.jar

service.name 建议写成「应用名-环境」，例如 order-service-prod。agent 会自动埋点 HTTP、数据库、消息队列等常见组件，不需要改业务代码。默认全量埋点，噪音太多可以用 -Dotel.instrumentation.<组件>.enabled=false 关掉不用的组件。

第二步：用环境变量托管配置

参数多了不好维护，尤其在 K8s 里，推荐全部改用环境变量：

export OTEL_EXPORTER_OTLP_ENDPOINT=https://ob.jjhub.cn/otlp
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer <你的token>"
export OTEL_SERVICE_NAME=order-service
export OTEL_METRICS_EXPORTER=otlp
export OTEL_LOGS_EXPORTER=otlp

注意两点：认证头必须写成 Authorization=Bearer <token>，漏了 token 会 401，数据一条都进不来——这是"数据没上来"最常见的原因；如果 OTLP 端点走 HTTP 而非 gRPC，协议要和 agent 的 exporter 版本对上，老版本默认 gRPC，新版本默认 HTTP/Protobuf，报连接拒绝时先确认这一点。

第三步：让日志也走 OTLP，做关联

trace 有了，日志还留在本地文件就没法做关联。推荐用 Logback 的 OpenTelemetry appender 把日志推上来，日志里会自动带上 trace_id 和 span_id。加上 opentelemetry-logback-appender 依赖并在 logback.xml 里配置，保留 console appender 作为兜底。

第四步：验证数据进来

启动后等 30 秒，在炬鲸 OBSERVE 的服务列表里应该能看到 order-service。造一次真实请求，再按 trace_id 查一次，确认日志和链路能对上。对不上就按顺序查：token 对不对、endpoint 对不对、exporter 协议是否匹配。这三点排查完，数据基本都能进来。