10 分钟接入 OpenTelemetry 自动埋点：以 Java 服务为例

前置条件

• JDK 8 或更高，一个可用的 Spring Boot 服务
• 控制台「接入中心」拿到 OTLP 地址和 token
• 服务机器能访问该端点，防火墙放行 4317/4318

第一步：下载 Java Agent

从 OpenTelemetry 官方 release 下载 javaagent 包，例如放到 /opt/otel/opentelemetry-javaagent.jar。注意 agent 版本要和 JDK 匹配：JDK 8 用 1.x 系列，JDK 17+ 用 2.x。版本不匹配是最常见的静默失败来源。

第二步：改启动参数

不需要改业务代码，只要加 -javaagent 并设置环境变量：

OTEL_SERVICE_NAME=order-service
OTEL_EXPORTER_OTLP_ENDPOINT=https://ob.jjhub.cn/otlp
OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer <token>
OTEL_TRACES_EXPORTER=otlp
OTEL_METRICS_EXPORTER=otlp
OTEL_LOGS_EXPORTER=otlp
java -javaagent:/opt/otel/opentelemetry-javaagent.jar -jar order-service.jar

service.name 用"环境-服务"命名，如 prod-order-service，避免多环境数据串到一起。

第三步：采样与资源属性

默认 100% 采样成本高，生产建议按比例采样：

OTEL_TRACES_SAMPLER=parentbased_traceidratio
OTEL_TRACES_SAMPLER_ARG=0.1

parentbased_traceidratio 保证子 span 跟随父 span 决策，不会出现"只采样一半调用"的断链。还可用 OTEL_RESOURCE_ATTRIBUTES 追加环境、版本号。

第四步：验证与常见坑

启动后 curl 打一个真实请求，30 秒内链路视图应有数据。三个最常见的坑：endpoint 写错协议（OTLP/HTTP 走 4318、gRPC 走 4317）；防火墙没放行端口；agent 与 JDK 版本不匹配导致静默失败，可加 -Dotel.javaagent.debug=true 看启动日志。日志自动关联 trace_id 还需引入 logback/log4j 的 OpenTelemetry 桥接包。验证后把 agent 参数固化进镜像，避免下次发布漏配。