Spring Boot OpenTelemetry導入｜2つのstarterの違いとMaven設定

Spring BootにOpenTelemetryを入れようとして最初につまずくのは、名前がほぼ同じで中身が違うstarterが2つ存在することです。spring-boot-starter-opentelemetry と opentelemetry-spring-boot-starter。語順が逆なだけに見えますが、提供元も設定キーもテレメトリの命名規約も別物で、取り違えると依存解決の時点でビルドが落ちるか、書いた設定キーが一切効きません。2026年7月時点の一次情報をもとに、どちらを選ぶか・Mavenにどう書くか・OTLPの送信先をどのプロパティで指定するかを整理します。

まとめ

• Spring Boot 4系：org.springframework.boot:spring-boot-starter-opentelemetry（Spring Boot 4.0で追加）が既定の選択。バージョン指定は不要で、設定は management.* プロパティ。
• Spring Boot 2.6〜3.x：io.opentelemetry.instrumentation:opentelemetry-spring-boot-starter（最新2.30.0）。公式starterは3系には存在しません。BOMで版を揃え、設定は otel.* プロパティ。
• OpenTelemetry版starterも実装上はSpring Boot 4に対応済み（2.23.0／2025年12月13日）です。公式ドキュメントの対応表記が2.6+と3.1+のまま更新されていないだけなので、4系でも選択肢に入ります。
• 2つの経路はメトリクス名やスパン属性の命名規約が異なります。片方から片方へ乗り換えると、既存のダッシュボードとアラートは作り直しになります。
• Spring Boot 3.5は2026年6月30日にOSSサポートが終了し、3系は全ブランチがOSS未サポートです。3系への新規導入を検討しているなら、計装より先に4系への移行を置くのが順当です。

同名2starterの見分け方｜groupIdとartifactIdの並びが示す別物

まず、検索で流れてくる2つの名前を正確に分離します。判別はartifactIdの語順ではなく、groupIdを見るのが確実です。

OpenTelemetryそのものの構成要素（3つのシグナル、OTLP、Collector）を先に押さえたい場合は、OpenTelemetry（OTel）の基礎解説を読んでおくと、以下の設定が何を送っているのか掴みやすくなります。

Spring Boot 4.0で追加された公式starterの中身（4.1.0の実依存7件）

spring-boot-starter-opentelemetry はSpring Boot 4.0（2025年11月20日公開）で追加されました。Maven Centralに公開されている4.1.0のPOMを開くと、実際に引き込まれる依存は7件です。

• spring-boot-starter／spring-boot-starter-micrometer-metrics／spring-boot-micrometer-tracing-opentelemetry／spring-boot-opentelemetry
• io.micrometer:micrometer-registry-otlp 1.17.0（メトリクスのOTLP送出）
• io.micrometer:micrometer-tracing-bridge-otel 1.7.0（トレースをOpenTelemetry APIへ橋渡し）
• io.opentelemetry:opentelemetry-exporter-otlp 1.62.0（OTLPエクスポーター本体）

注目すべきは、この一覧に spring-boot-starter-actuator が含まれていない点です。Spring Boot 4のモジュール分割により、Actuator全体を抱え込まずに可観測性だけを足せるようになりました。3系まではMicrometer関連とOpenTelemetry関連の依存を手で数行並べる必要があり、その手作業がstarter 1件に畳まれた形です。Spring Boot 4そのものの変更点はSpring Boot 4の新機能と3系との違いにまとめています。

OpenTelemetry版starterの対応範囲｜docs表記2.6+/3.1+と実装のずれ

もう一方の io.opentelemetry.instrumentation:opentelemetry-spring-boot-starter は、OpenTelemetry Java Instrumentationの一部として配布されています。最新は2.30.0で、Maven Centralのメタデータ更新は2026年7月22日です。

