JavaScript エージェント API

次の表にパラメータを一覧表示します：

監視キーはkeyコマンドで設定できる。 Instana のユーザーインターフェースでWebサイトを設定すると、監視キーが表示されます。

ineum('key', trackingKey);
 

ビーコンは、 HTTP へのGETリクエストおよび POST を通じてレポート用 URL に送信され、監視データが Instana に送信されます。

ineum('reportingUrl', reportingUrl);
 

場合によっては、 JavaScript エージェント・レポートを複数のバックエンドに作成することが望ましい場合があります。 この場合は、 reportingBackends コマンドを使用して、 JavaScript エージェントが複数のバックエンドにレポートするようにします。

ineum('reportingBackends', reportingBackends);
 

Instana は、Web サイト・メトリックを論理ページ別にセグメント化することができます。 そのためには、ユーザーが閲覧しているページに関する手がかりが必要です。 このページ名はpageコマンドで設定できる。 できるだけ早い段階でpageを設定する。 文書の変更を提示するpageを変更することができます（たとえば、単一ページのアプリケーションの場合）。 これにより、 Instana はページの読み込みだけでなく、ページ間の遷移も追跡できるようになります。

ineum('page', pageName);
 

API を通じてページ名が変更されるたびに、ページ遷移イベントが記録されます。ただし、 ページ読み込みフェーズ中にこの API が最初に呼び出された場合は除きます。

ページを定義するには、や window.title の代わりに payment selectionproduct detail page やのような論理 window.href名を使用してください。 または product detail page を使用すると、既存のコード payment selection と直接関連するページが少なくなります。 一方、 window.title やを使用すると、多くのトラッキング window.href 対象ページが生成されますが、には商品名が含ま window.title れているため、ほとんどの場合、それらは有益な情報を提供します。

Instana さまざまなフレームワークやライブラリ向けに、意味のあるページ名を収集する方法を示すサンプルプロジェクトを提供しています。 不足しているフレームワークやライブラリのプルリクエストやサポートリクエストを行う。

Instana に送信されるデータに、必要に応じてユーザー固有の情報を含めることができます。 この情報を使用して、以下のような追加機能をアンロックすることができます。

• エラーの影響を受けたユーザー数の計算
• 特定のユーザーのデータをフィルタリングするには
• どのユーザーがページの読み込みやAjax呼び出しを開始したかを確認するため。

デフォルトでは、Instana はユーザーが識別可能な情報をビーコンに関連付けません。 その際には、それぞれのデータ保護法にご注意ください。 Instana では、ユーザー ID は、特定のメトリクスの計算にのみ使用される透過的な string 要素です。 したがって、ユーザーの識別はユーザーIDによって行われる。 userName また、これを利用することで、より多くの userEmail フィルター機能や、ユーザー情報の効果的な表示を利用することもできます。

たとえば、ページの読み込みプロセス中にこの API を同期的に呼び出し、サーバー側で情報をHTMLドキュメントにレンダリングすることで、すべてのビーコンにユーザー情報が確実に含まれるようにし、一意のユーザー統計や影響を受けたユーザーの統計が正確になり、分析時にビーコンが適切にフィルタリングおよびグループ化されるようになります。

ineum('user', userId, userName, userEmail);
 

セッション・トラッキングは、ページロードをまたがるエンドユーザーのアクティビティに関する洞察を得るために使用することができます。 セッション追跡機能により、 Instana は、ユーザー情報が定義されていない場合でも、エンドユーザーへの影響を特定することが可能になります。

セッションを追跡するために、 JavaScript エージェントは、呼び出し trackSessions を行った後、 localStorage ブラウザの API を使用します。 厳密に言えば、セッションとは、ブラウザの 内に、2つのタイム localStorage スタンプと共に キーの下に保存されるランダム in-sessionなIDのことです。

プライバシー規定の順守は、この API の呼び出し元の責任です。

