Application Insights JavaScript SDK のトラブルシューティング

[アーティクル]
04/13/2024

この記事では、 Application Insights JavaScript SDK に関連するさまざまな問題のトラブルシューティング方法について説明します。この記事では、JavaScript Web アプリの SDK の読み込みエラーと、JavaScript アプリのソースマップのサポートについて説明します。

JavaScript Web アプリの SDK の読み込みエラーのトラブルシューティング

次のセクションでは、JavaScript Web アプリの特定の SDK ロードエラーシナリオの症状、原因、解決策について説明します。

現象

<監視している Web ページの head> 要素で、JavaScript スニペット (バージョン 3 以降のバージョン) によって、SDK スクリプトがダウンロードまたは初期化されなかったことが検出されると、次の例外が作成され、報告されます。

SDK LOAD エラー: Application Insights SDK スクリプトの読み込みに失敗しました (詳細については、「スタック」を参照してください)

このメッセージは、ユーザーのクライアント (ブラウザー) が Application Insights SDK をダウンロードできないか、識別されたホスティングページから初期化できないことを示します。そのため、テレメトリやイベントは表示されません。

注:

この例外は、API または XMLHttpRequestをサポートするすべての主要なブラウザーでfetch()サポートされています。これらのブラウザーバージョンでは、Microsoft Internet エクスプローラー 8 以前のバージョンは除外されます。そのため、これらのブラウザーでは、環境にフェッチポリフィルが含まれていない限り、この種類の例外は報告されません。

スタックの詳細には、ユーザーが使用している URL に関する基本情報が含まれます。

名前	説明
<CDN エンドポイント>	SDK のダウンロードに使用された (失敗した) URL。
<ヘルプリンク>	トラブルシューティングドキュメントにリンクする URL (このページ)。
<ホスト URL>	ユーザーが使用していたページの完全な URL。
<エンドポイント URL>	例外を報告するために使用された URL。この値は、パブリックインターネットまたはプライベートクラウドがホスティングページにアクセスしたかどうかを識別するのに役立つ場合があります。

次の一覧には、この例外が発生する最も一般的な理由が含まれています。

断続的なネットワーク接続エラー
Application Insights Content Delivery Network (CDN) の停止
スクリプトの読み込み後の SDK 初期化エラー
Application Insights JavaScript CDN のブロック

この例外の最も一般的な理由は、特にモバイルローミングのシナリオでは、断続的なネットワーク接続エラーです。

次のセクションでは、このエラーの潜在的な根本原因をトラブルシューティングする方法について説明します。

注:

これらの手順の一部では、アプリケーションがスニペット <スクリプト/> タグと、ホスティング HTML ページの一部として返される構成を直接制御していることを前提としています。これらの条件がシナリオに適用されない場合、これらの手順も適用されません。

原因 1: 断続的なネットワーク接続エラー

ユーザーが間欠的なネットワーク接続エラーが発生した場合、考えられる解決策は他の原因よりも少なくなります。ただし、このエラーは通常、それ自体を迅速に解決します。たとえば、ユーザーがページを更新してサイトを再読み込みした場合、ファイルは最終的にダウンロードされ、更新されたバージョンがリリースされるまでローカルにキャッシュされます。

解決策 1a: SDK の更新バージョンをダウンロードする

断続的なネットワーク接続エラーを最小限に抑えるために、すべての CDN ファイルにヘッダーを実装しました Cache-Control 。ユーザーのブラウザーが SDK の現在のバージョンをダウンロードした後、以前に取得したコピーを再利用するため、もう一度ダウンロードする必要はありません。 (キャッシュのしくみを参照してください)。キャッシュチェックが失敗した場合、または使用可能な新しいリリースがある場合、ユーザーのブラウザーは更新されたバージョンをダウンロードする必要があります。そのため、チェックエラーシナリオではバックグラウンドレベルの "ノイズ" が表示される場合があります。または、新しいリリースが発生し、一般公開 (CDN にデプロイ) されると、一時的なスパイクが発生する可能性があります。

解決策 1b: npm パッケージを使用して、SDK をアプリケーションと共に 1 つのバンドルに埋め込む

