MENU
技術系(Tips)
PR

dd-java-agent v1.x 系アップグレード実践記：破壊的変更と解決策の全記録

saratogax
記事内に商品プロモーションを含む場合があります

本番環境で稼働中の dd-java-agent を長期間アップデートしていないプロジェクトは少なくないのではないでしょうか。

本記事では、dd-java-agent を v1.27.0 から最新の v1.60.1 へアップグレードした際の調査内容をまとめます。約2年分のリリース差分から、Breaking Changes・新機能・Datadog Agent との互換性まで網羅的に整理しました。

「dd-java-agent をアップデートしたいけど影響範囲がわからない」「どのバージョンを避けるべきか知りたい」という方の参考になれば幸いです。

Contents
  1. 前提：アップグレード前の環境
  2. 1. 利用者にメリットのある主要な新機能
  3. 2. Breaking Changes（重要度順）
  4. 3. 回避すべきバージョン
  5. 4. Datadog Agent との互換性
  6. 5. 安全にアップグレードできるか
  7. 6. 推奨アップグレード手順
  8. 補足：DD_ENV / DD_VERSION の設定について
  9. まとめ
  10. 参考リンク

前提：アップグレード前の環境

項目バージョン
dd-java-agent1.27.0
Datadog Helm Chart3.59.6
Datadog Agent（Helm chart デフォルト）7.52.0
Agent imagejmx タグサフィックス付き
※表は横スクロールできます

JVM アプリケーションは EKS 上で稼働しており、Datadog Agent は DaemonSet としてデプロイされています。dd-java-agent はコンテナイメージに JAR を同梱するパターンで利用しています。

1. 利用者にメリットのある主要な新機能

ログ・トレーシング・運用面の改善

機能バージョン概要
Spring Boot サービス名自動検出v1.35.0DD_SERVICE 未設定時に spring.application.name から自動推定
GraphQL モニタリングv1.32.0GraphQL クエリのトレーシングサポート
JDK 21 仮想スレッドサポートv1.32.0〜Virtual Thread の検出・コンテキスト追跡
Kotlin コルーチン統合v1.50.0デフォルト有効化。コルーチンのコンテキスト伝搬を自動化
JSON ログフォーマットv1.58.0DD_LOG_FORMAT_JSON でトレーサー内部ログを JSON 出力可能
トレーサーログレベル制御v1.59.0DD_TRACE_LOG_LEVEL による細かいログ制御
Code Origin for Spansv1.56.0スパンの発生元コードの位置をトレースに付与
OTel インスツルメンテーション drop-inv1.35.0OpenTelemetry のインスツルメンテーションを Datadog tracer で直接利用可能
W3C Baggage サポートv1.52.0スパンタグとしての Baggage 伝搬
リモート設定によるサンプリングルール動的変更v1.34.0Agent 再起動なしにサンプリングルールを変更可能
Oracle DB 完全 APM/DBM サポートv1.45.0Oracle の DB モニタリング統合
Kafka-clients 3.8+ / 4.0 サポートv1.41/v1.48最新 Kafka クライアントへの対応
DynamoDB / S3 スパンポインターv1.46/v1.44AWS サービスとのトレース連携強化
OOM クラッシュトラッキングv1.37.0OutOfMemoryException イベントの送信
LLM Observability SDKv1.51.0Java 向け LLM 監視（利用する場合）
※表は横スクロールできます

Datadog コスト・パフォーマンス面の改善

機能バージョン概要
Client-Side Stats デフォルト有効化v1.54/v1.55トレース統計をクライアント側で計算し Agent に送信。Agent 側の処理負荷とネットワーク転送量を削減
プロファイリング zstd 圧縮v1.52.0プロファイルデータの圧縮によりデータ転送量削減
Data Streams Monitoring の CPU 最適化v1.52.0DSM のオーバーヘッド削減
スパン生成オーバーヘッド削減v1.52/v1.57TagMap 最適化、SpanBuilder アロケーション排除
gRPC クライアントメッセージスパン無効化v1.41.0不要なスパン生成を抑制しデータ量削減
※表は横スクロールできます

2. Breaking Changes（重要度順）

対応必須

バージョン変更内容影響・対応
v1.35.0Spring Boot サービス名自動検出がデフォルト有効化DD_SERVICE を明示設定していない場合、サービス名が変わる可能性がある。全アプリで DD_SERVICE を明示的に設定することを推奨
v1.45.0OpenTracing カスタム ScopeManager の完全削除dd-trace-ot でカスタム ScopeManager を使っている場合は OpenTelemetry API へ移行が必要
v1.46.0jnr-unixsocket が外部依存に変更dd-trace-ot アーティファクトを直接デプロイしている場合のみ影響
※表は横スクロールできます

確認推奨

バージョン変更内容影響・対応
v1.44.0X-Forwarded ヘッダーがクライアント IP 解決のデフォルトから除外クライアント IP をトレースしている場合、DD_TRACE_CLIENT_IP_HEADER=x-forwarded を設定
v1.50.0DD_RUNTIME_ID_ENABLED 非推奨DD_RUNTIME_METRICS_RUNTIME_ID_ENABLED に変更
v1.58.0MongoDB ドキュメント処理のリスト要素が256件に制限大きなドキュメントのリソース名が切り捨てられる可能性
v1.59.0サンプリング決定オーバーライドの動作変更手動サンプリング制御を使っている場合に注意
v1.39.0RASP がデフォルト有効化DD_APPSEC_ENABLED=true の環境ではセキュリティ保護が自動強化。パフォーマンスへの影響を確認
※表は横スクロールできます