対応範囲について公式ドキュメントは「works with Spring Boot 2.6+ and 3.1+, and Spring Boot native image applications」と記載しており、4.xが出てきません。ただしこれは実装の制約ではなくドキュメントの更新漏れです。CHANGELOGのVersion 2.23.0（2025年12月13日）に「Spring starter: support Spring Boot 4」が入り、2.24.0（2026年1月17日）でSpring Boot 4のRestClient対応、2.27.0（2026年4月21日）でSpring Boot 4環境のmetricsモジュール不在に起因する不具合が修正されています。追跡用のissue #14906「Support Spring boot 4」も2026年1月30日にcompletedでクローズ済みです。

つまり4系でOpenTelemetry版starterを使う構成は実際に動きます。残るリスクは、ドキュメントに明記がないぶん将来の非互換が告知なく入る可能性を否定しきれない点だけです。

選び分けの判断軸｜Bootのバージョンと命名規約で決まる

Spring Boot 3系では公式starterが存在しないため、starterとしての選択肢はOpenTelemetry版だけです（starter以外の手段としてJavaエージェントがあり、使い分けは後述します）。

迷うのはSpring Boot 4系で、ここは両方が使えます。判断軸は3つです。既存の監視がMicrometerのメトリクス名やActuatorのエンドポイント前提で組まれているなら公式starter。バックエンド側のダッシュボードやアラートがOpenTelemetryのセマンティック規約を前提にしているならOpenTelemetry版。計装できる範囲を最大化したいなら、starterではなくJavaエージェントです。

もうひとつ、土台であるSpring Boot側の期限も判断に入れてください。Spring Boot 3.5は最終OSSリリース3.5.16（2026年6月25日）を最後に、6月30日でOSSサポートを終えました。3.4以前も終了済みで、2026年7月時点で3系は全ブランチがOSS未サポートです。パッチの出ないランタイムの上に計装を積んでも、拾えるのはアプリの挙動だけで、フレームワーク側の脆弱性は塞がりません。工数を割けるなら先に4系への移行に充て、移行後に公式starterを1行足すほうが作業量も少なく済みます。ただしTanzuの商用サポート契約があれば話は別で、3.5の商用サポートは2032年6月30日までです。当面延命する前提が立つなら、3系にOpenTelemetry版starterを入れる判断も成立します。

4系ではOSSサポートが4.0は2026年12月31日、4.1は2027年7月31日までです。新規に選ぶなら4.1（4.1.0は2026年6月10日公開）が妥当でしょう。各ブランチの期限はSpring Bootのバージョン一覧とサポート期限で確認できます。

Spring Boot 4系の導入手順｜依存1行とOTLPプロパティ3行

Spring Boot 4.1の前提条件はJava 17〜26、Spring Framework 7.0.8以上、Maven 3.6.3以上またはGradle 8.14以上（9.x可）です。この条件を満たしていれば、導入は依存の追加とプロパティの指定だけで完了します。

pom.xmlとbuild.gradleへの追加（version指定なし）

Spring Bootの依存管理下にあるため、バージョンは書きません。

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-opentelemetry</artifactId>
</dependency>

Gradleの場合は次の1行です。start.spring.ioからプロジェクトを生成するなら、依存の選択画面で「OpenTelemetry」を選ぶと同じものが入ります。

implementation 'org.springframework.boot:spring-boot-starter-opentelemetry'

OTLP送信先の指定｜メトリクスだけ異なるキー体系

送信先はシグナルごとに指定します。ここに実務上の落とし穴があります。トレースとログは management.opentelemetry.*.export.otlp.endpoint という体系ですが、メトリクスだけが management.otlp.metrics.export.url と別体系です。Micrometerのレジストリ側の設定を引き継いでいるためで、規則から推測して書くと必ず外します。

management.otlp.metrics.export.url=http://localhost:4318/v1/metrics
management.opentelemetry.tracing.export.otlp.endpoint=http://localhost:4318/v1/traces
management.opentelemetry.logging.export.otlp.endpoint=http://localhost:4318/v1/logs

