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 にはそれぞれルールを追加してください。
クイックスタート¶
- DataKit Operator をインストールし、DataKit OpenTelemetry コレクターを有効化します。アプリケーション Pod から DataKit Service に接続できることを確認してください。
- 言語に対応する Pod ラベルと、サービス名に使用する
appラベルを設定します。既定の Java ルールを使うか、対象のワークロード用のルールを追加してください。 - 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 に追加します。
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"
}
}
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"
}
}
注入とエージェントの選択¶
優先順位、相互排他、スイッチは注入ルールを参照してください。
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 の使用には、該当プロジェクトのオープンソースライセンスが適用されます。