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

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

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

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

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

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

デバッグロギングは、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 に変更されました。カスタム設定がデフォルトのエンドポイント設定より優先する場合は、以下のことを確認する必要があります：

1. Javaエージェントの設定が正しいことを確認します。

   1. 選択したプロトコルに正しいポートを使用していることを確認します。

      • gRPC: 4317

      • http/protobuf: 4318

   2. カスタムエンドポイント設定が正しいポートを使用していることを確認してください。次に例を示します。otel.exporter.otlp.endpoint=http://<host>:4318

   3. カスタムプロトコル設定が正しいプロトコルを使用していることを確認してください。次に例を示します。otel.exporter.otlp.protocol=http/protobuf

2. OTel Collector 構成ファイルで、関連する OTLP レシーバのプロトコルが Java エージェントで使用されるものと一致していることを確認します。OTel Collector ファイルでの OTLP レシーバ構成の例を次に示します。

   YAMLCopy

   otlp: protocols: grpc: endpoint: "${SPLUNK_LISTEN_INTERFACE}:4317" http: endpoint: "${SPLUNK_LISTEN_INTERFACE}:4318"

   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 間の接続不足をトラブルシューティングするには、以下の手順を試してください：

1. otel.exporter.otlp.endpoint が正しいOpenTelemetry Collectorインスタンスホスト( http://<host>:4318 )を指していることを確認します。

2. OTel Collector インスタンスが構成され、実行されていることを確認します。「Splunk OpenTelemetry Collector のトラブルシューティング」を参照してください。

3. OTLP レシーバーが OTel Collector でアクティブになり、トレースパイプラインに接続されていることを確認します。

4. OTel Collector 構成ファイルで、関連する OTLP レシーバのプロトコルが Java エージェントで使用されるものと一致していることを確認します。OTel Collector ファイルでの OTLP レシーバ構成の例を次に示します。

   YAMLCopy

   otlp: protocols: grpc: endpoint: "${SPLUNK_LISTEN_INTERFACE}:4317" http: endpoint: "${SPLUNK_LISTEN_INTERFACE}:4318"

   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 アクセストークンの取得と管理」を参照してください。

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

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

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

1. splunk.metrics.endpoint が正しいホストを指していることを確認してください。

2. OpenTelemetry Collector または Smart Agent インスタンスが設定され、実行されていることを確認します。

3. OpenTelemetry Collector または Smart Agent が、SignalFx レシーバの正しいポートを使用していることを確認します。Collector は http://<host>:4318/v2/datapoint を使用し、Smart Agent は http://<host>:9080/v2/datapoint を使用します。

4. 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