SDK の読み込みエラー例外は永続的であり、通常のクライアントテレメトリの削減と共に多くのユーザーに対して発生しますか? この場合、間欠的なネットワーク接続の問題が問題の真の原因ではない可能性があるため、他の考えられる原因を調べる必要があります。

注:

このエラーが複数のユーザーに対して発生する一般的な兆候は、例外が迅速かつ持続的なレベルで報告されるということです。

このような状況では、独自の CDN で SDK をホストすることは、この例外の発生を提供したり減らしたりする可能性は低くなります。同じ問題が独自の CDN に影響し、npm パッケージソリューションを使用して SDK を使用する場合にも発生します。後者のシナリオの失敗は、特に、Application Insights が監視対象のアプリケーションとは異なるバンドルに含まれている場合に発生します。これは、障害が少なくとも 1 つのバンドルで発生することが保証されているためです。ユーザーの観点から見ると、この例外が発生すると、アプリケーション全体がテレメトリ SDK (ユーザーに表示されない) だけでなく、読み込みまたは初期化に失敗します。そのため、ユーザーは完全に読み込まれるまでサイトを更新し続ける可能性があります。

npm パッケージを使用して、監視対象のアプリケーションと共に Application Insights SDK を 1 つのバンドルに埋め込むことができます。このシナリオでは引き続き送信エラーが発生する可能性がありますが、組み合わされたバンドルでは問題を解決する可能性が高くなります。

原因 2: Application Insights CDN の停止

Application Insights CDN の停止が発生していることを確認するには、ブラウザーからユーザーとは異なる場所から CDN エンドポイントに直接アクセスしてみてください。たとえば、独自の開発用コンピューターからアクセス https://js.monitor.azure.com/scripts/b/ai.2.min.js を試すことができます。 (これは、organizationがこのドメインをブロックしていないことを前提としています)。

解決策 2: サポートチケットを作成する

障害が存在することを確認した場合は、新しいサポートチケットを作成できます。

原因 3: スクリプトの読み込み後に SDK が初期化されませんでした

SDK が初期化されない場合、 <スクリプト /> は CDN から正常にダウンロードされますが、初期化中に失敗します。このエラーは、依存関係が見つからないか無効であるか、何らかの形式の JavaScript 例外が原因で発生します。

解決策 3: SDK のダウンロードまたは JavaScript の例外が成功しているかどうかを確認するか、ブラウザーのデバッグを有効にする

手順 1: SDK のダウンロードが成功しているかどうかを確認する

SDK が正常にダウンロードされたかどうかを確認します。スクリプトのダウンロードが発生しなかった場合、このシナリオは SDK の読み込みエラー例外の原因ではありません。開発者ツールをサポートするブラウザーを使用します。 F12 を選択して開発者ツールを表示し、[ ネットワーク ] タブを選択します。 src スニペット構成で定義されているスクリプトがダウンロードされたことを確認します。これを行うには、応答コード 200 (成功) または 304 (変更なし) をチェックします。ネットワークトラフィックを確認するには、 Fiddler などの Web デバッグツールを使用することもできます。

SDK が正常にダウンロードされなかった場合は、次の表を参照して、さまざまなレポートオプションを理解してください。

シナリオ	原因	アクション
この問題は、少数のユーザーと特定のブラウザーバージョンまたはブラウザーバージョンのサブセットにのみ影響します。 (報告された例外の詳細を確認してください)。	この問題は、特定のユーザーまたは環境でアプリケーションに追加 `polyfill` の実装を提供する必要がある場合にのみ発生する可能性があります。	GitHub に問題を報告します。
この問題は、アプリケーション全体とすべてのユーザーに影響します。	これはリリース関連の問題です。	新しいサポートチケットを作成します。

SDK が正常にダウンロードされた場合は、SDK の初期化の問題を解決するために、次のセクションを確認してください。

手順 2: JavaScript 例外を確認する

JavaScript の例外を確認します。開発者ツールをサポートするブラウザーを使用します。 F12 を選択して開発者ツールを表示し、ページを読み込み、例外が発生したかどうかをチェックします。 SDK スクリプト (たとえば、 ai.2.min.js) は例外を引き起こしますか? この場合、次のいずれかのシナリオが発生しました。

SDK に渡される構成には、予期しない構成が含まれています。
SDK に渡される構成に必要な構成がありません。
障害のあるリリースが CDN にデプロイされました。