メタデータは、ページ・ロードおよび Ajax 呼び出しに注釈を付けるために使用できます。 メタデータを使用して、UIの設定値、設定、機能フラグ、または分析に役立つ可能性のあるその他のコンテキストを追跡します。

ineum('meta', key, value);
 

ページの読み込み時に、フロントエンドとバックエンドの相関分析を可能にするために、バックエンドのトレースIDを定義することができます。 詳細については、 「バックエンド相関」 を参照してください。 ページ読み込み時のバックエンド処理とフロントエンド処理を関連付けるには、バックエンドのトレースIDを定義する必要があります。 または fetchXMLHttpRequest リクエスト間の相関関係は必須ではありません。 トレースIDは16文字または32文字の16進文字列でなければならない。

ineum('traceId', traceId);
 

この API を使用すると、複数の正規表現を定義できます。 少なくとも1つでも一致する場合、 Instana へのデータ送信は行われません。 正規表現は以下のシナリオで評価される：

• ドキュメントのURL（アドレスバーに表示されるURL、つまり）に基づいて評価を行います。正規 window.location.href表現のいずれかに一致した場合、 Instana へのすべてのデータ送信が無効化されます。
• リソースのURL（例えば、JavaScriptCSSファイルのURL）に対する評価。 正規表現のいずれかに一致するリソースに関する情報は、 Instana には送信されません。
• 例えば、 HTTP へのリクエストのターゲット URL に対する評価。具体的には、および XMLHttpRequest を通じて fetch行われます。 正規表現のいずれかに一致する HTTP への呼び出しに関する情報は、 Instana には送信されません。

ineum('ignoreUrls', ignoreUrls);
 

Instana また、ドキュメントのURL（つまり、ブラウザのアドレスバーに表示される URL ）からシークレットを抽出する機能もサポートしています（ シークレットについては API を参照してください）。 しかし、ドキュメントのURLに格納された秘密は、すべての第三者にほぼ漏れることに注意してください。 ドキュメントのURLに保存されたシークレットが、あらゆるサードパーティに漏洩しやすい理由を説明する専用のサンプルアプリを用意しています。 詳細については、このアプリの例と説明を参照してください。 ただし、この API を通じて、これらのURLに関するすべての監視データの収集を無効にすることも可能です。

収集したURLのクエリパラメータに機密データが含まれている可能性がある。 したがって、JavaScriptエージェントは、値が編集されるクエリパラメータキーのパターンの指定をサポートします。 再編集はJavaScriptエージェント内、つまりウェブブラウザ内で行われる。 したがって、シークレットは処理のために Instana サーバーに送信されることはなく、UIでの分析や API 経由での取得もできません。

ineum('secrets', secrets);
 

照会パラメーターがリストの項目と一致する場合、値は編集され、Instana バックエンドに送信されません。 ineum('secrets') が定義されていない場合、Instana はデフォルトで [/key/i, /secret/i, /password/i] をマッチング・ルールとして使用します。

収集された URL のフラグメントには、機密情報が含まれている可能性があります。 したがって、 JavaScript エージェントは、 URL パスに基づいて非表示にできるフラグメント値のパターンを指定する機能をサポートしています。 この編集は、Webブラウザ内の JavaScript エージェント内で行われます。 その結果、機密情報が Instana サーバーに送信され、処理されるのを防ぐことができます。 機密情報は、UIでの分析や API による取得の対象外となります。

ineum('fragment', fragment);
 

URL パスの一部がリスト内のエントリと一致した場合、そのフラグメント値は伏せられ、 Instana バックエンドには送信されません。 デフォルトでは、 Instana は URL の断片を非表示にしません。

Instana User-Timing API を通じて作成されたマーカーと計測値を自動的に収集し、それらをカスタムイベントに変換します。 つまり、ユーザー・タイミング API は、純粋なタイミング・データを Instana に報告するためのベンダー中立の方法として使用できます。

User-Timing API を使用すると、複数の正規表現を定義でき、そのうち少なくとも1つに一致した場合、特定のユーザータイミングの収集が行われないようにすることができます。 デフォルトでは、以下の条件は無視される：

