Splunk Observability Cloud の Java インストルメンテーションのトラブルシューティング 🔗

Splunk Distribution of OpenTelemetry Java を使用して Java アプリケーションをインストルメンテーションしているときに Splunk Observability Cloud にデータが表示されない場合は、以下のトラブルシューティング手順に従ってください。

Java OpenTelemetryの問題のトラブルシューティングの手順 🔗

以下の手順は、Javaエージェントの問題のトラブルシューティングに役立ちます：

デバッグロギングを有効にする
ランタイムのステータスをチェックする

デバッグロギングを有効にする 🔗

デバッグロギングは、Splunk Distribution of OpenTelemetry Java の Java エージェントに関するより多くの情報を出力する特別な実行モードです。これは Java インストルメンテーションの問題のトラブルシューティングに役立ちます。

Java エージェントのデバッグロギングを有効にするには、以下のオプションのいずれかを選択します：

アプリケーションの実行時に以下の引数を渡します： -Dotel.javaagent.debug=true.
アプリケーションを実行する前に、OTEL_JAVAAGENT_DEBUG 環境変数を true に設定します。

デバッグロギングを有効にしてエージェントを実行すると、デバッグ情報は stderr としてコンソールに送られます。デバッグログエントリーは、以下の例のようになります：

...
[otel.javaagent 2023-05-09 15:22:40:172 +0200] [main] DEBUG io.opentelemetry.javaagent.tooling.VersionLogger - Running on Java 17.0.2. JVM OpenJDK 64-Bit Server VM - Eclipse Adoptium - 17.0.2+8
[otel.javaagent 2023-05-09 15:22:40:264 +0200] [main] DEBUG io.opentelemetry.sdk.internal.JavaVersionSpecific - Using the APIs optimized for: Java 9+
...

すべてのデバッグ・エントリーが、Javaインストルメンテーションに影響を与える問題に関連するとは限りませんが、根本的な原因はデバッグログに現れる可能性が高いです。

注釈

必要なときだけデバッグロギングを有効にします。デバッグモードはより多くのリソースを必要とします。

ランタイムのステータスをチェックする 🔗

jps -lvm コマンドを実行して、Javaランタイムが開始したことを確認します。出力は、現在実行中のすべてのJava仮想マシン（JVM）のリストです。その中に、インストルメンテーションしたJVMが表示されていることを確認します。

以下の例では、最初のエントリーは、-javaagent でエージェントを実行している JVM を示しています：

37602 target/spring-petclinic-2.4.5.jar -javaagent:./splunk-otel-javaagent.jar -Dotel.resource.attributes=service.name=pet-store-demo,deployment.environment=prod,service.version=1.2.0 -Dotel.javaagent.debug=true
38262 jdk.jcmd/sun.tools.jps.Jps -lvm -Dapplication.home=/usr/lib/jvm/java-16-openjdk-amd64 -Xms8m -Djdk.module.main=jdk.jcmd

インストルメンテーションされたJVMがリストに表示されない場合は、JVMまたはアプリケーションログをチェックして問題の原因を見つけます。また、追加のスタートアップ・パラメーターがランタイムに正しく渡されていることも確認してください。スタートアップ・パラメーターの詳細については、Splunk Observability Cloud に Java アプリケーションをインストルメンテーションするを参照してください。

ライブラリのインストルメンテーションに関する問題 🔗

ライブラリの特定のインストルメンテーションに問題が見つかった場合、またはそのインストルメンテーションに影響する問題がある可能性が疑われる場合、そのインストルメンテーションを無効にすると、Javaエージェントのトラブルシューティングに役立ちます。

特定のライブラリ・インストルメンテーションを無効にするには、以下の引数を追加します：

-Dotel.instrumentation.<name>.enabled=false

<name> を、https://opentelemetry.io/docs/instrumentation/java/automatic/agent-config/#suppressing-specific-auto-instrumentation にある GitHub の OpenTelemetry Java インストルメンテーションの対応するインストルメンテーションに置き換えてください。

クラスインストルメンテーションの問題 🔗

特定のクラスがインストルメンテーションされないようにすることができます。除外されたクラスはスパンを送信しないので、特定のクラスやパッケージをミュートするのに便利です。

クラスのインストルメンテーションを無効にするには、otel.javaagent.exclude-classes システム・プロパティまたは OTEL_JAVAAGENT_EXCLUDE_CLASSES 環境変数をクラスまたはクラスの名前に設定します。

複数のクラスを入力することができます。例えば、my.package.MyClass,my.package2.* 。

注意

特定のクラスのインストルメンテーションを無効にすると、意図しない副作用が生じることがあります。この機能は注意して使用してください。

テレメトリエクスポートの問題 🔗

Java 2.xインストルメンテーションへの移行後、テレメトリが機能しない 🔗

Java 2.xインストルメンテーションでは、デフォルトプロトコルがgRPCからhttp/protobufに変更されました。カスタム設定がデフォルトのエンドポイント設定を上書きする場合は、以下を確認する必要があります：

