基于 OpenTelemetry:Kubernetes 环境下 Java 应用无侵入接入落地实践
本文介绍如何通过观测云实现 Kubernetes 环境下 Java 应用的无侵入接入实践。关联请求耗时、调用关系及 Kubernetes 运行信息,为应用性能分析与故障定位提供支持。
以 Kubernetes 中的
springboot-server-otel.yaml为 Demo,通过 DataKit Operator 自动注入 OpenTelemetry Java Agent,无需修改 Spring Boot 业务代码和原有启动命令,即可将 HTTP 调用链与 Pod、Namespace、Node 等运行上下文接入观测云。
背景
Spring Boot 应用运行在 Kubernetes 中时,一个接口可能继续发起下游 HTTP、数据库或缓存调用。容器指标可以帮助判断资源是否异常,日志可以记录业务事件,而分布式链路能够进一步回答:请求经过了哪些调用、时间消耗在哪一段,以及具体运行在哪个 Pod。
OpenTelemetry Java Agent 可以自动插桩受支持的 Java 框架和客户端。如果由每个应用自行维护探针 JAR、启动参数和上报地址,服务增加后容易出现配置不一致。本实践将探针管理放到 Kubernetes 平台层:应用通过语言标签声明接入,DataKit Operator 在新 Pod 创建时完成注入。
本文围绕同一个 Demo 完成部署、检查、请求触发和页面验证,先打通 Trace,再说明如何扩展 JVM 指标与日志关联。
观测云如何实现统一观测
观测云通过应用性能监测展示服务请求、调用耗时、错误 Span 和调用关系,并可结合日志、指标与 Kubernetes 资源信息继续排查。本方案中,Java Agent 生成链路数据,DataKit 接收 OTLP 并经 DataWay 写入工作空间,DataKit Operator 负责探针注入。Operator 不承担业务链路数据的转发。

