跳转至

DataKit Operator 注入 Beacon

Beacon 是 DataKit Operator 首推的探针。发布模板中的 Java 规则仅匹配 default 命名空间中带有 admission.datakit/beacon-language=java 标签的 Pod,使用镜像 ghcr.io/beacon-observability/beacon-java:1.3.4@sha256:6d6316a2aae05cd926335bb3819a813ed0cae7d12faaf6497c2adf040a67b888。Node.js、Python、OpenTelemetry 和 DDTrace 需添加各自的注入规则。

快速开始

  1. 安装 DataKit Operator,开启 DataKit OpenTelemetry 采集器,并确认业务 Pod 可以访问 DataKit Service。
  2. 给 Pod 添加对应语言标签和用作服务名的 app 标签。使用默认 Java 规则时可直接部署,其他场景需添加对应规则。
  3. 直接修改 ConfigMap 后,重启 Operator。重新创建业务 Pod,发起受探针支持的请求,按 OTEL_SERVICE_NAME 查询链路。

Java 运行时兼容性见所用 Beacon 发行版本。每条规则作用于 Pod 中的所有普通容器,请按语言选择工作负载。

默认 Java 镜像固定摘要,拉取策略为 IfNotPresent。如果节点无法访问 ghcr.io,请提前在节点预载相同镜像,或将镜像同步到节点可访问的仓库并更新规则的 image。

配置规则

下例为带 Java 标签的 Pod 启用 Beacon,匹配所有命名空间。把规则合并到 admission_inject_v2.beacons。

{
    "admission_inject_v2": {
        "beacons": [
            {
                "name": "beacon-java",
                "language": "java",
                "namespace_selectors": [
                    "*"
                ],
                "label_selectors": [
                    "admission.datakit/beacon-language=java"
                ],
                "check_annotation": false,
                "image": "ghcr.io/beacon-observability/beacon-java:1.3.4@sha256:6d6316a2aae05cd926335bb3819a813ed0cae7d12faaf6497c2adf040a67b888",
                "image_pull_policy": "IfNotPresent",
                "envs": {
                    "POD_NAME": "{fieldRef:metadata.name}",
                    "POD_NAMESPACE": "{fieldRef:metadata.namespace}",
                    "OTEL_SERVICE_NAME": "{fieldRef:metadata.labels['app']}",
                    "OTEL_RESOURCE_ATTRIBUTES": "k8s.pod.name=$(POD_NAME),k8s.namespace.name=$(POD_NAMESPACE)",
                    "OTEL_EXPORTER_OTLP_PROTOCOL": "http/protobuf",
                    "OTEL_EXPORTER_OTLP_ENDPOINT": "http://datakit-service.datakit.svc.cluster.local:9529/otel",
                    "OTEL_TRACES_EXPORTER": "otlp",
                    "OTEL_METRICS_EXPORTER": "none",
                    "OTEL_LOGS_EXPORTER": "none",
                    "OTEL_PROFILING_ENABLED": "false",
                    "BEACON_SECURITY_ENABLED": "false"
                }
            }
        ]
    }
}

HTTP/Protobuf 基础地址必须保留 /otel;设置 OTEL_EXPORTER_OTLP_TRACES_ENDPOINT 等信号专用变量时,须填写完整路径,例如 http://datakit-service.datakit.svc.cluster.local:9529/otel/v1/traces。信号专用变量优先于基础地址。

部署 Java 应用

将示例镜像换成自己的 Java 应用镜像。此 Deployment 同时匹配发布模板中的 Java 规则和上面的标签规则。

apiVersion: apps/v1
kind: Deployment
metadata:
  name: beacon-java-demo
  namespace: default
spec:
  replicas: 1
  selector:
    matchLabels:
      app: beacon-java-demo
  template:
    metadata:
      labels:
        app: beacon-java-demo
        admission.datakit/beacon-language: java
      annotations:
        admission.datakit/beacon.enabled: "true"
        admission.datakit/otel.enabled: "false"
        admission.datakit/ddtrace.enabled: "false"
    spec:
      containers:
        - name: app
          image: registry.example.com/apps/java-demo:1.0.0

