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

このガイドの手順に従って、2.xメトリクスとHTTPセマンティック規約に移行し、カスタムレポート要素を新しいメトリクス形式に変換してください。

OpenTelemetry Java Instrumentation 2.x は、最近の OpenTelemetry HTTP セマンティック規約の更新の一部として導入された、いくつかの互換性に影響する変更点を含んでいます。Splunk Distribution of OpenTelemetry Java のバージョン 2.5.0 以降は、更新されたセマンティック規約と完全に互換性があります。

以下の移行の手順では、次のことを前提としています。

Splunk Distribution of OpenTelemetry Java のバージョン1.x を使用して Java アプリケーションメトリクスを送信しています。
Java アプリケーションのメトリクスに基づいて、カスタムダッシュボード、ディテクタ、またはアラートを作成しました。

このガイドの手順に従って、2.xメトリクスとHTTPセマンティック規約に移行し、カスタムレポート要素を新しいメトリクス形式に変換してください。

注: Java エージェントのバージョン 2.x では、デフォルトでメトリクスとログを収集します。これにより、データ取り込みコストが増加する可能性があります。

注意: Java 2.0 のインストルメンテーションでは、デフォルトのプロトコルが gRPC から http/protobuf に変更されました。カスタム構成の場合は、http/protobuf エンドポイントにデータを送信していることを確認します。トラブルシューティングのガイダンスについては、「テレメトリのエクスポートの問題」を参照してください。

前提条件

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 以降に移行できます。

注: この変更によるAlwaysOn Profilingメトリクスの影響はありません。

移行ベストプラクティス

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

このドキュメントをよく読んでください。
リリースノートを確認してください。GitHubの「Releases」を参照してください。
デプロイまたはテスト環境を使用します。
本番サービスを徐々に移行し、タイプごとにグループ化します。
インストルメンテーション設定の変更を特定します。
Splunk Observability Cloudのデータを検証します。
HTTP セマンティック規約の変更の影響を検証します。「APM カスタムレポートを OpenTelemetry Java Agent 2.0 に移行する」を参照してください。

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

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

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

Settings、Data Configuration にアクセスします。
Data Migration を選択します。
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以上に移行するには、以下の手順に従ってください：

Data Migration ページでJavaメトリクスの移行をオンにします。
- Settings、Data Configuration にアクセスします。
- Data Migration を選択します。
- Start migration カード内で、Start を選択します。
Splunk Distribution of OpenTelemetry CollectorでOTLPヒストグラムをオンにします。
SignalFx Exporter を使用してヒストグラムデータを Splunk Observability Cloud に送信するには、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
```
Splunk Distribution of the Java エージェントのバージョン 2.5.0 以降がインストールされていることを確認してください。「Splunk Distribution of OpenTelemetry Java をアップグレードする」を参照してください。
カスタムCollectorエンドポイントを定義している場合は、ポートを更新し、正しいプロパティを使用してください。
```
# 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 エージェントを設定する」を参照してください。
カスタムレポート要素を移行します：
- Splunk APM については、「APM カスタムレポートを OpenTelemetry Java Agent 2.0 に移行する」を参照してください。
（オプション）新しい Java メトリクス 2.x 内蔵ダッシュボードの使用を開始します。内蔵ダッシュボードのバージョンは、バージョン 1.x および 2.x のメトリクスを表す Java サービスメトリクスに対応しています。
準備ができたら、マイグレーションをオフにします：
- Settings、Data Configuration にアクセスします。
- Data Migration を選択します。
- Stop migration カードで、Stop を選択します。

注意: 猶予期間後に Java メトリクスのデータ移行ストリームをオフにしないと、重複したメトリクスはカスタムメトリクスとして請求されます。「データ移行ツールを使用する」を参照してください。

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

以下の表は、OpenTelemetry Java 2.0以降でデフォルトで生成されるメトリクスと、バージョン1.xの旧バージョンの相当メトリクスを示しています。


OTel Java 2.0のメトリクス	旧バージョン（1.x）のメトリクス
`db.client.connections.create_time` （ヒストグラム、ms）	`db.pool.connections.create_time`
`db.client.connections.idle.max`	`db.pool.connections.idle.max`
`db.client.connections.idle.min`	`db.pool.connections.idle.min`
`db.client.connections.max`	`db.pool.connections.max`
`db.client.connections.pending_requests`	`db.pool.connections.pending_threads`
`db.client.connections.timeouts`	`db.pool.connections.timeouts`
`db.client.connections.usage[state=idle]`	`db.pool.connections.idle`
`db.client.connections.usage[state=used]`	`db.pool.connections.active`
`db.client.connections.use_time` （ヒストグラム、ms）	`db.pool.connections.use_time`
`db.client.connections.wait_time` （ヒストグラム、ms）	`db.pool.connections.wait_time`
`jvm.buffer.count`	`runtime.jvm.buffer.count`
`jvm.buffer.memory.limit`	`runtime.jvm.buffer.total.capacity`
`jvm.buffer.memory.usage`	`runtime.jvm.buffer.memory.used`
`jvm.class.count`	`runtime.jvm.classes.loaded`
`jvm.class.unloaded`	`runtime.jvm.classes.unloaded`
`jvm.gc.duration{jvm.gc.name=<concurrent gcs>}`（ヒストグラム）`jvm.gc.action`	`runtime.jvm.gc.concurrent.phase.time`
`jvm.gc.duration{jvm.gc.name!=<concurrent gcs>}` `jvm.gc.action`	`runtime.jvm.gc.pause`
`jvm.memory.allocated`¹	`runtime.jvm.gc.memory.allocated` `process.runtime.jvm.memory.allocated`
`jvm.memory.committed`	`runtime.jvm.memory.committed`
`jvm.memory.limit`	`runtime.jvm.memory.max`
`jvm.memory.limit{jvm.memory.pool.name=<long lived pools>}`	`runtime.jvm.gc.max.data.size`
`jvm.memory.used`	`runtime.jvm.memory.used`
`jvm.memory.used_after_last_gc{jvm.memory.pool.name=<long lived pools>}`	`runtime.jvm.gc.live.data.size`
`jvm.thread.count`	`runtime.jvm.threads.daemon` `runtime.jvm.threads.live`

注: 上の表には、デフォルトで生成されたメトリクスが含まれています。アプリケーションサーバーをインストルメントする場合など、サポートされているメトリクスのインストルメンテーションによって、追加のメトリクスが生成される場合があります。

HTTP セマンティック規約の変更に関する詳細は、GitHub の「HTTP semantic convention stability migration guide」を参照してください。

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

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）インストルメント済みサービスからのメトリクス。

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

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

注: 組み込みのダッシュボードを表示するには、jvm.classes.loaded メトリクスをSplunk Observability Cloudで受信する必要があります。

トラブルシューティング

__ ___ ___ _ ______ _____________ _____ ________ ___ ___ ___ ____ __ ___ ____ ____ __ ______ _____________ ______ ___ ___ ___ ____ __ ___ _________ _____

_________ __ ______ _____________ _____ _________

______ _ ____ __ ___ ______ _______ _______
_______ ______ ________

_________ __ ___________ _________ ___ ____ _____ _____

___ _ ________ ___ ___ _______ _______ _________ _______ __ ______ ________
____ ___ ______ ______________ ____ _____ _____ _______ __ ___________ ____ __________ _________ ___ ______ _________ __________ __ _____ ___ ____ _______

¹ これは Splunk 固有のメトリクスであり、アップストリームのセマンティック規約には存在しません。