JavaScript エージェント API

以下の表にパラメータを列挙します：

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

ineum('key', trackingKey);
 

ビーコンは、監視データを Instana に配信するため、 HTTP GET および POST を通じて、レポート用 URL に送信されます。

ineum('reportingUrl', reportingUrl);
 

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

ineum('reportingBackends', reportingBackends);
 

Instana は、Web サイト・メトリックを論理ページ別にセグメント化することができます。 そのためには、ユーザーが閲覧しているページに関するヒントが必要です。 このページ名は、コマンド page を通じて設定できます。 できるだけ早く page 設定してください。 ドキュメントの変更を反映させるために（例えば page シングルページアプリケーションの場合）、を変更できます。 これにより、 Instana はページ読み込みに加えてページ遷移を追跡できるようになります。

ineum('page', pageName);
 

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

ページを定義するには、や product detail page などの論理的な payment selection 名前を、や window.title の代わりに使用 window.hrefしてください。 または product detail page を使用すると、既存のコードと直接 payment selection 関連するページが少なくなります。 一方、 window.title またはを使用すると、多くの window.href 追跡対象ページが生成されますが、これらはほとんどの場合に価値を提供します。なぜなら window.title 、には製品名が含まれているからです。

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

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

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

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

ページ読み込みプロセスにおいて、例えばサーバーサイドで情報をHTMLドキュメントにレンダリングするなどして、 API を同期的に呼び出すことで、すべてのビーコンがユーザー情報を保持し、一意または影響を受けたユーザー統計が正確であり、分析時にビーコンが正しくフィルタリングおよびグループ化されることを保証するのに役立ちます。

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

セッション追跡は、ページ読み込みを跨いだエンドユーザーの活動に関する洞察を得るために使用できます。 セッション追跡は、特に Instana が定義されたユーザー情報がない場合でもエンドユーザーへの影響を特定することを可能にします。

セッションを追跡するため、 JavaScript エージェントは localStorage ブラウザ APItrackSessions を呼び出した後に使用します。 技術的には、セッションとはブラウザ内のキー localStorage の下に保存される2つのタイムスタンプと共に 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に対する評価。例えば、 JavaScript のURLやCSSファイルなど。 正規表現のいずれかに一致するリソースに関する情報は、 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 パスに基づいて編集可能なフラグメント値のパターン指定をサポートします。 この編集は、ウェブブラウザ内の JavaScript エージェント内で実行されます。 その結果、機密情報が Instana サーバーに送信され、処理されるのを防ぎます。 機密情報は、UI上での分析や API による取得にはアクセスできません。

ineum('fragment', fragment);
 

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

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

ユーザータイミング API を使用することで、複数の正規表現を定義できます。これらのうち少なくとも1つが一致した場合、特定のユーザータイミングのコレクションが生成されません。 デフォルトでは、以下の条件は無視されます：

• React のユーザータイミング：⚛️ または ⛔ 絵文字で始まるマークと小節
• Angular のユーザータイミング：以下で始まるマークと小節 Zone
• 名前が または start で始まるマークおよび測定単位 end

ineum('ignoreUserTimings', ignoreUserTimings);
 

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

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

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

ineum('queryTrackedDomainList',queryTrackedDomainList);
 

以下のシナリオは、 URL に秘密情報または断片が含まれ、または または ineum('secrets', secrets) を使用して編集された場合の ineum('fragment', fragment)条件を説明します：

• URL が のエントリと一致した場合 queryTrackedDomainList、編集された秘密情報または断片を含む URL 全体が Instana バックエンドに送信されます。
• URL がのエントリと一致しない場合、すべてのパラメータは除外された後、 URLqueryTrackedDomainListが Instana バックエンドに送信されます。

ブラウザがリモートサーバーにリクエストを送信し、 Instana エージェントがリモートサーバーを監視している場合、サーバーの応答には HTTP ヘッダーServer-Timingが含まれる可能性があります。これにより、ブラウザ内で動作する Instana エージェントに backendTraceId タイムスタンプが提供されます。 リモートサーバーで OpenTelemetry が有効になっている場合、 HTTPtracestate ヘッダーには. backendTraceIdが含まれることがあります。

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

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

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

• が有効になっている enableW3CHeaders 場合、次の2つの選択肢があります。 まず、現在のページのメタデータから値を tracestatetraceparent 抽出し、それを使用します。 取得 tracestateできない場合、 W3C トレースコンテキストと互換性のある16文字の長い文字列が生成され使用されます。
• 無効化されている enableW3CHeaders 場合、まず APItraceId が呼び出されているか確認してください。 APItraceId が呼び出された場合、そのIDを. backendTraceIdとして使用する。 APItraceId が呼び出されない場合、 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 オリジンであるため、 https://shop.example.com:443 へのリクエスト XMLHttpRequestを送信できません。

このセキュリティ制限を回避するために、 クロスオリジンリソース共有 （ 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 、 JavaScript エージェントによってキャプチャできます。 fetch captureHeaders コマンドを使用して、JavaScript エージェントにキャプチャーさせる HTTP ヘッダーを定義できます。

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