JavaScript エージェント API

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

モニタリング・キーは key コマンドで設定できる。 モニタリングキーは、Instana のユーザーインターフェイス内でウェブサイトを構成するときに表示されます。

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 や window.href ではなく、 product detail page や payment selection のような論理名を使用する。 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 エージェントは、 を呼び出した後、ブラウザAPIを使用する。 localStoragetrackSessions ブラウザAPIを使用する。 厳密には、セッションとはランダムなIDのことで、ブラウザの localStorage 、 in-session というキーの下に、2つのタイムスタンプとともに保存される。

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

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

ineum('meta', key, value);
 

ページロードの一部として、バックエンドのトレースIDを定義し、フロントエンドとバックエンドの相関をとることができる。 詳細については、 バックエンド相関を参照のこと。 バックエンドのトレースIDを定義することは、ページロードのバックエンドとフロントエンドの処理の相関を得るために必要である。 XMLHttpRequest 、 fetch リクエスト間の相関には必要ない。 トレースIDは、16文字または32文字の16進文字列でなければならない。

ineum('traceId', traceId);
 

このAPIを使えば、いくつかの正規表現を定義することができる。 少なくとも1つ一致すれば、Instanaへのデータ送信には至らない。 正規表現は以下のシナリオで評価される：

• ドキュメントのURL（アドレスバーに表示されているURL、つまり window.location.href ）に対する評価。正規表現のいずれかがマッチすると、Instanaへのデータ送信はすべて無効になる。
• リソースのURL（例えば、 JavaScript やCSSファイルのURL）に対する評価。 正規表現のいずれかに一致するリソースに関する情報は、Instanaに送信されません。
• XMLHttpRequest や fetch など、 HTTP 呼び出しの対象 URL に対する評価。 正規表現のいずれかに一致する HTTP コールに関する情報は、Instana には送信されない。

ineum('ignoreUrls', ignoreUrls);
 

Instanaは、ドキュメントのURL、つまりブラウザのアドレスバーに表示される URL （ secrets 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は、 User-Timing APIを通じて行われたマーカーとメジャーを自動的に収集し、 カスタムイベントに変換します。 つまり、ユーザー・タイミング API は、純粋なタイミング・データを Instana に報告するためのベンダー中立の方法として使用できます。

User-Timing 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 が queryTrackedDomainList のエントリと一致しない場合、 URL を Instana バックエンドに送信する前に、すべてのパラメータが除外される。

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

tracestate と traceparent は、分散トレースIDの関連付けに使用される W3C-defined ヘッダーである。 W3C トレース・ヘッダーの詳細については、 トレース・コンテキスト・レベルを参照のこと。

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

backendTraceId Server-Timing ヘッダー、 ヘッダー、そしてブラウザーの APIを使った手動です。 tracestate traceId これらのアプローチの順序は以下の通りである：

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

ineum('enableW3CHeaders',true);
 

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

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

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

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（ Cross-Origin Resource Sharing ）が利用できる。 CORS を使用すると、クロス・オリジン・リソース・アクセスに対してオリジンを許可できます。 既にアプリケーション内にクロス・オリジン・リソース・アクセスがある場合は、何らかの CORS ヘッダーを既に使用しているはずです。

Instana バックエンド相関を有効にするには、次の手順を実行します：

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

   注意: あなたのサーバーは、 プリフライトリクエストと通常のリクエストの両方に対して、これらのヘッダーで応答しなければなりません。 プリフライトリクエスト（ OPTIONS HTTP メソッドで識別可能）は、ブラウザによって実行され、リクエストがサーバーに発行される可能性があることを確認する。

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

2. CORSが正しく設定され、相関ヘッダーを設定しなければならないことを、 JavaScript エージェントに通知する：

   ineum('allowedOrigins', urls);
    

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

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