• React のuser-timings：⚛️または⛔の絵文字で始まるマークとメジャ
• Angular のuser-timings：次のように始まるマークとメジャー Zone
• 名前が または start で始まる単位 end

ineum('ignoreUserTimings', ignoreUserTimings);
 

デフォルトでは、 JavaScript エージェントは、すべてのパラメータを含む完全な URL を収集します。 エージェントの設定により、指定された正規表現のリストに一致するURLのパラメータのみを収集するように設定できます。 除外されたURLのパラメータは追跡されません。

提供された正規表現のリストに基づき、 JavaScript エージェントは次のようにURLを追跡します：

• URL がリストのエントリと一致する場合、すべてのパラメータを含む URL 全体が取得されます。
• URL がリストのエントリと一致しない場合、クエリパラメータおよび URL のフラグメントは、 Instana バックエンドに送信されません。
• 指定されたリストが空の場合、デフォルトの動作が適用され、 URL およびそのパラメータのすべてが追跡されます。

ineum('queryTrackedDomainList',queryTrackedDomainList);
 

以下のシナリオでは、 URL に、 ineum('fragment', fragment)または ineum('secrets', secrets) を使用して伏せられたシークレットまたはフラグメントが含まれている場合の状況を説明します

• URL がの項目と一致した場合、秘密鍵またはその一部が伏せられた URLqueryTrackedDomainList全体が、 Instana バックエンドに送信されます。
• URL がの項目と一致しない場合、 URL を queryTrackedDomainListInstana バックエンドに送信する前に、すべてのパラメータが除外されます。

ブラウザがリモートサーバーにリクエストを送信し、 Instana エージェントがそのリモートサーバーを監視している場合、サーバーのレスポンスには、ブラウザ内で実行されている Instana エージェントに backendTraceId 情報を提供するために、 HTTP ヘッダー「Server-Timing」が含まれることがあります。 リモートサーバーで OpenTelemetry が有効になっている場合、 HTTPtracestate ヘッダーには.が含まれることがあります backendTraceId。

tracestate および traceparent は、分散トレースIDの照合に使用される W3C-defined ヘッダーです。 W3C のトレースヘッダーに関する詳細については、 「トレースコンテキストレベル」 を参照してください。

リモートサーバーが OpenTelemetry を使用でき、ヘッダー tracestate に backendTraceId その値を提供できると予想される場合、ブラウザの Instana エージェントは、 W3CbackendTraceId ヘッダーの値を利用するために、 APIenableW3CHeaders をtrueに設定する必要があります。

この設定は backendTraceId 、3つの異なる場所で行うことができます。 Server-Timing ヘッダー、 tracestate ヘッダー、およびブラウザの APItraceId を使用して手動で行う方法です。 これらのアプローチの手順は以下の通りです：

• が有効になっている enableW3CHeaders 場合、2つの選択肢があります。 まず、現在のページのメタデータからその tracestate 値を traceparent 抽出し、それを使用します。 を取得 tracestateできない場合は、 W3C のトレースコンテキストと互換性のある16文字の文字列が生成され、使用されます。
• が無効になっている enableW3CHeaders 場合は、まず APItraceId が呼び出されているか確認してください。 API traceId が呼び出された場合は、その ID を として使用します backendTraceId。 API traceId が呼び出されない場合は、 HTTP ヘッダーの Server-Timing を解析して、. backendTraceIdを取得します。
• 上記の値がいずれも利用できない場合、ビーコンをバックエンドのトレースに関連付けることはできません。

ineum('enableW3CHeaders',true);
 

追加のメトリクスを収集するために、 JavaScript エージェントは、以下の条件が満たされるまで待機します。 例えば、初期入力遅延や累積レイアウトシフトなどです。

• すべてのメトリクスが利用可能
• ページがアンロードされた（タブが閉じられたなど）
• 最大待機時間が経過するまで