障害のある構成をチェックするには、スニペットに渡される構成 (まだこれを行っていない場合) を変更して、インストルメンテーションキーのみを文字列値として含めます。次のコードは、スニペット構成の変更の例を示しています。

注:

インストルメンテーションキーインジェストのサポートは、2025 年 3 月 31 日に終了します。インストルメンテーションキーインジェストは引き続き機能しますが、この機能の更新プログラムやサポートは提供されなくなります。新機能を利用するには、「接続文字列への移行」を参照してください。

<script type="text/javascript">
...
src: "https://js.monitor.azure.com/scripts/b/ai.2.min.js",
cfg: {
    instrumentationKey: "<instrumentation-key-guid>"
}});
</script>

この最小限の構成を使用する場合でも、SDK スクリプトに JavaScript 例外が表示される場合は、新しいサポートチケットを作成します。この問題を解決するには、障害のあるビルドをロールバックする必要があります。これは、新しくデプロイされたバージョンが問題の原因である可能性があるためです。

例外が消えた場合、型の不一致または予期しない値が原因で問題が発生している可能性があります。構成オプションを 1 つずつ復元してトラブルシューティングを開始し、例外が再び発生するまで各変更後にテストします。次に、問題の原因となる項目のドキュメントをチェックします。ドキュメントが不明な場合、またはサポートが必要な場合は、 GitHub に問題を提出してください。

構成は以前にデプロイされ、動作していましたが、この例外が報告されましたか? この場合、新しくデプロイされたバージョンに影響する問題が発生する可能性があります。例外がユーザーまたはブラウザーのごく一部にのみ影響するかどうかを確認します。 GitHub に問題を提出するか、新しいサポートチケットを作成します。

手順 3: ブラウザーコンソールのデバッグを有効にする

スローされた例外が発生しなかった場合は、次のスニペット構成例に示すように、 loggingLevelConsole 設定を構成に追加してコンソールデバッグを有効にする必要があります。この変更により、すべての初期化エラーと警告がブラウザーのコンソールに送信されます。 (ブラウザーコンソールを表示するには、F12 を選択して開発者ツールを開き、[ コンソール ] タブを選択します)。報告されたエラーは、自明である必要があります。さらにサポートが必要な場合は、 GitHub に問題を提出してください。

<script type="text/javascript">
...
src: "https://js.monitor.azure.com/scripts/b/ai.2.min.js",
cfg: {
    instrumentationKey: "<instrumentation-key-guid>",
    loggingLevelConsole: 2
}});
</script>

注:

初期化中に、SDK は既知の主要な依存関係に関するいくつかの基本的なチェックを行います。現在のランタイムがこれらのチェックを提供しない場合、ランタイムはエラーを警告メッセージとしてコンソールに報告します (ただし、設定値が 0 より大きい場合 loggingLevelConsole のみ)。

SDK がまだ初期化されない場合は、 enableDebug 構成設定を有効にしてみてください。この変更を行うと、すべての内部エラーが例外としてスローされます。これにより、テレメトリが失われます。この設定は開発者専用であるため、内部チェックのためにより多くの例外がスローされる可能性があります。各例外を確認して、SDK が失敗する原因となっている問題を特定します。未確定バージョンのスクリプトを使用します (ファイル名拡張子を .min.js から .jsのみに変更します)。それ以外の場合、例外は読み取りできません。次のコードは、スニペット構成の変更の例を示しています。

警告

この開発者専用の設定は、完全な運用環境では有効にしないでください。これを行うとテレメトリが失われるためです。

<script type="text/javascript">
...
src: "https://js.monitor.azure.com/scripts/b/ai.2.js",
cfg:{
    instrumentationKey: "<instrumentation-key-guid>",
    enableDebug: true
}});
</script>

それでもこのアクションで分析情報が得られない場合は、詳細とサイトの例を指定して GitHub に問題を提出する必要があります (使用している場合)。問題の特定に役立つブラウザーのバージョン、オペレーティングシステム、JavaScript フレームワークの詳細を含めます。

原因 4: Application Insights JavaScript CDN のブロック

