Docs » Splunk Observability Cloud でサポートされているインテグレーション » バックエンドアプリケーションをインストルメンテーションして、スパンを Splunk APM に送信する » Splunk Observability Cloud 用 Java アプリケーションのインストルメンテーション » OpenTelemetry Java 2.xメトリクスの移行ガイド

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

OpenTelemetry Java Instrumentation 2.x contains a set of breaking changes, introduced as part of recent OpenTelemetry HTTP semantic convention updates. Versions 2.5.0 and higher of the Splunk Distribution of OpenTelemetry Java are fully compatible with the updated semantic conventions.

The following migration instructions assume the following:

  • You’re sending Java application metrics using version 1.x of the Splunk Distribution of OpenTelemetry Java.

  • Javaアプリケーションのメトリクスに基づいて、カスタムダッシュボード、ディテクター、またはアラートを作成しました。

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

注釈

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

注意

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

前提条件 🔗

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

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

注釈

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

Migration best practices 🔗

The following best practices can help you when initiating the migration process:

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

  2. Read the release notes. See Releases on GitHub.

  3. Use a development or test environment.

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

  5. Identify changes in your instrumentation settings.

  6. Validate the data in Splunk Observability Cloud.

  7. Verify the impact of HTTP semantic convention changes. See APMカスタムレポートをOpenTelemetry Javaエージェント2.0に移行する.

Use the Data Migration tool 🔗

Due to the changes in metric names, upgrading to Java OTel 2.x might break existing dashboards, detectors, and other features. To prevent sudden loss of access to custom reporting elements, use the Data Migration tool, which transforms and duplicates metric data from the new 2.x semantic conventions into the legacy 1.x format for a limited period of time at no additional cost.

Java 2.xメトリクス用の移行メトリクスルールを実行するデータ移行ツール

To access the Data Migration tool:

  1. Go to Settings, Data Configuration.

  2. Select Data Migration.

  3. Inside the Start migration card, select Start.

サポートされている各プロセスについて、データ移行のオン/オフ、移行されたメトリック時系列（MTS）数の確認、猶予期間 の表示が可能です。メトリクスの複製と二重公開は、移行を決定したときに有効にされる、事前に定義されたルールに従って行われます。

注釈

メトリクスルールはシステムルールとして扱われ、編集することはできません。

Grace period 🔗

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

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

注釈

猶予期間を過ぎると、重複したメトリクスデータはカスタムメトリクスデータとして請求されます。追加課金を避けるため、移行完了後は必ずデータ移行アクションをオフにしてください。

Migrate to OTel Java 2.x 🔗

To migrate your instrumentation to the version 2.5.0 or higher of the Java agent, follow these steps:

  1. Turn on the migration of Java metrics in the Data Migration page:

    • Go to Settings, Data Configuration.

    • Select Data Migration.

    • Inside the Start migration card, select Start.

  2. Turn on OTLP histograms in the Splunk Distribution of OpenTelemetry Collector.

    To send histogram data to Splunk Observability Cloud, set the send_otlp_histograms option to true. For example:

    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. If you defined a custom Collector endpoint for metrics, make sure to update the port and use the correct property:

    # 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

    Review all others settings to check that they’re still applicable to version 2.5.0. See Splunk Observability Cloud 用の Java エージェントを設定する.

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

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

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

    • Go to Settings, Data Configuration.

    • Select Data Migration.

    • In the Stop migration card, select Stop.

注意

猶予期間後にJavaメトリクスのデータ移行ストリームをオフにしないと、重複したメトリクスはカスタムメトリクスとして請求されます。Use the Data Migration tool を参照してください。

New metric names for version 2.x 🔗

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

OTel Java 2.0 metric

Legacy metric (1.x)

db.client.connections.create_time (Histogram, 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 (Histogram, ms)

db.pool.connections.use_time

db.client.connections.wait_time (Histogram, 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>} （ヒストグラム）|br| 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

* This is a Splunk-specific metric and it’s not present in the upstream semantic conventions.

注釈

前の表には、デフォルトで生成されるメトリクスが記載されています。アプリケーションサーバーのインスルトメンテーションなど、サポートされているメトリクスのインストルメンテーションによって、この他のメトリクスが生成される場合があります。

For more information on the HTTP semantic convention changes, see HTTP semantic convention stability migration guide on GitHub.

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

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

Built-in dashboards 🔗

Use the following links to access the built-in OTel Java 2.X APM services dashboards:

Optionally, you can navigate to the dashboards on your own:

  1. In the left navigation menu, select Dashboards.

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

注釈

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

トラブルシューティング 🔗

Splunk Observability Cloudをご利用のお客様で、Splunk Observability Cloudでデータを確認できない場合は、以下の方法でサポートを受けることができます。

Splunk Observability Cloudをご利用のお客様

見込み客および無料トライアルユーザー様

  • Splunk Answers のコミュニティサポートで質問し、回答を得る

  • Splunk #observability ユーザーグループの Slack チャンネルに参加して、世界中の顧客、パートナー、Splunk 社員とのコミュニケーションを図る。参加するには、Get Started with Splunk Community マニュアルの チャットグループ を参照してください。

このページは 2024年12月11日 に最終更新されました。