Ajaxコール・インストゥルメンテーションの構成

Application Performance Monitoringで、ajaxコール・インストゥルメンテーションを構成できます。

相互層トレースの実行を許可するために、APMブラウザ・エージェントは、X-B3-*のようなヘッダーを使用してAjaxコールの送信にトレース・コンテキストを追加します。これらのヘッダーは、潜在的なサーバー・エージェント/トレーサに、Ajaxコールをトリガーしたトレースとスパンを通知します。これにより、伝播されたコンテキストに基づいてブラウザからバックエンド・サーバーへの完全なフローについてレポートできます。

デフォルトでは、前述の動作は、同じドメインを共有し、外部ドメインへのajaxコールを除外するすべてのajaxコールに適用されます。外部ドメインが同じAPMモニタリング環境を共有しないことを前提としています。このロジックが適用されない場合、外部ドメインへのコールでヘッダーを有効にするか、同じドメインへの一部のコールに対してヘッダーを無効にできます。

サンプル構成:

apmrum.traceSupportingEndpoints =  [ 
    { headers: [ ], hostPattern: 'https://((identity)|(console)).*' },
    { headers: [ 'APM' ], hostPattern: 'https://my-rest-server.*' }
]

前述の構成は、「identity」または「console」で始まるURLの場合、ヘッダーを操作できないこと(空のコンテキスト)、および「my-rest-server」で始まるURLについては、APMブラウザ・エージェントが存在するため、ヘッダーにはpmコンテキストで注釈を付ける必要があることを示しています。

ノート

apmrum.traceSupportingEndpoints構成は、定義の順序に依存します。ajax URLに一致する最初のhostPatternのヘッダー定義が使用されます。最初の定義にhostPattern: ".*"がある場合、他のすべての定義は無視されます。推奨される構成は、ajax URLの接頭辞または接尾辞を一貫して使用して、目的の構成を作成することです。

APMブラウザ・エージェントによるCORS障害

ブラウザ・エージェントによって、ブラウザでリクエストが失敗する場合があります。たとえば、これは、GETコールにB3ヘッダー注釈が付けられ、プリフライトをトリガーする場合に発生します。

サーバーは、正しい`Access-Control-Allow-Origin`ヘッダーをOPTIONSに、実際のGETコールで応答する必要があります。また、サーバーは、関連するコンテキスト関連のヘッダーに、それらの問題を回避できるようにマークする必要があります。

CORS (クロス・オリジン・リソース共有)プロトコルの詳細は、https://fetch.spec.whatwg.org/#cors-protocolを参照してください。

バックエンド・トレース・エージェントを使用したブラウザ・エージェントの統合

Application Performance Monitoringでは、ブラウザ・エージェントをバックエンド・トレース・エージェントと統合できます。

ブラウザ・エージェントは、ブラウザ・アクティビティとバックエンド・アクティビティの統合ビューのために、トレース・コンテキストを記録し、Ajaxコールにプッシュします。これは、様々なタイプのバックエンド・サーバー・エージェントに対して様々なタイプのヘッダーを使用して実行できます。このようなカスタム・ヘッダーがAjaxコールに追加されるため、CORS (クロス・オリジン・リソース共有)検証のプリフライト・リクエストが必要になります。CORSプロトコルの詳細は、https://fetch.spec.whatwg.org/#cors-protocolを参照してください。

そのようなプリフライト・コールを処理するようにサーバーが構成されていない場合、ブラウザはAjaxコールを予期したとおりに処理せず、アプリケーションが期待どおりに動作しない可能性があります。関連する問題を回避するために、APMブラウザエージェントはajax呼び出しをチェックし、同じドメインに移動するプリフライト要求または要求を持つ要求にのみカスタムヘッダーを追加します。

ドメイン名は、第2レベルとトップ・レベルのドメインに基づいて比較されます。たとえば、api.oracle.comはapex.oracle.comと同じドメインとみなされます。

ブラウザ・エージェントとバックエンド・トレース・エージェントの統合の詳細は、次を参照してください。

サーバー・エージェントを使用したRestエンドポイントの構成

htmlとは異なるURLを使用してアクセスされるシステムにサーバー・エージェントがインストールされている場合は、追加の構成が必要です。この構成では、関連するトレース・ヘッダーを追加する必要があることをブラウザ・エージェントに通知し、プリフライト・リクエストが適切に処理されます。

APM Javaエージェントを使用したサンプル構成

同じドメインの認識時にデフォルト・ロジックを無効にするサンプル構成を次に示しますが、https://regexThatMatchesServersThatHaveServerAgent.*を使用してAPM Java AgentがインストールされているURLパターンを指定できます。APM Javaエージェント・コンテキスト・ヘッダーは、このパターンに一致するURLに対して行われたAjaxコールでのみ使用されます。他のすべてのURLは「.*」パターンに一致し、コンテキストが空であるため注釈付けされません。

document.apmrum.traceSupportingEndpoints =  [
    { headers: [ 'APM'], hostPattern: 'https://regexThatMatchesServersThatHaveServerAgent.*'},
    { headers: [ ], hostPattern: '.*'} // block headers for everything else
];

エージェントが異なるサンプル構成

/* sample configuration for an app running on 
* sample.oracle.com, by default 'APM' headers
* are added for ajax-calls to data.oracle.com
* (same domain) so no configuration needed in
* that scenario.
*/
document.apmrum.traceSupportingEndpoints = [
 /* apm server agent running on api.oracledata.com servers */
  { hostPattern: 'https://api.oracledata.com', headers: [ 'APM']},

 /* oracle functions uses B3 header for integration */
 { hostPattern: 'https://functions.oraclecloud.com', headers: [ 'B3-Multi']}, 

  /* more complex configuration withregexp host and multiple header types combined */   
   { hostPattern: 'https://*.extern.*.com', headers: ['W3C', 'B3-Multi']},

 /* server has no agent therefore don't send headers */
  { hostPattern: 'https://info.oracle.com', headers: []}, 
]

コンテキスト伝播ヘッダー

次の表に、APMブラウザ・エージェントがサポートする様々なタイプのコンテキスト伝播ヘッダーを示します。

名前	コンテキスト伝播ヘッダー	説明
午後	X-B3-TraceId X-B3-SpanId X-B3-Sampled X-Oracle-Apm-Ba-Version	APM Java Agentをインストールして、サーバー側トレース情報を結合します。
B3-Single	b3	トレース情報が結合された単一のb3ヘッダー。
B3-Multi	X-B3-TraceId X-B3-SpanId X-B3-Sampled	値が別々のヘッダーに分散されたB3ヘッダー。
W3C	トレース親	W3Cで指定された単一のヘッダーにトレース・スパン情報が結合されました。
UberId	Uber-Trace-Id	トレース・コンテキストを単一値に結合したuberIdヘッダー。

Oracle Cloud Infrastructureドキュメント

Ajaxコール・インストゥルメンテーションの構成