Application Insights JavaScript SDK CDN エンドポイントが安全でないと報告または識別された場合、CDN のブロックが発生する可能性があります。この状況では、エンドポイントはパブリックにブロックリストされ、これらのリストのコンシューマーはすべてのアクセスをブロックし始めます。

この問題を解決するには、CDN エンドポイントの所有者が、エンドポイントを安全でないとマークしたブロックリストエンティティと連携する必要があります。その後、ブロックリストエンティティは、関連リストからエンドポイントを削除できます。

次のインターネットセキュリティ Web サイトを確認して、CDN エンドポイントが安全でないと識別されているかどうかを確認します。

この問題の解決には長い時間がかかる場合があります。ユーザーまたは企業の IT 部門は、更新を強制するか、CDN エンドポイントを明示的に許可する必要がある場合があります。この問題を解決するために必要な合計時間は、アプリケーション、ファイアウォール、または環境がリストのローカルコピーを更新するために必要な頻度によって異なります。

CDN エンドポイントが安全でないと識別された場合は、できるだけ早く問題を解決するためのサポートチケットを作成します。

次のセクションでは、より具体的にブロックが発生する方法と、ブロックを修正する方法について説明します。

原因 4a: ユーザーのブロック (ブラウザー、取り付け済みのブロック、または個人用ファイアウォール)

ユーザーが次のいずれかの構成アクションを実行したかどうかを確認します。

ブラウザープラグインをインストールしました (通常は広告、マルウェア、またはポップアップブロックの形式)
ブラウザーまたはプロキシで Application Insights CDN エンドポイントをブロックまたは禁止しました
SDK の CDN ドメインのブロック (または DNS エントリの解決に失敗) を引き起こすファイアウォール規則を構成しました

解決策 4a: CDN エンドポイントのブロックリスト例外を追加する

ユーザーが一覧表示されている構成アクションのいずれかを実行した場合は、CDN エンドポイントを許可するためにそれらを操作 (またはドキュメントを提供) します。

ユーザーは、パブリックブロックリストを使用するプラグインをインストールしている可能性があります。そうでない場合は、手動で構成された別のソリューションを使用しているか、プラグインがプライベートドメインブロックリストを使用している可能性があります。

ブラウザーのプラグインまたはファイアウォール規則の例外リストにエンドポイントを含めることで、Application Insights CDN エンドポイントからのスクリプトのダウンロードを許可するようにユーザーに指示します。これらのリストは、ユーザー環境によって異なります。

Web サイトへのアクセスを許可またはブロックするように Google Chrome を構成する方法を示すこの状況の例を次に示します。

原因 4b: 企業ファイアウォールのブロック

ユーザーが企業ネットワーク上にある場合、企業ファイアウォールが CDN のブロックの原因である可能性があります。企業の IT 部門は、おそらく何らかの形式のインターネットフィルタリングシステムを実装しています。

解決策 4b1: 企業の CDN エンドポイントの例外を追加する

重要

ユーザーはプライベートクラウドを使用しており、パブリックインターネットにアクセスできませんか? この場合は、 Application Insights npm パッケージを使用して SDK を埋め込むか、 Application Insights SDK を独自の CDN でホストする必要があります。

会社の IT 部門と連携して、ユーザーに必要なルールを許可します。このソリューションは、ユーザーに例外を追加するのと似ています。 IT 部門に、任意のドメインブロックリストまたは許可リストサービスに含める (または削除する) 方法で、ダウンロード用に Application Insights CDN エンドポイントを構成させます。

解決策 4b2: 独自の CDN で SDK をホストする