この非対称はSpring Boot側でも認識されていて、統一を求めるissue #50202が2026年4月24日に起票されました。同issueは2026年7月23日に重複としてクローズされ、統一の検討は #47962「Make it easier to configure OTLP exports」（オープン、マイルストーン4.x）へ引き継がれています。作業は継続中ですが、4.1時点ではこの書き分けが必要です。

トレースとログの自動構成は @ConditionalOnProperty でエンドポイントの指定を条件にしており（v4.1.0の OtlpTracingConfigurations／OtlpLoggingConfigurations）、指定しなければ何も送られません。一方メトリクスのURLは既定値が http://localhost:4318/v1/metrics のため、ローカルのCollectorへ送るだけなら省略できます。「メトリクスだけ勝手に飛ぶ」ように見えるのはこの差です。なおポート4318はOTLP/HTTPで、gRPC（4317）を使うなら management.opentelemetry.tracing.export.otlp.transport=grpc のように明示します（既定は http）。

サンプリング既定10%とDevToolsによる上書き

トレースの取りこぼしで多い原因が、サンプリング率の既定値です。management.tracing.sampling.probability の既定は0.1、つまり10%しか送られません。

management.tracing.sampling.probability=1.0

ただし開発環境では全件届いて見えることがあります。spring-boot-micrometer-tracing の META-INF/spring-devtools.properties に defaults.management.tracing.sampling.probability=1.0 が入っており、DevToolsが有効な環境では既定が100%へ上書きされるためです。開発では全件見えていたのに本番で9割消える、という食い違いはここから生まれます。本番で1.0にすると送信量と保管コストが10倍になるので、サービス単位で調整するかCollector側でテールサンプリングを組みます。サンプラー種別は management.opentelemetry.tracing.sampler で変えられますが、既定の parent-based-trace-id-ratio のままで足りるケースがほとんどです。

サービス名とリソース属性の指定

サービス名は spring.application.name がそのまま使われます。明示的に上書きするなら management.opentelemetry.resource-attributes.service.name です。同じ接頭辞で任意のリソース属性を足せるので、複数インスタンスを区別したいときはインスタンスIDを入れておきます。

management.opentelemetry.resource-attributes.service.instance.id=${HOSTNAME:local-dev}

ログをOTLPで送る場合、Logbackのアペンダー側にも設定項目があります。management.opentelemetry.instrumentation.logback-appender.capture-experimental-attributes や capture-key-value-pair-attributes を有効にすると、ログイベントに付随する属性まで送出できます。

Spring Boot 3系の導入手順｜BOM 2.30.0で版を揃えるOpenTelemetry版

3系に残る前提で導入する場合は、OpenTelemetry版starterを使います。設定キーの体系がSpring Boot 4系とはまったく別になる点に注意してください。

BOM importで版を揃える理由

OpenTelemetryのモジュールは相互のバージョン整合が前提のため、公式ドキュメントもBOMの利用を推奨しています。個別にバージョンを書いて混在させると版整合が崩れ、起動時に初めて発覚する形の失敗につながります。

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

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

otel.*プロパティとservice.nameの解決順6段階

設定は application.properties／application.yaml、環境変数、プログラムによる指定のいずれでも可能です。環境変数がファイル側の値を上書きする、通常のSpring Bootの優先順位に従います。

otel:
  propagators:
    - tracecontext
    - baggage
  resource:
    attributes:
      deployment.environment: staging
      service:
        name: order-api
        namespace: ec-backend

サービス名は6段階で解決されます。優先度の高い順に、otel.service.name（または OTEL_SERVICE_NAME）、otel.resource.attributes 内の service.name、spring.application.name、build-info.properties、META-INF/MANIFEST.MF の Implementation-Title、そして既定値の unknown_service:java です。バックエンドで unknown_service:java が並んでいたら、この5段すべてが未設定だという意味になります。計装ごと止めたいときは otel.sdk.disabled=true です。

既定で有効な計装9件と既定無効のMicrometerブリッジ