デフォルト動作の変更（影響は軽微だが認識すべきもの）

  • v1.50.0: Kotlin コルーチン統合がデフォルト有効
  • v1.51.0: JAX-WS / API Security がデフォルト有効
  • v1.55.0: Client-Side Stats がデフォルト有効
  • v1.56.0: Code Origin for Spans がデフォルト有効

3. 回避すべきバージョン

以下のバージョンには重大なバグが含まれているため、アップグレード先として選ばないようにしましょう。

バージョン理由
v1.29.0 / v1.30.0Spring Boot に影響する重大バグ
v1.35.0 / v1.35.1AWS SNS 不正メッセージ属性のバグ（v1.35.2で修正）
v1.42.0プロファイリング中のクラッシュ（v1.42.1で修正）
v1.55.0〜v1.56.2liveheap プロファイラーの JVM クラッシュ（v1.56.3で修正）
v1.60.0OTel インスツルメンテーション破損（v1.60.1で修正）
※表は横スクロールできます

4. Datadog Agent との互換性

既存の Agent バージョンで問題ないか

基本的な APM トレーシングは Agent 7.52.0 で問題なく動作します。

dd-trace-java と datadog-agent は後方互換性を持つよう設計されており、トレースプロトコル（v0.4/v0.5）は Agent 6.x/7.x で互換性があります。

そのため、dd-java-agent のアップグレードと Helm chart（Agent）のアップグレードを同時に行う必要はありません。

Agent バージョンを上げると活用できる新機能

Agent 最小バージョン機能
7.41.0+APM Remote Configuration（サンプリングルール動的変更など）
7.44.0+Single Step Instrumentation
7.50.0+新しいテレメトリプロトコル完全対応
※表は横スクロールできます

Agent 7.52.0 であれば、dd-java-agent 1.60.1 の主要機能はほぼフルに活用可能です。

Client-Side Stats の影響

v1.54.0/v1.55.0 で Client-Side Stats がデフォルト有効化されています。

これによりトレース統計がアプリ側で計算されてから Agent に送られるため、Agent 側の処理負荷は減りますが、Agent 側でのサンプリング動作が変わる可能性があります。Agent 7.52.0 はこの機能に対応しています。

5. 安全にアップグレードできるか

結論：基本的には問題ないが、事前確認を行ってから実施すること

以下の3点をクリアしていれば、v1.27.0 から v1.60.1 への一括アップグレードが可能です。段階的にバージョンを上げる必要はありません。

  1. DD_SERVICE が全アプリで明示設定されているか確認（最重要）
    未設定の場合、v1.35.0 以降で Spring Boot アプリのサービス名が自動的に変わる可能性があります。
  2. OpenTracing (dd-trace-ot) を使っていないか確認
    使っている場合は v1.45.0 で ScopeManager が削除されるため、移行計画が必要です。
  3. v1.60.0 は避けて v1.60.1 を使う
    v1.60.0 は OTel インスツルメンテーションのバグがあります。

6. 推奨アップグレード手順

Step 1：事前確認

  • 全 JVM アプリで DD_SERVICE が明示設定されているか確認
  • DD_RUNTIME_ID_ENABLED を使っている場合は DD_RUNTIME_METRICS_RUNTIME_ID_ENABLED に変更
  • OpenTracing (dd-trace-ot) の使用有無を確認

Step 2：アップグレード実施

  • dd-java-agent.jar のバージョンを 1.60.1 に更新（Dockerfile 内のダウンロード先やコピー元を変更）
  • 一気に v1.60.1 に上げて問題ありません（段階的にする必要はなし）
  • ただし、まずは dev/staging 環境で検証してから本番適用

Step 3：適用後の確認ポイント

  • サービス名が意図通りか（Datadog APM 画面）
  • トレースが正常に送信されているか
  • プロファイリングが有効な場合、JVM クラッシュがないか
  • ログ転送に影響がないか

Step 4：Helm chart（Datadog Agent）について

  • 現在の Helm chart のままでも dd-java-agent 1.60.1 は動作する
  • ただし、最新の Helm chart に上げることで Remote Configuration などの恩恵がより確実に受けられる

補足：DD_ENV / DD_VERSION の設定について

dd-java-agent のバージョンアップとは直接関係ありませんが、DD_ENV と DD_VERSION を設定しておくことで、Datadog の Unified Service Tagging によりトレース・ログ・プロファイルの関連付けが大幅に改善されます。

バージョンアップのタイミングで整備を検討してもよいかもしれません。

まとめ

dd-java-agent の v1.27.0 → v1.60.1 のアップグレードは、事前確認さえ行えば一括で安全に実施可能です。約2年分のリリースには多くの新機能・パフォーマンス改善が含まれており、特に以下の点でメリットがあります。

  • JDK 21 仮想スレッド・Kotlin コルーチンなど最新の Java エコシステムへの対応
  • Client-Side Stats による Agent 負荷とネットワーク転送量の削減
  • OTel drop-in サポートによる将来的な移行の柔軟性
  • OOM クラッシュトラッキングや Code Origin for Spans による可観測性の向上

長期間アップデートを見送っていると Breaking Changes が蓄積して影響調査が大変になるため、定期的なアップデートを心がけましょう。

参考リンク

ABOUT ME
saratoga
saratoga
フリーランスエンジニア
YouTube
仕事にも趣味にも IT を駆使するフリーランスエンジニア。技術的な TIPS や日々の生活の中で深堀りしてみたくなったことを備忘録として残していきます。
Recommend
こんな記事も読まれています
記事URLをコピーしました