Javaエージェントの設定が正しいことを確認します。
1. 選択したプロトコルに正しいポートを使用していることを確認します。
  - gRPC: 4317
  - http/protobuf: 4318
2. カスタムエンドポイント設定が正しいポートを使用していることを確認してください。例： otel.exporter.otlp.endpoint=http://<host>:4318。
3. カスタムプロトコル設定が正しいプロトコルを使用していることを確認してください。例： otel.exporter.otlp.protocol=http/protobuf。
OTel Collector設定ファイルで、関連するOTLPレシーバーのプロトコルがJavaエージェントで使用されるものと一致していることを確認します。OTel CollectorファイルのOTLPレシーバー設定の例を示します：
```
otlp:
  protocols:
    grpc:
      endpoint: "${SPLUNK_LISTEN_INTERFACE}:4317"
    http:
      endpoint: "${SPLUNK_LISTEN_INTERFACE}:4318"
```

トレース・エクスポーターの問題 🔗

デフォルトでは、Splunk Distribution of OpenTelemetry Java は OTLP エクスポーターを使用します。トレースのエクスポートに影響する問題が発生すると、デバッグログにエラーが出力されます。

OTLP がスパンをエクスポートできない 🔗

ログの以下のエラーは、エージェントがトレースデータを OpenTelemetry Collector に送信できないことを意味します：

[BatchSpanProcessor_WorkerThread-1] ERROR io.opentelemetry.exporter.otlp.trace.OtlpGrpcSpanExporter - Failed to export spans. Server is UNAVAILABLE. Make sure your collector is running and reachable from this network. Full error message:UNAVAILABLE: io exception

OTLPエクスポーターとOTel Collector 間の接続不足をトラブルシューティングするには、以下の手順を試してください：