Node.js 基础链路

使用 Debian Bookworm glibc 上的 Node.js 24,支持 Linux amd64 和 arm64。Operator 向 NODE_OPTIONS 追加以下预加载参数。

--import=/beacon-auto-instrumentation-nodejs/node_modules/@beacon-observability/nodejs/register.mjs

将规则添加到 admission_inject_v2.beacons,并在 Pod 模板中设置 admission.datakit/beacon-language: nodejs。

{
  "name": "beacon-nodejs",
  "language": "nodejs",
  "namespace_selectors": [
    "*"
  ],
  "label_selectors": [
    "admission.datakit/beacon-language=nodejs"
  ],
  "image": "ghcr.io/beacon-observability/beacon-nodejs:2.0.2@sha256:f9aeac2c291361db7696f6dd154f26b9dd6c2231bc6bbdc4ed20ef484c241f3e",
  "image_pull_policy": "IfNotPresent",
  "envs": {
    "OTEL_SERVICE_NAME": "{fieldRef:metadata.labels['app']}",
    "OTEL_EXPORTER_OTLP_ENDPOINT": "http://datakit-service.datakit.svc.cluster.local:9529/otel",
    "OTEL_EXPORTER_OTLP_PROTOCOL": "http/protobuf"
  }
}

Beacon Node.js 接入

Python 基础链路

使用 Debian Bookworm glibc 上的标准 GIL CPython 3.13,支持 Linux amd64 和 arm64。Operator 通过 PYTHONPATH 加载 sitecustomize.py,镜像包含 requests 插桩。

将规则添加到 admission_inject_v2.beacons,并在 Pod 模板中设置 admission.datakit/beacon-language: python。解释器需启用 site 和环境变量。探针包优先于应用默认的 site-packages。若应用有自定义 sitecustomize.py 或依赖冲突,请在该 Pod 上关闭 tracing 注入。

{
  "name": "beacon-python",
  "language": "python",
  "namespace_selectors": [
    "*"
  ],
  "label_selectors": [
    "admission.datakit/beacon-language=python"
  ],
  "image": "ghcr.io/beacon-observability/beacon-python:1.2.4@sha256:330cdcc062381af47668337fbdc56bec5a6211e77cea85fed6d91a1ebe280808",
  "image_pull_policy": "IfNotPresent",
  "envs": {
    "OTEL_SERVICE_NAME": "{fieldRef:metadata.labels['app']}",
    "OTEL_EXPORTER_OTLP_ENDPOINT": "http://datakit-service.datakit.svc.cluster.local:9529/otel",
    "OTEL_EXPORTER_OTLP_PROTOCOL": "http/protobuf"
  }
}

Beacon Python 接入

注入与互斥

优先级、互斥和开关见注入规则。

若 Pod 已有 tracing init Container、专用卷或挂载,Operator 会保留现有探针。Webhook 再次调用时也会跳过 Beacon 注入。修改探针配置后应重新创建 Pod。

规则中的环境变量按配置顺序添加,业务容器中显式声明的同名 env 优先。默认使用 OTLP 导出 Trace,Metric、Log、Profile 和 Security 默认关闭。

如果 JAVA_TOOL_OPTIONS、NODE_OPTIONS 或 PYTHONPATH 可能由 envFrom 提供且未显式声明,Beacon 会跳过该 Pod,避免覆盖原值。需要注入时,请先在容器的 env 中声明对应启动变量并保留原值。

Java 启动参数

Operator 添加 datakit-beacon-lib-init,从镜像的 /javaagent.jar 复制到 EmptyDir datakit-beacon-auto-instrument。业务容器只读挂载 /beacon-auto-instrumentation-java,并向 JAVA_TOOL_OPTIONS 追加 -javaagent:/beacon-auto-instrumentation-java/javaagent.jar。

