Java環境での計装 - エージェントとSpring Boot統合ガイド ​

JavaアプリケーションをOpenTelemetryで計装する方法は複数あります。コードを変更しない自動計装から、Spring Boot Starterを使用した統合まで、様々なアプローチが可能です。このガイドでは、最も一般的な2つの方法と、実装時のポイントを説明します。

Java計装アーキテクチャの概観 ​

Javaでの計装には大きく2つのアプローチがあります。一つはJavaエージェントを使用した自動計装で、もう一つはSDK（Software Development Kit）を依存関係として追加する方法です。

JavaエージェントJARの導入 ​

JARファイルの取得 ​

OpenTelemetryのJavaエージェントは、Maven Central Repositoryから取得できます。現在の最新バージョンは公式ドキュメントで確認しますが、以下のようにダウンロードできます。

bash
# エージェントJARのダウンロード例
wget https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/download/v2.x.x/opentelemetry-javaagent.jar

エージェントJARは単一ファイルで、アプリケーションの起動時に指定するだけで、自動的にテレメトリを収集します。

JVM起動オプションの設定 ​

エージェントを有効にするには、JVM起動時に -javaagent オプションを指定します。最小限の設定では以下の通りです。

bash
java -javaagent:./opentelemetry-javaagent.jar \
     -Dotel.exporter.otlp.endpoint=http://localhost:4317 \
     -Dotel.service.name=my-java-app \
     -jar application.jar

主要なオプションを説明します。otel.exporter.otlp.endpoint はトレースやメトリクスを送信するCollectorのエンドポイントを指定します。otel.service.name はアプリケーション識別名で、テレメトリデータに含まれます。otel.exporter.otlp.protocol ではプロトコルを指定でき、デフォルトではgrpcですがhttpに変更することもできます。

Spring Boot統合アプローチ ​

Spring Boot Starterの利用 ​

Spring Bootアプリケーションでは、JavaエージェントよりもSpring Boot Starterを使用する方がより統合度が高く、設定も簡単です。特にネイティブイメージ対応が必要な場合は、Starterが推奨されます。

依存関係の追加 ​

Maven を使用する場合、pom.xml に以下のように依存関係を追加します。

xml
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>io.opentelemetry.instrumentation</groupId>
            <artifactId>opentelemetry-instrumentation-bom</artifactId>
            <version>2.x.x</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<dependencies>
    <dependency>
        <groupId>io.opentelemetry.instrumentation</groupId>
        <artifactId>opentelemetry-spring-boot-starter</artifactId>
    </dependency>
</dependencies>

Gradle を使用する場合は以下の通りです。

gradle
dependencyManagement {
    imports {
        mavenBom "io.opentelemetry.instrumentation:opentelemetry-instrumentation-bom:2.x.x"
    }
}

dependencies {
    implementation "io.opentelemetry.instrumentation:opentelemetry-spring-boot-starter"
}

重要なのは、BOM（Bill of Materials）を使用することで、各コンポーネントのバージョンが自動的に統一されます。これにより、依存関係の互換性問題を防げます。

application.propertiesでの設定 ​

Spring Bootでは、標準的な設定ファイルで OpenTelemetry を設定できます。

properties
# サービス識別名
otel.service.name=my-spring-boot-app

# Collectorエンドポイント（OTLP gRPC）
otel.exporter.otlp.endpoint=http://localhost:4317

# トレースのサンプリング比率 (例: 1.0 = 100%)
otel.traces.sampler=parentbased_traceidratio
otel.traces.sampler.arg=1.0

# ログエクスポート有効化
otel.logs.exporter=otlp
otel.metrics.exporter=otlp

otel.traces.sampler.arg は重要な設定です。値が1.0の場合はすべてのトレースを収集し、0.1なら10%のみを収集します。本番環境ではログ量とコストを考慮して適切な値を設定しましょう。

環境変数での動的設定 ​

開発環境と本番環境で異なる設定が必要な場合、環境変数を使用することで、コードの再コンパイルなしに設定を切り替えられます。

bash
export OTEL_SERVICE_NAME=production-app
export OTEL_EXPORTER_OTLP_ENDPOINT=https://collector.production.example.com
export OTEL_TRACES_SAMPLER_ARG=0.1

Kubernetes環境では、configmapやシークレットから環境変数を注入することで、デプロイメント時に設定を一元管理できます。

どのアプローチを選ぶべきか ​

Javaエージェント方式は、既存のアプリケーションに最小限の変更で導入できる利点があります。Dockerコンテナに含める際も、起動スクリプトのオプション変更のみで済みます。

一方、Spring Boot Starterアプローチは、Spring自体の設定ファイルで統制でき、ネイティブイメージ対応も可能です。また、OpenTelemetry APIを直接使用して、独自のスパンやメトリクスを追加する際にも、より統合的にコード化できます。

新規プロジェクトであればStarter方式、既存プロジェクトへの導入ならエージェント方式が一般的ですが、チームの技術方針や環境に応じて選択しましょう。次のステップでは、実装後のテレメトリデータの確認方法や、トラブルシューティング手法を学んでいきます。