この API を使用して、最大待ち時間を再構成することができます。 デフォルトでは、 Instana は、ページの読み込みが完了し、 onLoad イベントが終了してから最大1秒間待機します。

ineum('maxMaitForPageLoadMetricsMillis', durationMillis);
 

たとえば、カスタム相関分析を行いたい場合など、ページ読み込みのIDを手動で取得しておくと便利なことがあります。 この関数は、JavaScriptエージェントがロードされない限り、undefinedを返す。 JavaScriptエージェントがロードされた後は、常に同じstringを返します。

ineum('getPageLoadId');
 

「グローバルカスタムイベント」の詳細については、 「イベント」ページをご覧ください。

カスタムイベントを使用すると、標準外のアクティビティ、重要なインタラクション、およびカスタムタイミングに関するレポートを Instana に送信できます。 これは、未処理のエラー（ブレッドクラム）を分析したり、より多くのパフォーマンス指標を追跡したりする際に特に役立ちます。

ineum('reportEvent', eventName, {
  duration: duration,
  timestamp: timestamp,
  backendTraceId: backendTraceId,
  error: error,
  componentStack: componentStack,
  meta: meta,
  customMetric: customMetric
});
 

Instana のバックエンド相関は、XMLHttpRequest 要求または fetch 要求にカスタム・ヘッダーを設定することで機能します。 JavaScript エージェントはこれらのヘッダーを設定し、サーバーがそれらを読み取ります。 ブラウザーでは、同一オリジン・ポリシーによってカスタム・ヘッダーの送信が制限されています。 より具体的には、カスタムヘッダは同じオリジンのリクエスト、あるいはカスタムヘッダの送信を許可している他のオリジンへのリクエストに対してのみ設定できます。 例えば、デフォルトでは、https://example.com:443から提供されているウェブサイトは、XMLHttpRequestを https://shop.example.com:443にすることはできない。

このセキュリティ制限を回避するために、 クロスオリジンリソース共有 （ CORS ）を利用できます。 CORS を使用すると、クロス・オリジン・リソース・アクセスに対してオリジンを許可できます。 既にアプリケーション内にクロス・オリジン・リソース・アクセスがある場合は、何らかの CORS ヘッダーを既に使用しているはずです。

Instana のバックエンド相関機能を有効にするには、以下の手順を実行してください：

1. サーバー・サイドで以下のヘッダーによって応答することにより、クロス・オリジン要求に対して Instana の相関ヘッダーを許可します。

   注： サーバーは、プレフライトリクエストと通常のリクエストの両方に対して、これらのヘッダーを含めて応答する必要があります。 プリフライトリクエスト（ HTTPOPTIONS メソッドによって識別可能）は、サーバーへのリクエストが送信される可能性があるかどうかを確認するために、ブラウザによって実行されます。

   Access-Control-Allow-Origin: https://your-origin.example.com
   Access-Control-Allow-Headers: X-INSTANA-T, X-INSTANA-S, X-INSTANA-L
   
    

2. JavaScript のエージェントに対し、 CORS が正しく設定されており、以下の相関ヘッダーを設定する必要があることを通知してください：

   ineum('allowedOrigins', urls);
    

HTTP リクエストまたはレスポンスのヘッダーは XMLHttpRequest 、 fetchJavaScript エージェントによって取得できます。 captureHeaders コマンドを使用して、JavaScript エージェントにキャプチャーさせる HTTP ヘッダーを定義できます。

ブラウザー内では、同一生成元ポリシーによってカスタム・ヘッダーのアクセスが制限されます。 クロス・オリジン・リソース共有 (CORS) 構成がないと、JavaScript エージェントがすべての HTTP ヘッダーをキャプチャーできない場合があります。 CORS を有効にするには、 クロス・オリジン要求のバックエンド相関を参照してください。 CORS を使用する場合、 JavaScript エージェントが収集できるのは、 CORS の条件を満たすリクエストまたはレスポンスヘッダー、およびAccess-Control-Expose-Headersで定義されているヘッダーのみです。