otel.exporter.otlp.endpoint が正しいOpenTelemetry Collectorインスタンスホスト( http://<host>:4318 )を指していることを確認します。
OTel Collector インスタンスが構成され、実行されていることを確認します。Splunk OpenTelemetry Collector のトラブルシューティングを参照してください。
OTLP レシーバーが OTel Collector でアクティブになり、トレースパイプラインに接続されていることを確認します。
OTel Collector設定ファイルで、関連するOTLPレシーバーのプロトコルがJavaエージェントで使用されるものと一致していることを確認します。OTel CollectorファイルのOTLPレシーバー設定の例を示します：
```
otlp:
  protocols:
    grpc:
      endpoint: "${SPLUNK_LISTEN_INTERFACE}:4317"
    http:
      endpoint: "${SPLUNK_LISTEN_INTERFACE}:4318"
```

スパン送信時の401エラー 🔗

トレースを Splunk Observability Cloud に直接送信して 401 エラーコードを受け取った場合、SPLUNK_ACCESS_TOKEN で指定した認証トークンが無効です。次のような理由が考えられます：

値はnullです。
値が整形式トークンではありません。
このトークンは、authScope が ingest に設定されているアクセストークンではありません。

Splunk プラットフォームインスタンスに直接データを送信する場合は、有効な Splunk アクセストークンを使用していることを確認してください。Splunk Observability Cloudを使用したユーザー APIアクセストークンの取得と管理を参照してください。

メトリクス・エクスポーターの問題 🔗

注釈

OpenTelemetry Java 2.xメトリクスの移行ガイドも参照してください。

ログにメトリクスに関する警告が表示された場合は、JavaエージェントがOTel CollectorインスタンスまたはSplunkプラットフォームのエンドポイントにメトリクスを送信できないことを意味する可能性があります。

アプリケーション・メトリクスに影響する接続性の問題をトラブルシューティングするには、以下の手順を試してください：

非推奨のプロパティ splunk.metrics.endpoint が設定から削除されていることを確認してください。
OpenTelemetry Collectorが設定され、実行されていることを確認します。

OTLPレシーバーを使用している場合は、正しいホスト/エンドポイント、例えば http://<host>:4318/v1/metrics を指していることを確認してください。

SignalFxレシーバーを使用している場合は、それが http://<host>:4318/v2/datapoint を指していることを確認してください。

Splunk プラットフォームインスタンスに直接データを送信する場合は、有効な Splunk アクセストークンを使用していることを確認してください。Splunk Observability Cloudを使用したユーザー APIアクセストークンの取得と管理を参照してください。

Java の AlwaysOn Profilingのトラブルシューティング 🔗

以下の手順に従って、AlwaysOn Profilingの問題をトラブルシューティングしてください：

AlwaysOn Profilingが有効になっていることを確認する 🔗

Java エージェントは、起動時に INFO メッセージを使って文字列 JFR profiler is active をログに記録します。AlwaysOn Profiling が有効になっているかどうかを確認するには、以下のような文字列をログから検索します：

[otel.javaagent 2021-09-28 18:17:04:246 +0000] [main] INFO com.splunk.opentelemetry.profiler.JfrActivator - JFR profiler is active.

文字列が表示されない場合は、splunk.profiler.enabled システム・プロパティまたは SPLUNK_PROFILER_ENABLED 環境変数を設定して、プロファイラが有効になっていることを確認してください。AlwaysOn Profilingの Java 設定を参照してください。

AlwaysOn Profilingの設定を確認する 🔗

AlwaysOn Profilingが意図したとおりに動作しない場合は、構成設定を確認してください。Java エージェントは、起動時に INFO メッセージを使用して AlwaysOn Profiling 設定を記録します。com.splunk.opentelemetry.profiler.ConfigurationLogger という文字列を検索すると、次のようなエントリーが表示されます：

[otel.javaagent 2021-09-28 18:17:04:237 +0000] [main] INFO <snip> - -----------------------
[otel.javaagent 2021-09-28 18:17:04:237 +0000] [main] INFO <snip> - Profiler configuration:
[otel.javaagent 2021-09-28 18:17:04:238 +0000] [main] INFO <snip> -                 splunk.profiler.enabled : true
[otel.javaagent 2021-09-28 18:17:04:239 +0000] [main] INFO <snip> -               splunk.profiler.directory : .
[otel.javaagent 2021-09-28 18:17:04:244 +0000] [main] INFO <snip> -      splunk.profiler.recording.duration : 20s
[otel.javaagent 2021-09-28 18:17:04:244 +0000] [main] INFO <snip> -              splunk.profiler.keep-files : false
[otel.javaagent 2021-09-28 18:17:04:245 +0000] [main] INFO <snip> -           splunk.profiler.logs-endpoint : null
[otel.javaagent 2021-09-28 18:17:04:245 +0000] [main] INFO <snip> -             otel.exporter.otlp.endpoint : http://collector:4318
[otel.javaagent 2021-09-28 18:17:04:246 +0000] [main] INFO <snip> -   splunk.profiler.period.jdk.threaddump : null
[otel.javaagent 2021-09-28 18:17:04:246 +0000] [main] INFO <snip> - -----------------------

JFRは利用不可エラー 🔗

お使いのJava仮想マシンがJava Flight Recording (JFR)をサポートしていない場合、プロファイラの起動時に警告がログに記録され、Java Flight Recorder (JFR) is not available in this JVM. Profiling is disabled. というメッセージが表示されます。

プロファイラを使用するには、JVMのバージョンを8u262以上にアップグレードしてください。Javaエージェントの互換性と要件を参照してください。

アクセス拒否エラー 🔗

JavaランタイムでJava Security Manager（JSM）が有効になっている場合、以下のエラーが表示されることがあります：

java.security.AccessControlException: access denied ("java.util.PropertyPermission" "otel.javaagent.debug" "read")

これを解決するには、JSMを非アクティブにするか、JSMポリシーファイルに以下のブロックを追加します：

grant codeBase "file:<path to splunk-otel-java.jar>" {
   permission java.security.AllPermission;
};

AlwaysOn Profiling のデータとログが Splunk Observability Cloud に表示されない 🔗

Collector 構成の問題により、AlwaysOn Profilingデータとログが Splunk Observability Cloud に表示されない場合があります。

この問題を解決するには、次のようにしてください：

起動ログメッセージで splunk.profiler.logs-endpoint と otel.exporter.otlp.endpoint の値を見つけます。そのエンドポイントを使用してコレクタが実行されていること、アプリケーションホストまたはコンテナがホスト名を解決して OTLP ポートに接続できることを確認します。
Splunk Distribution of OpenTelemetry Collector を実行していることと、バージョンが 0.34 以上であることを確認してください。他のコレクタディストリビューションでは、プロファイリングデータを含むログデータをルーティングできない場合があります。
カスタム設定は、コレクタにプロファイリングデータを処理させる設定をオーバーライドする場合があります。正しいトークンとエンドポイントフィールドを持つ otlp レシーバーと splunk_hec エクスポーターを設定してください。profiling パイプラインは、設定した OTLP レシーバーと Splunk HEC エクスポーターを使用する必要があります。詳細は Splunk HEC エクスポーターを参照してください。

次のスニペットには、profiling パイプラインのサンプルが含まれています：

receivers:
  otlp:
    protocols:
      grpc:

exporters:
  # Profiling
  splunk_hec/profiling:
    token: "${SPLUNK_ACCESS_TOKEN}"
    endpoint: "${SPLUNK_INGEST_URL}/v1/log"
    log_data_enabled: false

processors:
  batch:
  memory_limiter:
    check_interval: 2s
    limit_mib: ${SPLUNK_MEMORY_LIMIT_MIB}

service:
  pipelines:
    logs/profiling:
      receivers: [otlp]
      processors: [memory_limiter, batch]
      exporters: [splunk_hec, splunk_hec/profiling]

すべてのJavaエージェントログを無効にする 🔗

デフォルトでは、Splunk Java エージェントはログをコンソールに出力します。状況によっては、システムログを散らかさないようにエージェントの出力を停止したいこともあるでしょう。

Javaエージェントをサイレント・モードで実行するには、以下の引数を追加します：

-Dotel.javaagent.logging=none

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

Splunk Observability Cloudをご利用のお客様

Splunk サポートポータルでケースを送信する
Splunkサポートに連絡する

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

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

このページは 2025年02月20日に最終更新されました。

Related Topics