Skip to content

Inject Beacon with DataKit Operator

Beacon is the recommended agent for DataKit Operator. The shipped Java rule uses ghcr.io/beacon-observability/beacon-java:1.3.4@sha256:6d6316a2aae05cd926335bb3819a813ed0cae7d12faaf6497c2adf040a67b888 and matches only Pods labeled admission.datakit/beacon-language=java in the default namespace. Add separate rules for Node.js, Python, OpenTelemetry, and DDTrace.

Quick Start

  1. Install DataKit Operator, enable the DataKit OpenTelemetry input, and confirm that application Pods can reach the DataKit Service.
  2. Label the Pod for your language and set the app label used as the service name. Use the shipped Java rule as is or add a rule for your workload.
  3. Restart the Operator after editing its ConfigMap directly. Recreate the application Pods, make a request supported by the agent, and look up traces by OTEL_SERVICE_NAME.

Check Java runtime compatibility in the selected Beacon release. Rules apply to all regular containers in a Pod. Select workloads by language.

The default Java image is pinned to a digest and uses IfNotPresent. If nodes cannot reach ghcr.io, preload that image on the nodes or mirror it to a registry they can reach and update the rule’s image.

Configuration Rules

This rule enables Beacon for Pods with the Java label across all namespaces. Merge it into 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"
                }
            }
        ]
    }
}

The HTTP/Protobuf base endpoint must retain /otel. Signal-specific variables such as OTEL_EXPORTER_OTLP_TRACES_ENDPOINT require a complete path, for example http://datakit-service.datakit.svc.cluster.local:9529/otel/v1/traces. Signal-specific variables take precedence over the base endpoint.

Deploy a Java Application

Replace the image with your Java application image. This Deployment matches both the shipped Java rule and the label rule above.

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 tracing

Use Node.js 24 on Debian Bookworm with glibc, on Linux amd64 or arm64. The Operator adds the following preload to NODE_OPTIONS.

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

Add this rule to admission_inject_v2.beacons and set admission.datakit/beacon-language: nodejs in the Pod template.

{
  "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 guide

Python tracing

Use standard GIL CPython 3.13 on Debian Bookworm with glibc, on Linux amd64 or arm64. The Operator loads sitecustomize.py through PYTHONPATH. The image includes requests instrumentation.

Add this rule to admission_inject_v2.beacons and set admission.datakit/beacon-language: python in the Pod template. Keep site and environment variable processing enabled. The bundled packages take precedence over the application’s default site-packages. Disable tracing injection for Pods with a custom sitecustomize.py or conflicting dependencies.

{
  "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 guide

Injection and Agent Selection

See Injection rules for agent priority, mutual exclusion, and switches.

If the Pod already has a tracing init container, dedicated volume, or mount, the Operator preserves the existing agent and skips Beacon injection when the webhook runs again. Recreate the Pod to apply agent configuration changes.

Rule environment variables are added in configuration order. Explicit application env entries with the same name take precedence. By default, traces are exported via OTLP and metrics, logs, profiling, and security are disabled.

Beacon skips a Pod if JAVA_TOOL_OPTIONS, NODE_OPTIONS, or PYTHONPATH might come from envFrom and is not declared explicitly. To enable injection, declare the relevant startup variable in the container’s env and keep its original value.

Java Startup Options

The Operator adds datakit-beacon-lib-init to copy /javaagent.jar from the image into the EmptyDir datakit-beacon-auto-instrument. Application containers mount /beacon-auto-instrumentation-java read-only and receive -javaagent:/beacon-auto-instrumentation-java/javaagent.jar appended to JAVA_TOOL_OPTIONS.

For Java, the Operator checks command, args, JAVA_TOOL_OPTIONS, JDK_JAVA_OPTIONS, and _JAVA_OPTIONS in every application container. It resolves $(VAR) in startup arguments in declaration order and preserves the original configuration. It skips tracing for the entire Pod if any container already loads an APM agent, uses an unrecognized -javaagent, or has duplicate JVM option variables, values from valueFrom, or unresolved references. Recognized JaCoCo agents can coexist with APM instrumentation.

The Operator checks the startup options visible in the Pod. If the application already loads an agent through a JVM @file or configuration from envFrom, set admission.datakit/tracing.enabled: "false".

Switches, Versions, and Permissions

admission.datakit/beacon.enabled: "false" disables Beacon. With check_annotation: true, the Pod must set admission.datakit/beacon-<language>-lib.version, where <language> is java, nodejs, or python. The value replaces the image tag, for example 1.3.4, and removes the original digest. Keep check_annotation: false when pinning a digest.

The new init Container defaults to UID/GID 65532, with runAsNonRoot, a read-only root filesystem, privilege escalation disabled, and all capabilities dropped. An explicit nonzero Pod UID and an explicit Pod GID are respected. An existing Pod seccomp profile is inherited; otherwise, RuntimeDefault is used. Application container permissions and Pod fsGroup are unchanged. Custom agent images must preserve the directory layout for the selected language and allow the init container to read agent files and write to the EmptyDir.

Read-only Root Filesystem

Beacon Java 1.3.4 extracts its embedded extensions into a temporary directory at startup. If the application container sets readOnlyRootFilesystem: true and /tmp is read-only, the JVM logs Failed to open embedded extensions. Basic traces may still arrive. Reuse an existing writable temporary directory, or mount a writable emptyDir in the app container as shown below.

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

Optional Java Features

Enable Metric, Log, Profile, and Security explicitly through rule or application environment variables. Security requires OTEL_LOGS_EXPORTER=otlp. Profile requires a JFR-capable runtime, the DataKit Profile input, and a separate OTEL_PROFILING_ENDPOINT. This feature does not automatically add a profiler sidecar. Optional feature compatibility is defined by the corresponding Beacon release.

See the Beacon Java guide for runtime requirements, signal settings, and exporter configuration. To send profiles to DataKit, also set OTEL_PROFILING_EXPORTER=datakit.

Verify Java Injection and Traces

Once the example Deployment is ready, inspect the init container exit code and JVM options. Expect exit code 0 and a single -javaagent:/beacon-auto-instrumentation-java/javaagent.jar alongside the original JVM options.

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

For missing injection or init container failures, see General troubleshooting. If injection succeeds but traces are missing, check the DataKit input, OTLP endpoint, and existing OTEL_* or JVM -D options. To roll back, disable the Beacon rule or set admission.datakit/beacon.enabled: "false", then recreate the Pods.

DDTrace is a tracing project initiated and open-sourced by Datadog. Copyright belongs to Datadog and other contributors. Guance supports DDTrace data ingestion. Use of DDTrace is subject to the applicable project's open-source license.

Feedback

Is this page helpful?