注入发生在 Pod 创建阶段:Webhook 匹配语言标签后,为业务 Pod 添加 initContainer、共享卷、Java 启动参数和 OTel 环境变量。应用运行后,Java Agent 再通过 OTLP/HTTP 将数据发往 DataKit。本文使用 DataKit Operator 完成注入,无需另外部署 OpenTelemetry Operator 或创建 Instrumentation CR。
实践
前置条件与 Demo 说明
- Kubernetes 集群已启用 Mutating Admission Webhook,操作账号可管理 DataKit、Operator 和业务 Deployment;
- DataKit 已连接目标观测云工作空间,业务 Pod 能访问集群内 DataKit Service 的
9529端口; - DataKit Operator 不低于
v1.9.0,节点可以拉取业务与探针镜像; - Java 运行时满足所选 Java Agent 的支持范围。本次截图显示 Demo 使用 OpenJDK
1.8.0_402-b06。
Demo 使用 default 命名空间,Deployment 和服务标识均为 springboot-server,容器监听 8080。仓库清单已经包含 admission.datakit/otel-language: java 标签,但标签本身不能替代 Operator 注入规则。
kubectl -n datakit get daemonset datakit
kubectl -n datakit get deployment datakit-operator
kubectl -n datakit get service datakit-service
kubectl -n datakit get deployment datakit-operator -o jsonpath='{.spec.template.spec.containers[0].image}{"\n"}'
DataKit 与 DataKit Operator 是独立组件。已有 DataKit 时仍需确认 Operator 是否安装且支持 OTel。仓库中的旧版 datakit-operator.yaml 标注为 v1.5.10,不能直接用作本文的 OTel 注入配置。
配置 DataKit 接收 OpenTelemetry
尚未安装 DataKit 时,先按照Kubernetes 安装文档部署,并配置目标工作空间的 DataWay 地址。已安装时,在现有 DaemonSet 配置中追加 opentelemetry,保留原有采集器列表;同时确认 HTTP 监听和 Service 端口。
# DataKit DaemonSet 容器的 env 片段,合并到现有配置
env:
- name: ENV_DEFAULT_ENABLED_INPUTS
value: "cpu,disk,diskio,mem,system,container,opentelemetry"
- name: ENV_HTTP_LISTEN
value: "0.0.0.0:9529"
# 已有 datakit-service 的 spec.ports 中应包含此端口
ports:
- name: http
port: 9529
targetPort: 9529
protocol: TCP
应用修改后的 DataKit 安装清单,然后检查滚动状态、Service 后端和采集器日志:
kubectl apply -f <DataKit 安装清单>
kubectl -n datakit rollout status daemonset/datakit --timeout=5m
kubectl -n datakit get service datakit-service -o yaml
kubectl -n datakit get endpointslice -l kubernetes.io/service-name=datakit-service -o wide
kubectl -n datakit logs daemonset/datakit --tail=100
本文明确使用 http/protobuf,Trace 上报地址为:
http://datakit-service.datakit.svc.cluster.local:9529/otel/v1/traces
这里配置的是 Trace 专用 Endpoint,必须包含完整路径。若修改了 DataKit Service、命名空间、集群 DNS 域或 HTTP 路由,应同步修改 Operator 规则。
安装并配置 DataKit Operator
若尚未安装,下载当前官方 Operator 清单。建议在单独目录中操作,避免与仓库中的旧版同名文件混淆;已有支持 OTel 的 Operator 时,编辑现有配置即可。
mkdir -p otel-demo
cd otel-demo
curl -fL --connect-timeout 10 --max-time 120 https://static.guance.com/datakit-operator/datakit-operator.yaml -o datakit-operator.yaml
kubectl create namespace datakit --dry-run=client -o yaml | kubectl apply -f -
安装 Operator 后还需手动配置 OTel 规则。 官方清单中的 admission_inject_v2.otels 默认为空数组 []。只安装 Operator,不会自动为 Java 应用注入 OpenTelemetry。
在清单中找到 ConfigMap 的 data.jsonconfig,定位 admission_inject_v2 下的 "otels": [],把下面这条 Java 规则放入数组;数组非空时追加规则,保留同级 ddtraces、logfwds 等现有配置。下面展示的是数组中的单条规则,不是完整 Operator 配置:
{
"name": "otel-java",
"language": "java",
"namespace_selectors": [
"*"
],
"label_selectors": [
"admission.datakit/otel-language=java"
],
"check_annotation": false,
"image": "ghcr.io/open-telemetry/opentelemetry-operator/autoinstrumentation-java:2.29.0",
"image_pull_policy": "IfNotPresent",
"envs": {
"POD_NAME": "{fieldRef:metadata.name}",
"POD_NAMESPACE": "{fieldRef:metadata.namespace}",
"NODE_NAME": "{fieldRef:spec.nodeName}",
"OTEL_SERVICE_NAME": "{fieldRef:metadata.labels['app']}",
"OTEL_RESOURCE_ATTRIBUTES": "k8s.pod.name=$(POD_NAME),k8s.namespace.name=$(POD_NAMESPACE),k8s.node.name=$(NODE_NAME)",
"OTEL_PROPAGATORS": "tracecontext,baggage",
"OTEL_TRACES_SAMPLER": "parentbased_always_on",
"OTEL_TRACES_EXPORTER": "otlp",
"OTEL_METRICS_EXPORTER": "none",
"OTEL_LOGS_EXPORTER": "none",
"OTEL_EXPORTER_OTLP_PROTOCOL": "http/protobuf",
"OTEL_EXPORTER_OTLP_TRACES_ENDPOINT": "http://datakit-service.datakit.svc.cluster.local:9529/otel/v1/traces"
},
"resources": {
"requests": {
"cpu": "100m",
"memory": "64Mi"
},
"limits": {
"cpu": "500m",
"memory": "512Mi"
}
}
}
规则通过语言标签选择 Pod,OTEL_SERVICE_NAME 从 app 标签读取,因此观测云中显示为 springboot-server。先声明 Pod、Namespace、Node 环境变量,再在 OTEL_RESOURCE_ATTRIBUTES 中引用,可随 Span 携带 Kubernetes 上下文。
示例固定探针镜像为 2.29.0,便于复现配置;截图本身未展示 Agent 版本,不据此认定当时使用了相同版本。无法拉取 GHCR 镜像时,可同步到可访问的私有仓库后替换 image。resources 配置的是探针 initContainer,并非业务 JVM 的 CPU、内存上限。
本次先开启 Trace,关闭 OTel Metric 和 Log 导出。parentbased_always_on 会采集新建根 Trace,并遵循已有父上下文的采样决定,适合低流量验证。保存配置后安装或更新 Operator:
kubectl apply -f datakit-operator.yaml
kubectl -n datakit rollout restart deployment/datakit-operator
kubectl -n datakit rollout status deployment/datakit-operator --timeout=5m
kubectl -n datakit logs deployment/datakit-operator --tail=100
应用 yaml 调整
以仓库中的 springboot-server-otel.yaml 为基础,保留业务镜像、语言标签和端口,并补充互斥注解。将下面内容保存为当前实践目录中的 springboot-server-otel.yaml:
apiVersion: apps/v1
kind: Deployment
metadata:
name: springboot-server
namespace: default
spec:
replicas: 1
selector:
matchLabels:
app: springboot-server
template:
metadata:
labels:
app: springboot-server
admission.datakit/otel-language: java
annotations:
admission.datakit/ddtrace.enabled: "false"
admission.datakit/otel.enabled: "true"
spec:
containers:
- name: springboot-server
image: registry.cn-shenzhen.aliyuncs.com/lr_715377484/springboot-server:flameshots
imagePullPolicy: IfNotPresent
ports:
- name: http
containerPort: 8080
protocol: TCP
标签和注解都必须位于 spec.template.metadata。关闭 ddtrace.enabled 可以避免 Demo 在 default 命名空间同时匹配 DDTrace 规则;otel.enabled 明确声明启用 OTel。
kubectl apply -f springboot-server-otel.yaml
kubectl -n default rollout status deployment/springboot-server --timeout=5m
kubectl -n default get pod -l app=springboot-server -o wide
首次部署,或修改 Pod 模板后应用清单,Deployment 会创建新 Pod。如果只修改了 Operator 规则,或者语言标签早已存在,现有 Pod 不会自动重新注入,需要主动滚动:
kubectl -n default rollout restart deployment/springboot-server
kubectl -n default rollout status deployment/springboot-server --timeout=5m
检查探针是否真正加载
Pod 处于 Running 不能单独证明注入成功。Operator 使用 fail-open 策略,跳过注入时业务仍可能正常启动。应同时检查 Pod 结构、启动环境和应用日志:
kubectl -n default get pod -l app=springboot-server -o yaml
kubectl -n default exec deployment/springboot-server -c springboot-server -- sh -c 'echo "$JAVA_TOOL_OPTIONS"; env | sort | grep "^OTEL_"'
kubectl -n default exec deployment/springboot-server -c springboot-server -- java -version
kubectl -n default logs deployment/springboot-server -c springboot-server --tail=100
正确注入后应看到以下内容:
datakit-otel-lib-initinitContainer;datakit-otel-auto-instrument共享卷和/otel-auto-instrumentation-java挂载目录;JAVA_TOOL_OPTIONS中的-javaagent:/otel-auto-instrumentation-java/javaagent.jar;OTEL_SERVICE_NAME=springboot-server、HTTP/Protobuf 协议以及正确的 Trace Endpoint。
initContainer 将探针复制到共享卷,JVM 启动时通过 Java Agent 加载自动插桩,业务启动命令仍可保持原样。已有启动脚本或 JVM 系统属性时,也要检查是否覆盖了注入的配置。
发送请求并验证观测云数据
原 Demo 清单只包含 Deployment。使用端口转发即可访问应用,不必额外配置 Service 或 Ingress。在一个终端保持以下命令运行:
kubectl -n default port-forward deployment/springboot-server 18080:8080
另一个终端访问 Demo 的网关入口,触发业务调用:
curl -i http://127.0.0.1:18080/gateway
也可直接访问 /billing 检查该接口;直接调用与经 /gateway 调用产生的 Trace 结构可能不同。请以实际响应及链路为准,不要求每次请求的 Span 数或耗时与截图一致。
进入观测云“应用性能监测 → 链路”,选择请求发生的时间范围,先按服务名筛选:
service:springboot-server
需要进一步确认数据来源时,可增加 source:opentelemetry 条件。打开一条链路,检查 HTTP 方法、路由、父子关系、耗时与错误状态,再查看扩展属性中的 Kubernetes 和 JVM 信息。
实践效果
HTTP 调用链与 Span 耗时
下面是本次 springboot-server Demo 的观测云截图。Span 列表和瀑布图页签显示该 Trace 包含 7 个 Span;当前火焰图视区可见 GET /gateway、HTTP 客户端 GET 和选中的 GET /billing。

