コンテンツにスキップ

DataKit Operator による Beacon の注入

Beacon は DataKit Operator の推奨エージェントです。デプロイテンプレートの Java ルールはイメージ ghcr.io/beacon-observability/beacon-java:1.3.4@sha256:6d6316a2aae05cd926335bb3819a813ed0cae7d12faaf6497c2adf040a67b888 を使用し、default 名前空間で admission.datakit/beacon-language=java ラベルを持つ Pod のみに一致します。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 イメージは digest を固定し、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 のトレース

Linux amd64 または arm64 の Debian Bookworm(glibc)で Node.js 24 を使用してください。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 のトレース

Linux amd64 または arm64 の Debian Bookworm(glibc)で標準 GIL 版 CPython 3.13 を使用してください。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 で送信し、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 では、すべてのアプリケーションコンテナの command、args、JAVA_TOOL_OPTIONS、JDK_JAVA_OPTIONS、_JAVA_OPTIONS を確認します。起動引数内の $(VAR) を宣言順に解決し、元の構成を維持します。いずれかのコンテナがすでに APM エージェントを読み込む場合や、識別できない -javaagent を使う場合は、Pod 全体の tracing 注入をスキップします。JVM オプション変数が重複している場合、値が valueFrom から取得される場合、参照を解決できない場合も同様です。識別できた 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 を置き換え、元の digest を除去します。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 が出力されます。その場合でも基本的なトレースは送信されることがあります。既存の書き込み可能な一時ディレクトリを使用するか、次の例のように 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 コンテナの終了コードと JVM オプションを確認します。終了コードは 0 で、元の JVM オプションに -javaagent:/beacon-auto-instrumentation-java/javaagent.jar が 1 回だけ追加されます。

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 およびその他の貢献者に帰属します。Guance は DDTrace のデータ受信をサポートしています。DDTrace の使用には、該当プロジェクトのオープンソースライセンスが適用されます。

フィードバック

このページは役に立ちましたか?