对于 Java,Operator 检查所有业务容器的 command、args、JAVA_TOOL_OPTIONS、JDK_JAVA_OPTIONS 和 _JAVA_OPTIONS。它按声明顺序解析启动参数中的 $(VAR),保留原始配置。任一容器已加载 APM 探针、使用无法识别的 -javaagent,或 JVM 参数重复、来自 valueFrom 或引用无法解析时,都会跳过整个 Pod 的 tracing 注入。已识别的 JaCoCo 可以与 APM 探针共存。

Operator 只检查 Pod 中可见的启动参数。如果已有探针通过 JVM @file 或 envFrom 中的配置加载,请设置 admission.datakit/tracing.enabled: "false"。

开关、版本与权限

admission.datakit/beacon.enabled: "false" 禁用 Beacon。启用 check_annotation: true 时,Pod 需设置 admission.datakit/beacon-<language>-lib.version,其中 <language> 为 java、nodejs 或 python。其值替换镜像 tag,例如 1.3.4,并移除原 digest。使用固定镜像摘要时,保持 check_annotation: false。

新增 init Container 默认使用 UID/GID 65532,启用 runAsNonRoot、只读根文件系统、禁用提权并丢弃所有 capabilities。Pod 已指定非零 UID 时沿用该 UID,已指定 GID 时沿用该 GID;已有 Pod seccomp 配置会继承,否则使用 RuntimeDefault。不会修改业务容器权限或 Pod 的 fsGroup。自定义探针镜像须保留对应语言的目录布局,并允许 init 容器读取探针文件和写入 EmptyDir。

只读根文件系统

Beacon Java 1.3.4 启动时会在临时目录解包内置扩展。如果业务容器设置了 readOnlyRootFilesystem: true 且 /tmp 不可写,JVM 日志会出现 Failed to open embedded extensions。基础 Trace 仍可能上报。已有可写临时目录可直接复用,下面的示例为 app 容器单独挂载一个可写的 emptyDir。

spec:
  template:
    spec:
      volumes:
        - name: java-tmp
          emptyDir: {}
      containers:
        - name: app
          volumeMounts:
            - name: java-tmp
              mountPath: /tmp

Java 可选能力

Metric、Log、Profile 和 Security 通过规则或业务环境变量显式启用。Security 需要 OTEL_LOGS_EXPORTER=otlp;Profile 需要支持 JFR 的运行时、DataKit Profile 采集器及独立的 OTEL_PROFILING_ENDPOINT。本功能不会自动添加 profiler sidecar。可选能力的兼容性以对应 Beacon 发行版本为准。

具体的运行时要求、信号开关和导出配置参见 Beacon Java 接入文档。将 Profile 发送到 DataKit 时还需设置 OTEL_PROFILING_EXPORTER=datakit。

验证 Java 注入和链路

在示例 Deployment 就绪后,查看 init Container 的退出码和 JVM 参数。预期退出码为 0,原有参数中仅追加一次 -javaagent:/beacon-auto-instrumentation-java/javaagent.jar。

kubectl -n default rollout status deployment/beacon-java-demo
pod=$(kubectl -n default get pods -l app=beacon-java-demo -o jsonpath='{.items[0].metadata.name}')
kubectl -n default get pod "$pod" -o jsonpath='{.status.initContainerStatuses[?(@.name=="datakit-beacon-lib-init")].state.terminated.exitCode}{"\n"}'
kubectl -n default get pod "$pod" -o jsonpath='{.spec.containers[?(@.name=="app")].env[?(@.name=="JAVA_TOOL_OPTIONS")].value}{"\n"}'
kubectl -n default logs "$pod" -c app

未注入或 init 容器失败时,见通用排查。 已注入但没有链路时,检查 DataKit 采集器、OTLP 地址及已有 OTEL_* 或 JVM -D 参数。回滚时关闭 Beacon 规则或设置 admission.datakit/beacon.enabled: "false",然后重建 Pod。

DDTrace 是由 Datadog 发起并开源的链路追踪项目,相关著作权归 Datadog 及其他贡献者所有。观测云支持 DDTrace 的数据上报,具体使用遵循相应项目的开源许可证。

文档评价

文档内容是否对您有帮助?