图中 GET /gateway 显示耗时 8.77 ms,可见 HTTP 客户端 Span 为 1.57 ms,选中的 GET /billing 为 1.40 ms,错误 Span 数为 0。详情顶部的 1.40 ms 对应当前选中的 billing Span,不能当作整条网关请求的总耗时。
同一 Trace 中的调用层级和时间位置,使排查可以从入口请求继续定位到具体 HTTP 调用。截图右侧只显示 springboot-server 一个服务,因此这里展示的是该服务内的 HTTP 调用链;若要验收跨服务拓扑,还需多个已接入并正确传播上下文的服务参与调用。
Kubernetes 与 Java 运行上下文
截图中的链路扩展属性同时包含 k8s.namespace.name=default、k8s.pod.name 和 k8s.node.name,可将请求定位到具体实例。process.command_line 中可见 -javaagent:/otel-auto-instrumentation-java/javaagent.jar,运行时为 OpenJDK 1.8.0_402-b06。
这些信息说明链路已携带容器运行环境和 Java 探针加载信息。截图还展示了 service.version=0.0.1-SNAPSHOT,但本文最小规则未显式设置版本;后续推广时可统一从真实构建版本或 Pod 标签注入 service.version。
扩展 JVM 指标与日志关联
当前截图展示了 Trace 和资源属性,未展示 JVM 指标,且“日志”页签为 0。因此,本次效果可确认链路接入成功,JVM 指标与日志关联需分别开启并验收。
| 目标 | 配置与验收方式 |
|---|---|
| JVM Runtime 指标 | 将规则中的 OTEL_METRICS_EXPORTER 改为 otlp,增加下方 Metric Endpoint;重启 Operator 并滚动业务 Pod 后,在指标页面检查实际产生的 JVM 内存、GC、线程等指标。具体指标集取决于 Agent 版本。 |
| 容器日志关联 | 保留 OTEL_LOGS_EXPORTER=none,由 DataKit 采集 stdout 或日志文件;应用日志格式输出当前请求的 MDC 字段,并通过 Pipeline 提取为 trace_id、span_id,再验收链路页的日志关联。 |
| OTLP 日志导出 | 若选择 OTel 日志通道,将 OTEL_LOGS_EXPORTER 改为 otlp 并配置 Log Endpoint;确认应用日志框架受探针支持并避免同一日志被另一条通道重复采集。 |
OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=http://datakit-service.datakit.svc.cluster.local:9529/otel/v1/metrics
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=http://datakit-service.datakit.svc.cluster.local:9529/otel/v1/logs
Logback/Log4j 等受支持框架可在有活动 Span 的请求上下文中获得 OTel MDC 字段;日志模板仍需将字段实际输出。以日志格式片段为例:
trace_id=%X{trace_id} span_id=%X{span_id} trace_flags=%X{trace_flags}
开启 JVM 指标或日志并修改注入规则后,同样需要重启 Operator、重新创建业务 Pod,并通过实际请求确认页面数据。资源属性中出现 JVM 版本,并不等同于 JVM Runtime 指标已经采集。
常见问题与回滚
| 现象 | 优先检查 |
|---|---|
| Pod 正常运行但未注入 | Operator 是否不低于 v1.9.0;otels 是否仍为空;标签是否在 Pod 模板中;是否重新创建 Pod;是否匹配了 DDTrace 规则;查看 Operator warning。 |
| Pod 卡在初始化 | 查看 initContainer 状态与事件,检查探针镜像拉取、共享目录权限及 Pod 安全策略。 |
| 已注入但没有 Trace | 确认产生真实请求、DataKit 已启用 opentelemetry、Service 有可用后端、DNS 与网络可达,核对协议及完整 /otel/v1/traces 路径,再查看 Agent 导出错误。 |
| 页面找到服务但调用不完整 | 确认相关框架受自动插桩支持、上下游传播 tracecontext、采样决定一致,并选择覆盖请求时间的查询窗口。 |
| 链路日志为 0 | 检查应用是否在请求上下文内打印日志、trace_id/span_id 是否输出并正确解析,以及日志与链路是否进入同一工作空间。 |
若需要撤销 Demo 的 OTel 接入,在 Pod 模板中将 admission.datakit/otel.enabled 改为 "false" 并重新应用清单。Pod 模板变化会触发滚动,新 Pod 不再注入。只修改 Operator 或删除规则,不能卸载已运行 JVM 中的探针。
总结
以 springboot-server-otel.yaml 为入口,Java 应用通过语言标签和 DataKit Operator 完成自动注入,Trace 经 DataKit 上报后,可以在观测云中查看 HTTP 调用层级、Span 耗时及对应的 Kubernetes 实例信息。
接入验收需要贯穿三层:Operator 规则能够匹配,Pod 中探针真正加载,真实请求能在观测云查到。将这条路径验证清楚后,再逐步开启 JVM 指标、日志关联,并按生产流量设置采样率、固定探针版本和灰度升级策略。


