APM Javaエージェント・ハイブリッド・モードの構成
APM Java Agentハイブリッド・モードは、APMエージェント・ハイブリッド・モードとも呼ばれ、エージェント・プローブ・スパンとアプリケーション・スパンによって完全なトレースを形成できます。
APMエージェント・ハイブリッド・モード機能は、バイトコード・インストゥルメンテーションとOpenTracing/OpenTelemetryマニュアル・インストゥルメンテーションの両方を組み合せて、アプリケーション・フローを完全に把握します。
これは、OpenTracingおよびOpenTelemetryライブラリが、APMエージェントおよびすべてのアプリケーションからアクセス可能な共通ClassLoaderにロードされていることを確認するメカニズムを提供します。したがって、スパンはアプリケーションで作成でき、APMエージェント・プローブによって自動的に作成されるスパンにリンクされます。
APMエージェント・プローブによって作成されたスパンは、アクティブ化されたスパンに自動的にリンクされます。
前提条件
- APMエージェントは、プロパティを有効にする前に完全に機能します。
OpenTelemetryには、
com.oracle.apm.agent.otel=trueプロパティを使用します。ノート
OpenTelemetryにはJava 8以上が必要です。 - アプリケーションは、
GlobalTracer.get()を使用してOpenTracingトレーサ・インスタンスを取得するか、GlobalOpenTelemetry.get()メソッドを使用してOpenTelemetryインスタンスを取得する必要があります。 - 同じライブラリのバージョン。
OpenTracingの場合、APMエージェントとアプリケーションは同じOpenTracingライブラリ・バージョンを使用します。
OpenTelemetryの場合、APMエージェントとアプリケーションは同じOpenTelemetryライブラリ・バージョンを使用します。詳細は、「OpenTelemetryと連携するためのAPM Javaエージェントの構成」を参照してください。
APMエージェント・ハイブリッド・モードの有効化
APMエージェントのハイブリッド・モードはデフォルトで有効になっています。
これを無効にするには、プロパティcom.oracle.apm.agent.hybrid=falseを使用します。ただし、OpenTelemetryプロパティcom.oracle.apm.agent.otel=trueが設定されている場合、ハイブリッド・モードは常にオンになります。
| プロパティ・タイプおよび説明 | プロパティ | 例 |
|---|---|---|
|
AgentConfig.properties
|
com.oracle.apm.agent.hybrid |
com.oracle.apm.agent.hybrid=true |
|
システム・プロパティ システム・プロパティを更新します。 |
com.oracle.apm.agent.hybrid |
-Dcom.oracle.apm.agent.hybrid=true |
|
環境変数 環境変数を更新します。 |
com_oracle_apm_agent_hybrid |
Windowsの場合:
Linuxの場合:
|
ほとんどのアプリケーション・サーバーおよびマイクロサービスで必要なステップは、プロパティの設定のみです。ただし、一部のアプリケーション・サーバーには、異なるクラス・ロード・ロジックおよびクラス定義分離がある場合があります。APMエージェントで同じOpenTracingおよびOpenTelemetryクラス定義が使用されるようにするには、追加の次のステップが必要になる場合があります。
-
OpenTracingおよびOpenTelemetryライブラリを
oracle-apm-agent/install/<version>/lib/extディレクトリからoracle-apm-agent/bootstrapディレクトリにコピーします。
前述のステップでは、APMエージェントおよびすべてのアプリケーションが、コピーされたOpenTracingおよびOpenTelemetryライブラリを使用するため、同じOpenTracingおよびOpenTelemetryクラス定義を使用します。
APMエージェントおよびOpenTracingおよびOpenTelemetryライブラリ: OpenTracingライブラリのバージョン0.33およびOpenTelemetryライブラリのバージョン1.38.0は、APMエージェントに含まれています。アプリケーションでOpenTracingバージョン0.32固有のAPIを使用する必要がある場合は、OpenTracing 0.32ライブラリをoracle-apm-agent/bootstrapディレクトリにコピーできます。APMでは、OpenTracing 0.32および0.33ライブラリの両方がサポートされます。アプリケーションで異なるOpenTelemetryバージョンを使用する必要がある場合は、OpenTelemetryと連携するためのAPM Javaエージェントの構成を参照してください。
-
OpenTracingライブラリがマイクロサービスのクラスパスに明示的に含まれている場合。
-
appserverクラス・ローダーが親クラス・ローダーへのクラス・ロードの優先順位付けを行わない場合。例: Tomcat
FAQ
- JDBCスパンなどのエージェント・プローブ・スパンが、アプリケーション・スパン・スコープ内でJDBCコールが行われた場合でも、アプリケーションにリンクしなかったのはなぜですか。
A:エージェント・プローブがスパン・リンケージを作成するには、JDBCコールの前にアプリケーション・スパンをアクティブ化する必要があります。
- エージェントプローブスパンがHelidonスパンにリンクされていないのはなぜですか。
A: Helidonが作成したスパンがアクティブ化されていない場合は、ServerRequestから新しいスパンを作成し、親SpanContextを使用してアクティブ化できます。その後、すべてのAgent Probeスパンが新しいスパンの子になります。
- APMエージェントにOpenTracingバージョン0.33があり、アプリケーションにOpenTracingバージョン0.32が埋め込まれている場合、エージェント・ハイブリッド・モードはどのように機能しますか。
A:そのような場合は、OpenTracing 0.33を使用するようにアプリケーションを更新することを検討してください。
そうでない場合は、oracle-apm-agent/install/<version>/lib/extのOpenTracingライブラリを0.32に変更できます。APMエージェントは、OpenTracingバージョン0.32および0.33の両方と互換性があります。
- エージェント・ハイブリッド・モードを有効にした後、APMエージェントとアプリケーションがリクエストに対して個別のトレースを作成したのはなぜですか。
A: 構成ステップを確認し、プロパティが正しく設定されていることを確認します。詳細は、APMエージェント・ハイブリッド・モードの有効化を参照してください。
問題が解決しない場合は、OpenTracingライブラリをoracle-apm-agent/bootstrapにコピーする必要がある場合があります。
- APMトレーサ(1.2以下)を使用して構築された既存のアプリケーションで、エージェントからのハイブリッド・モード(1.3以上)を使用できますか。
A:いいえ。アプリケーション・ビルドに使用されるデプロイ済APMエージェントとAPMトレーサの両方が少なくとも1.3である必要があります。
- ハイブリッド・モードが有効な場合、AgentConfig.propertiesのサービス名が異なるサービス名設定のトレーサに使用されるのはなぜですか。
A: ハイブリッド・モードの場合、APMエージェントはトレーサを起動し、グローバル・トレーサとして登録されます。トレーサがアプリケーションまたはマイクロ・サービスによって起動された場合、トレーサ・インスタンスは実際にはグローバル・トレーサ・インスタンスです。したがって、
AgentConfig.propertiesファイルに定義されているのと同じサービス名が使用されます。エージェント・インスタンスごとに異なるサービス名を使用するには、そのサービス名をjavaシステム・プロパティまたは環境変数でオーバーライドする必要があります。 AgentConfig.propertiesファイルのサービス名をオーバーライドするにはどうすればよいですか。A: サービス名をオーバーライドするには、javaシステム・プロパティ(
com.oracle.apm.agent.service.name)または環境変数(com_oracle_apm_agent_service_name)を設定します。- MicronautアプリケーションのOpentracingハイブリッドモードを有効にするには?
- 「APM Javaエージェント・ハイブリッド・モードの構成」に記載されている手順に従います。
- アプリケーション
pom.xmlファイルにAPM Micronautトレーサを依存関係として追加します。詳細は、MicronautでのAPMトレーサの使用を参照してください。