Java のゼロコード計装¶

Beacon Java は単一の Agent JAR として配布されます。エージェントには JDK 対応のランタイムが必要で、Profile には JDK 11 以降が必要です。同じ JAR に任意で有効化できる Security 機能も含まれています。

接続前に共通設定を完了し、DataKit OpenTelemetry コレクターを有効にしてください。以下は Linux/macOS のシェルの例で、アプリケーションと DataKit が同じホストにあることを前提とします。別ホストやコンテナに配置する場合は、127.0.0.1 を置き換え、リッスンアドレスを調整してください。

インストール¶

Beacon Java のリリースページから完全版の Agent JAR をダウンロードし、現在のディレクトリに beacon-javaagent.jar として保存してください。

起動¶

export OTEL_SERVICE_NAME=my-java-service
export OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4317
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
java -javaagent:./beacon-javaagent.jar -jar app.jar

-javaagent は必ず -jar またはアプリケーションのメインクラスより前に指定し、既存の JVM 引数とアプリケーション引数はそのまま保持してください。

デバッグと診断¶

上記のサービス名と OTLP 設定を保持し、一時的に Agent のデバッグログを有効にして出力を保存します。

OTEL_JAVAAGENT_DEBUG=true \
  java -javaagent:./beacon-javaagent.jar -jar app.jar \
  > beacon-java-debug.log 2>&1

-jar より前に JVM 引数 -Dotel.javaagent.debug=true を追加する方法もあります。JVM のシステムプロパティは同名の環境変数より優先されます。このログで Agent の読み込み、計装対象の一致、エクスポートエラーを確認できます。

調査後は通常の起動コマンドに戻してください。サービス設定にこの変数や JVM 引数を追加した場合は、削除してアプリケーションを再起動します。

Profile¶

先に DataKit Profile コレクターを有効にし、以下の変数を設定して、上記の起動方法を引き続き使用してください。Profile は独立した HTTP アップロード先を使用し、OTLP Trace のアドレスとは共用しません。

Beacon Java Profile は実験的な機能で、既定では無効です。Java 11 以降と JFR 対応ランタイムが必要です。アプリケーションは Java ゼロコードガイドと同じ -javaagent コマンドで起動します。

HTTP でアップロード¶

互換 HTTP エクスポーターは、multipart/form-data で JFR スナップショットとメタデータを送信します。

export OTEL_SERVICE_NAME=my-java-service
export OTEL_PROFILING_ENABLED=true
export OTEL_PROFILING_EXPORTER=datakit
export OTEL_PROFILING_ENDPOINT=http://127.0.0.1:9529/profiling/v1/input
java -javaagent:./beacon-javaagent.jar -jar app.jar

datakit は現在の互換エクスポーターを選ぶ設定値です。受信側は main.jfr と event.json の 2 つの multipart フィールドをサポートする必要があります。既定のスナップショット間隔は 1 分です。

ローカル JFR ファイルに書き込む¶

受信側に依存せずに確認する場合は、file エクスポーターを使用できます。

mkdir -p profiles
export OTEL_PROFILING_ENABLED=true
export OTEL_PROFILING_EXPORTER=file
export OTEL_PROFILING_EXPERIMENTAL_FILE_EXPORT_PATH="$PWD/profiles"
java -javaagent:./beacon-javaagent.jar -jar app.jar

profiles/ に .jfr ファイルが生成されることを確認してください。本番環境で有効にする前に、ディスク上の保持方針を決め、アプリケーションの負荷をかけて性能への影響を検証してください。

任意のメモリーイベント¶

export OTEL_PROFILING_MEMORY_ENABLED=true

この設定は、標準の Profile テンプレートにメモリー分析向けの JFR 設定を追加します。

パラメーターリファレンス¶

環境変数名は大文字と小文字を区別します。期間の値は数値と ns、us、ms、s、m、h、d の単位で指定します。

環境変数	型 / 設定値	既定値	説明
`OTEL_PROFILING_ENABLED`	真偽値	`false`	JFR Profiler を有効にします。
`OTEL_PROFILING_INTERVAL`	正の期間	`1m`	JFR スナップショットの生成間隔。
`OTEL_PROFILING_STARTUP_DELAY`	0 以上の期間	`0s`	Profile 収集を開始するまでの待機時間。
`OTEL_PROFILING_MAX_AGE`	正の期間	`5m`	アクティブな JFR 録画でデータを保持する最大期間。
`OTEL_PROFILING_STACK_DEPTH`	正の整数	`64`	呼び出しスタックの最大深度。
`OTEL_PROFILING_MAX_SIZE`	0 以上の整数、バイト	`0`	アクティブな JFR 録画の最大サイズ。`0` は JFR の既定動作を使用します。
`OTEL_PROFILING_TEMP_DIR`	ディレクトリパス	未設定	JFR の一時データディレクトリ。未設定の場合はランタイムの一時ディレクトリの動作に従います。
`OTEL_PROFILING_MEMORY_ENABLED`	真偽値	`false`	メモリー分析を重視した JFR 設定を有効にします。
`OTEL_PROFILING_MEMORY_ALLOCATION_SAMPLING`	真偽値	未設定	設定すると JFR のメモリー割り当てサンプリングの有効化設定を上書きします。
`OTEL_PROFILING_MEMORY_OLD_OBJECT_SAMPLING`	真偽値	未設定	設定すると JFR の長寿命オブジェクトサンプリングの有効化設定を上書きします。
`OTEL_PROFILING_EXPORTER`	`none`、`file`、`datakit`	`none`	それぞれエクスポートなし、ローカル JFR ファイルへの書き込み、互換 HTTP multipart エクスポーターの使用を表します。
`OTEL_PROFILING_ENDPOINT`	HTTP(S) URL	`http://localhost:9529/profiling/v1/input`	`datakit` エクスポーターのアップロード先。
`OTEL_PROFILING_DATAKIT_TIMEOUT`	正の期間	`10s`	互換エクスポーターの HTTP アップロードタイムアウト。
`OTEL_PROFILING_EXPERIMENTAL_FILE_EXPORT_PATH`	ディレクトリパス	`${java.io.tmpdir}/otel-profiles`	`file` エクスポーターの出力先ディレクトリ。

datakit の値と対応するタイムアウト変数は、現在の Java Agent が必要とする互換識別子です。そのまま使用してください。

Security¶

同じ Agent から、任意で有効化するセキュリティ検出結果とランタイム SBOM を OpenTelemetry Logs でエクスポートできます。Java Security ガイドを参照してください。

接続の確認¶

対応するフレームワークやライブラリを経由するリクエストをアプリケーションの API に送り、Guance の「APM > トレース」で上記のサービス名を絞り込んでください。確認手順の詳細は共通設定を、データがない場合はトラブルシューティングを参照してください。