OpenTelemetry Java 2.xメトリクスの移行ガイド

前提条件

OpenTelemetry Java 1.xからOpenTelemetry Java 2.xに移行するには、以下のものが必要です：

• Splunk Distribution of OpenTelemetry Collectorバージョン0.98以上がデプロイされている

• Splunk Observability Cloud での管理者権限。「Splunk Observability Cloudのロールと機能のマトリックス」を参照してください。

Splunk Distribution of OpenTelemetry Java 1.x または同等のアップストリーム インストルメンテーションを使用して Java サービスをインストルメントしている場合は、すでに Java エージェントのバージョン 2.5.0 以降に移行できます。

移行ベストプラクティス

以下のベストプラクティスは、移行プロセスを開始するときに役立ちます：

1. このドキュメントをよく読んでください。

2. リリースノートを確認してください。GitHubの「Releases」を参照してください。

3. デプロイまたはテスト環境を使用します。

4. 本番サービスを徐々に移行し、タイプごとにグループ化します。

5. インストルメンテーション設定の変更を特定します。

6. Splunk Observability Cloudのデータを検証します。

7. HTTP セマンティック規約の変更の影響を検証します。「APM カスタムレポートを OpenTelemetry Java Agent 2.0 に移行する」を参照してください。

データ移行ツールを使用する

メトリクス名が変更されたため、Java OTel 2.x にアップグレードすると、既存のダッシュボード、ディテクタ、およびその他の機能が損なわれる可能性があります。カスタムのレポート要素に対する突然のアクセス喪失を防ぐには、データ移行ツールを使用してください。このツールは、新しい 2.x のセマンティック規約から旧バージョンの 1.x のフォーマットへのメトリクスデータの変換および複製を、期間限定で追加費用なしで実行します。

データ移行ツールにアクセスする

1. Settings、Data Configuration にアクセスします。

2. Data Migration を選択します。

3. Start migration カード内で、Start を選択します。

サポートされている各プロセスについて、データ移行のオンとオフを切り替え、移行されたメトリクス時系列（MTS）の数を表示して、猶予期間を確認できます。メトリクスの重複と二重公開は、移行を決定したときに有効になる一連の事前定義済みルールに従います。

猶予期間

追加費用なしで複製されたメトリクスの受領と処理の猶予期間は、2024年6月25日のJavaエージェントバージョン2.5.0のリリースから2025年1月31日までの6か月間です。

移行サポートはバージョン2.5.0のリリースから12か月間利用可能で、18か月後に非推奨となります。

OTel Java 2.xへの移行

インストルメンテーションをJavaエージェントのバージョン2.5.0以上に移行するには、以下の手順に従ってください：

1. Data Migration ページでJavaメトリクスの移行をオンにします。

   • Settings、Data Configuration にアクセスします。

   • Data Migration を選択します。

   • Start migration カード内で、Start を選択します。

2. Splunk Distribution of OpenTelemetry CollectorでOTLPヒストグラムをオンにします。

   SignalFx Exporter を使用してヒストグラムデータを Splunk Observability Cloud に送信するには、send_otlp_histograms オプションを true に設定します。例：

   YAMLCopy

   exporters: signalfx: access_token: "${SPLUNK_ACCESS_TOKEN}" api_url: "${SPLUNK_API_URL}" ingest_url: "${SPLUNK_INGEST_URL}" sync_host_metadata: true correlation: send_otlp_histograms: true

   exporters:
     signalfx:
       access_token: "${SPLUNK_ACCESS_TOKEN}"
       api_url: "${SPLUNK_API_URL}"
       ingest_url: "${SPLUNK_INGEST_URL}"
       sync_host_metadata: true
       correlation:
       send_otlp_histograms: true

3. Splunk Distribution of the Java エージェントのバージョン 2.5.0 以降がインストールされていることを確認してください。「Splunk Distribution of OpenTelemetry Java をアップグレードする」を参照してください。

4. カスタムCollectorエンドポイントを定義している場合は、ポートを更新し、正しいプロパティを使用してください。

   SHELLCopy

   # Legacy property and value: -Dsplunk.metrics.endpoint=http(s)://collector:9943 # You can also use the OTEL_EXPORTER_OTLP_METRICS_ENDPOINT environment variable -Dotel.exporter.otlp.metrics.endpoint=http://localhost:4318/v1/metrics

   # Legacy property and value: -Dsplunk.metrics.endpoint=http(s)://collector:9943
   # You can also use the OTEL_EXPORTER_OTLP_METRICS_ENDPOINT environment variable
   -Dotel.exporter.otlp.metrics.endpoint=http://localhost:4318/v1/metrics

   バージョン 2.5.0 に引き続き該当することをチェックするために、その他すべての設定を確認します。「Splunk Observability Cloud 用の Java エージェントを設定する」を参照してください。

5. カスタムレポート要素を移行します：

   • Splunk APM については、「APM カスタムレポートを OpenTelemetry Java Agent 2.0 に移行する」を参照してください。

6. （オプション）新しい Java メトリクス 2.x 内蔵ダッシュボードの使用を開始します。内蔵ダッシュボードのバージョンは、バージョン 1.x および 2.x のメトリクスを表す Java サービスメトリクスに対応しています。

7. 準備ができたら、マイグレーションをオフにします：

   • Settings、Data Configuration にアクセスします。

   • Data Migration を選択します。

   • Stop migration カードで、Stop を選択します。

バージョン2.xの新しいメトリクス名

報告されなくなったメトリクス

Javaインストルメンテーションのバージョン2.5.0以降で発行されるメトリクスが変更されたため、以下のメトリクスを使用するディテクターまたはダッシュボードが移行前と同じように動作しない可能性があります：

• db.pool.connections

• executor.tasks.completed

• executor.tasks.submitted

• executor.threads

• executor.threads.active

• executor.threads.core

• executor.threads.idle

• executor.threads.max

• runtime.jvm.memory.usage.after.gc

• runtime.jvm.gc.memory.promoted

• runtime.jvm.gc.overhead

• runtime.jvm.threads.peak

• runtime.jvm.threads.states

内蔵ダッシュボード

内蔵OTel Java 2.X APMサービスダッシュボードにアクセスするには、次のリンクを使用します。

• サービス：APM トレースデータからのサービスレベル指標。

• サービスエンドポイント：APM トレーシングデータからのエンドポイントレベルの指標。

• Java ランタイムメトリクス（Otel 2.X） インストルメント済みサービスからのメトリクス。

オプションで、ダッシュボードに自分で移動することもできます：

1. 左のナビゲーションメニューで、Dashboards を選択します。

2. Built-in dashboard groups セクションで、3つのダッシュボードがグループ化されている APM Java services (OTel 2.X) ダッシュボードグループまでスクロールダウンします。

トラブルシューティング