ユーザーにパブリック CDN から Application Insights SDK をダウンロードしてもらう代わりに、独自の CDN エンドポイントで Application Insights SDK をホストできます。 SDK の特定のバージョン (ai.2.#.#.min.js) を使用して、使用しているバージョンを簡単に特定することをお勧めします。また、SDK を現在のバージョン (ai.2.min.js) に定期的に更新して、使用可能になったバグ修正や新機能を使用できるようにします。

解決策 4b3: npm パッケージを使用して Application Insights SDK を埋め込む

スニペットを使用してパブリック CDN エンドポイントを追加する代わりに、npm パッケージを使用して、独自の JavaScript ファイルの一部として SDK を含めることができます。 SDK は、独自のスクリプト内の単なる別のパッケージになります。詳細については、Application Insights JavaScript SDK GitHub ページの npm ベースのセットアップに関するセクションを参照してください。

注:

npm パッケージを使用する場合は、コードの分割と縮小を行うのに役立つ何らかの形式の JavaScript bundler も使用することをお勧めします。

スニペットと同様に、ここに表示されるのと同じブロックの問題が、(SDK npm パッケージを使用する場合と使用しない) 独自のスクリプトに影響する可能性があります。アプリケーション、ユーザー、フレームワークによっては、スニペットのロジックと同様のものを実装して、これらの問題を検出して報告することを検討する場合があります。

JavaScript アプリケーションのソースマップのサポートのトラブルシューティング

次の表では、 JavaScript アプリケーションのソースマップのサポートに関連する特定の問題について説明し、これらの問題を解決するための戦略を示します。

問題	説明
BLOB コンテナーで必要な Azure ロールベースのアクセス制御 (Azure RBAC) 設定	この機能を使用するポータル上のユーザーには、少なくとも BLOB コンテナーのストレージ BLOB データ閲覧者ロールを割り当てる必要があります。この機能を使用してソースマップを使用するすべてのユーザーにこのロールを割り当てる必要があります。コンテナーの作成方法によっては、このロールが自分またはチームに自動的に割り当てられていない可能性があります。
ソースマップが見つかりません	この問題を解決するには、次のアクションを実行します。対応するソースマップが正しい BLOB コンテナーにアップロードされていることを確認します。ソースマップファイルが、マップ先の JavaScript ファイルからその名前を取得し、 .map ファイル名拡張子を持っていることを確認します。たとえば、 /static/js/main.4e2ca5fa.chunk.js は、main.4e2ca5fa.chunk.js.map という名前の BLOB を検索します。ブラウザーの本体を調べて、エラーがログに記録されているかどうかを確認します。この出力を任意のサポートチケットに含めます。

問題

説明

BLOB コンテナーで必要な Azure ロールベースのアクセス制御 (Azure RBAC) 設定

この機能を使用するポータル上のユーザーには、少なくとも BLOB コンテナーのストレージ BLOB データ閲覧者ロールを割り当てる必要があります。この機能を使用してソースマップを使用するすべてのユーザーにこのロールを割り当てる必要があります。コンテナーの作成方法によっては、このロールが自分またはチームに自動的に割り当てられていない可能性があります。

ソースマップが見つかりません

この問題を解決するには、次のアクションを実行します。

対応するソースマップが正しい BLOB コンテナーにアップロードされていることを確認します。
ソースマップファイルが、マップ先の JavaScript ファイルからその名前を取得し、 .map ファイル名拡張子を持っていることを確認します。たとえば、 /static/js/main.4e2ca5fa.chunk.js は 、main.4e2ca5fa.chunk.js.map という名前の BLOB を検索します。
ブラウザーの本体を調べて、エラーがログに記録されているかどうかを確認します。この出力を任意のサポートチケットに含めます。

"parentId 値なしでイベント行をクリックする" 警告を修正しました

アプリケーションで Application Insights プラグインと Click Analytics Auto-Collection プラグインを使用すると、アプリケーション分析情報ブックに次のテレメトリ警告が表示される場合があります。"parentId 値のないイベント行をクリックします"。

原因

この問題は、親 ID が親 HTML 要素で指定されていない場合に発生する可能性があります。この条件により、すべての親要素でイベントがトリガーされます。

ソリューション

この問題を解決するには、または data-<customPrefix>-parentid 属性をdata-parentid親 HTML 要素に追加します。 HTML コードの例を次に示します。

<div data-heart-id="demo Header" data-heart-parentid="demo.Header" data-heart-parent-group="demo.Header.Group">

次の手順

サードパーティの情報に関する免責事項

この資料に記載されているサードパーティ製品は、マイクロソフトと関連のない他社の製品です。明示的か黙示的かにかかわらず、これらの製品のパフォーマンスや信頼性についてマイクロソフトはいかなる責任も負わないものとします。

お問い合わせはこちらから

質問がある場合やヘルプが必要な場合は、サポート要求を作成するか、Azure コミュニティサポートにお問い合わせください。 Azure フィードバックコミュニティに製品フィードバックを送信することもできます。