追加設定なしで計装されるのは、JDBC、Logback、Logback MDC、Spring Web、Spring Web MVC、Spring WebFlux、Kafka、MongoDB、R2DBCです。ここで挙動が分かれるのがMicrometerブリッジで、これだけは既定で無効になっています。既存のMicrometerメトリクスをOTLPで一緒に送りたい場合は otel.instrumentation.micrometer.enabled=true を明示してください。

逆に不要な計装を切りたい場合は、otel.instrumentation.common.default-enabled=false で既定を一括無効にし、使うものだけを個別に有効化します。JDBCのSQL文サニタイズやHTTPヘッダーの取得可否も、計装単位のプロパティで制御できます。

OTEL_LOG_LEVELが効かないJava環境でのデバッグログ設定

「テレメトリが届かないのでエージェントのログを出したい」という場面で OTEL_LOG_LEVEL=debug を設定しても、Javaでは何も変わりません。この環境変数はJavaScript SDKやOpenTelemetry Collectorの設定で使われるもので、opentelemetry-java-instrumentationのリポジトリには参照が1件もありません。検索でこのキーワードに行き着いた場合、まずここが原因である可能性が高いと考えてください。

Javaエージェントでデバッグ出力を有効にするのは OTEL_JAVAAGENT_DEBUG=true、システムプロパティなら -Dotel.javaagent.debug=true です。出力先は otel.javaagent.logging（環境変数 OTEL_JAVAAGENT_LOGGING）で切り替えられ、標準エラーへINFO以上を出す simple（既定）、何も出さない none、アプリケーション側のslf4jロガーへ流す application の3モードがあります。Spring Bootのログ設定に載せて扱いたいなら application が適しています。

これらはいずれもJavaエージェント固有の設定です。starter経由（公式版・OpenTelemetry版のいずれも）で導入している場合はエージェントが動いていないため、通常のSpring Bootのロギング設定でSDK関連パッケージのログレベルを上げる形になります。アプリのログ自体をOTLPで送りたい場合の設定は、Spring Boot 4系なら前述の management.opentelemetry.logging.export.otlp.endpoint です。

Javaエージェントとstarterの使い分け｜native imageと起動オーバーヘッドが判断軸

OpenTelemetryはstarterのほかに、JVM起動時に -javaagent で差し込むJavaエージェントも提供しています。公式ドキュメントは、エージェントのほうがstarterより「More out of the box instrumentation」＝標準で計装できる範囲が広いとして、既定の選択肢に置いています。コードにも依存にも手を入れずに済むため、既存アプリへの後付けではエージェントが素直です。

それでもstarterを選ぶべき条件として、公式は5項目を挙げています。GraalVMのnative imageでビルドしている（エージェントは動作しない）、起動時のオーバーヘッドが許容できない、別のJava監視エージェントと競合する、設定を application.properties／application.yaml に集約したい、YAMLによる宣言的な構成で書きたい。特にnative imageは代替手段がないため、そこだけで決まります。

裏を返せば、5条件のどれにも当てはまらずSpring Boot 3系のまま運用を続けるアプリでは、starterを入れるよりJavaエージェントを被せるほうが計装範囲を広く取れます。

経路の乗り換えで壊れるもの｜Micrometer規約とOTelセマンティック規約の非互換

Spring Boot 3系＋OpenTelemetry版starterの環境を、Spring Boot 4系＋公式starterへ移す場面で最も見落とされるのがテレメトリの命名規約です。公式starterは内部でMicrometerのObservation APIとレジストリを経由してOTLPを吐くため、メトリクス名や属性はMicrometerの命名規約に従います。一方、OpenTelemetry版starterはOpenTelemetryのセマンティック規約で出力します。Spring Boot公式ドキュメント自身が、OpenTelemetryが提供する計装手段（Javaエージェントとstarter）について「supported by the OTel community; the metrics and traces use the semantic conventions defined by OTel libraries」と、規約が別である点を明示して区別しています。

実務上は、依存を差し替えた瞬間にバックエンドへ届くメトリクス名とスパン属性のキーが変わります。既存のダッシュボードのクエリは空を返し、そこに紐づくアラートは「データなし」で沈黙する。障害検知が止まったことに誰も気づかない、という最悪の形になりかねません。

対処は単純で、切り替えを一度にやらないことです。新旧を並行稼働させる期間を取り、新しい命名でダッシュボードとアラートを組み直し、両方が同じ事象を検知することを確認してから旧経路を落とします。ステージングだけで済ませると、本番固有のメトリクス（バッチや外部連携まわり）の欠落を見逃します。

よくある質問

spring-boot-starter-opentelemetry と opentelemetry-spring-boot-starter は同じものですか？

別物です。前者はgroupIdが org.springframework.boot で、Spring Boot 4.0から提供される公式starterです。後者はgroupIdが io.opentelemetry.instrumentation で、OpenTelemetryプロジェクトが提供しています。実装基盤（Micrometer経由かOpenTelemetry Java SDK直か）も、設定キー（management.* か otel.* か）も、テレメトリの命名規約も異なります。artifactIdの語順が逆なだけに見えるため取り違えが起きやすく、依存を書くときはgroupIdで確認するのが確実です。

Spring Boot 3系でも spring-boot-starter-opentelemetry は使えますか？

使えません。このstarterはSpring Boot 4.0で追加されたもので、3系の依存管理には存在しません。3系では io.opentelemetry.instrumentation の opentelemetry-spring-boot-starter を使います。ただしSpring Boot 3.5は2026年6月30日にOSSサポートが終了し、3系は全ブランチがOSS未サポートです（商用サポートは3.5で2032年6月30日まで）。新規に計装を入れる工数があるなら、4系への移行を先に検討することをおすすめします。

Mavenの依存座標はどう書けばよいですか？

Spring Boot 4系では groupId org.springframework.boot、artifactId spring-boot-starter-opentelemetry を、バージョン指定なしで記述します。Spring Bootの依存管理が版を解決します。Spring Boot 3系では groupId io.opentelemetry.instrumentation、artifactId opentelemetry-spring-boot-starter を使い、あわせて opentelemetry-instrumentation-bom（2026年7月時点の最新は2.30.0）を dependencyManagement にimportして、OpenTelemetry関連モジュールの版を揃えます。

OTEL_LOG_LEVEL を設定してもデバッグログが出ません。

OTEL_LOG_LEVEL はOpenTelemetry Javaエージェントの制御変数ではないため、Java環境では効きません。エージェントのデバッグ出力は OTEL_JAVAAGENT_DEBUG=true（または -Dotel.javaagent.debug=true）で有効にします。出力先は OTEL_JAVAAGENT_LOGGING で simple／none／application から選べます。starterで導入している場合はエージェント自体が動いていないので、Spring Bootのロギング設定でSDK関連パッケージのレベルを上げてください。

トレースが一部しかバックエンドに届きません。

Spring Boot 4系の公式starterでは management.tracing.sampling.probability の既定値が0.1（10%サンプリング）です。まずここを確認してください。DevToolsが有効な開発環境ではこの既定が1.0へ上書きされるため、開発では全件見えていたのに本番で9割消える、という形で表面化します。本番で値を上げると送信量と保管コストがそのまま増えるので、サービス単位で調整するか、OpenTelemetry Collector側でテールサンプリングを構成する方針が現実的です。

関連記事

• OpenTelemetry（OTel）とは｜3つのシグナル・OTLP・Collector・Prometheusとの違いを解説
• Spring Boot 4とは？最新バージョン4.1の変更点・新機能とSpring Boot 3との違いを解説【2026年最新】
• Spring Bootバージョン一覧とサポート期限【2026年7月】最新4.1と3.5 EOL後の選び方
• Spring WebFluxとは？ノンブロッキング・リアクティブなWeb開発の基礎【2026年版】
• Spring Bootの主要なアノテーション一覧｜DI・MVC・JPA・バリデーション・AOPを役割別に整理