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

SDK 読み込みエラーの例外は、SDK スクリプトがダウンロードまたは初期化に失敗したことが JavaScript スニペット (v3 以降) によって検出されると、作成および報告されます。 つまり、エンド ユーザーのクライアント (ブラウザー) が Application Insights SDK をダウンロードできなかったか、識別されたホスト ページから初期化できなかったため、テレメトリやイベントはまったく報告されません。

Azure portal browser failure overview

Note

この例外は、fetch() API や XMLHttpRequest をサポートするすべての主要なブラウザーでサポートされています。 IE 8 以下は除外されます。このため、それらのブラウザーではこの種の例外は報告されません (ご使用の環境に fetch polyfill が含まれている場合を除く)。

browser exception detail

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

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

この例外が発生する最も一般的な理由は次のとおりです。

  • 間欠的なネットワーク接続エラー。
  • Application Insights CDN の停止。
  • スクリプト読み込み後の SDK の初期化エラー。
  • Application Insights JavaScript CDN がブロックされている。

間欠的なネットワーク接続エラーは、この例外の最も一般的な理由であり、ユーザーのネットワーク接続が間欠的に失われるモバイル ローミング シナリオでは特にこれが原因となります。

以下のセクションでは、このエラーの根本原因として考えられるものそれぞれのトラブルシューティングを行う方法を説明します。

Note

トラブルシューティングの手順のいくつかは、ホストしている HTML ページの一部として返されるスニペット <script /> タグとその構成をアプリケーションで直接制御できることを前提としています。 そうでない場合、特定されている手順はシナリオに適用されません。

間欠的なネットワーク接続エラー

間欠的なネットワーク接続エラーをユーザーが経験している場合、考えられる解決策は限られており、通常はしばらくすると自然に解決します。 たとえば、ユーザーがサイトを再度読み込むと (ページを最新の情報に更新)、ファイルは (最終的には) ダウンロードされて、更新されたバージョンがリリースされるまでの間、ローカルにキャッシュされます。

Note

この例外が解決せず、ユーザーの多くにこの例外が発生しており (この例外が急速かつ持続的に報告されていることにより診断)、通常のクライアント テレメトリが減少している場合、間欠的なネットワーク接続エラーは、この問題の真の原因ではない可能性が高いため、考えられる他の既知の問題かどうか診断を続ける必要があります。

この状況では、SDK を独自の CDN でホストしても、その CDN も同じ問題の影響を受けるため、この例外の発生は増えも減りもしません。

NPM パッケージ ソリューション経由で SDK を使用する場合にも同じことが言えます。 ただし、エンド ユーザーの観点から見ると、この問題が発生したときには、アプリケーション全体が読み込みまたは初期化に失敗している (エンド ユーザーには見えていないテレメトリ SDK "のみ" ではなく) ため、サイトが完全に読み込まれるまでそれを最新の情報に更新する可能性が非常に高くなります。

NPM パッケージを使用して、Application Insights SDK を埋め込むことも試すことができます。

間欠的なネットワーク接続エラーを最小限に抑えるため、すべての CDN ファイルに Cache-Control ヘッダーが実装されています。この結果、エンド ユーザーのブラウザーで SDK の現在のバージョンがダウンロードされると、再びダウンロードする必要はなくなり、ブラウザーは以前に取得したコピーを再利用します (「キャッシュのしくみ」を参照)。 キャッシュ チェックが失敗するか新しいリリースが存在する場合は、エンド ユーザーのブラウザーは更新されたバージョンをダウンロードする必要があります。 このため、新しいリリースが作成されて一般提供 (CDN にデプロイ) されると、チェック エラー シナリオでのバックグラウンド レベルの "ノイズ" や、一時的なスパイクが確認される場合があります。

Application Insights CDN の停止

Application Insights CDN が停止しているかどうかは、エンド ユーザーの場所とは異なる場所、おそらくご自分の開発用マシンから (組織でこのドメインがブロックされていない場合)、ブラウザー (https://js.monitor.azure.com/scripts/b/ai.2.min.js など) で直接 CDN エンドポイントにアクセスしてみることで確認できます。

停止の発生を確認した場合、新しいサポート チケットを作成できます。

スクリプト読み込み後の SDK の初期化エラー

SDK が初期化に失敗する場合、<script /> は CDN から正常にダウンロードされていますが、初期化中にエラーが発生しています。 これは、存在しない依存関係や無効な依存関係、何らかの形の JavaScript 例外が原因である可能性があります。

最初に、SDK が正常にダウンロードされたかどうかを確認します。スクリプトがダウンロードされていない場合、このシナリオは SDK 読み込みエラーの例外の原因ではありません

クイック チェック:開発者ツール (F12) をサポートするブラウザーを使用して、src スニペット構成で定義されているスクリプトがダウンロードされており、応答コードが 200 (成功) または 304 (変更なし) になっていることを [ネットワーク] タブで検証します。 fiddler などのツールを使用して、ネットワーク トラフィックを確認することもできます。

以下のセクションで、さまざまなレポート オプションについて説明します。サポート チケットを作成するか、GitHub で問題を報告することをお勧めします。

レポートの基本的なルール:

  • 問題が少数のユーザーや特定のブラウザー バージョンまたはそのサブセットにのみ影響している場合 (報告された例外の詳細を確認)、エンド ユーザーや環境に限定された問題であると考えられます。その場合は、アプリケーションで polyfill を追加実装することが必要になる可能性があります。 この場合は、GitHub で問題を提出してください。
  • この問題がアプリケーション全体に影響を与えており、すべてのユーザーが影響を受けている場合は、リリース関連の問題であると考えられます。その場合は、新しいサポート チケットを作成する必要があります。

JavaScript の例外

最初に、開発者ツール (F12) をサポートするブラウザーを使用して、JavaScript 例外のチェックでページを読み込み、何らかの例外が発生していないか確認します。

SDK スクリプト (ai.2.min.js など) で例外が報告されている場合、SDK に渡された構成に、予期しない、または必要なのに不足している構成が含まれている可能性があります。また、問題のあるリリースが CDN にデプロイされていることも考えられます。

構成が間違っていないかどうかを確認するには、スニペットに渡される構成を変更し (まだ行っていない場合)、その構成に文字列値としてインストルメンテーション キーのみが含まれるようにします。

注意

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

src: "https://js.monitor.azure.com/scripts/b/ai.2.min.js",
cfg: {
    instrumentationKey: "INSTRUMENTATION_KEY"
}});

この最小構成でも SDK スクリプトで JavaScript の例外が引き続き発生する場合は、新しくデプロイされたバージョンの問題である可能性があり、障害が発生したビルドをロールバックすることが必要になるため、新しいサポート チケットを作成してください。

例外が発生しなくなった場合、問題の原因は型の不一致または予期しない値だったと考えられます。 構成オプションを 1 つずつ元に戻して、例外が再び発生するまでテストを繰り返します。 その後、問題の原因となっていた項目のドキュメントを確認します。 ドキュメントがわかりづらい場合やサポートが必要な場合は、GitHub で問題を提出してください。

構成が以前にデプロイされたもので、正常に動作していたのに突然この例外が報告されるようになった場合は、新しくデプロイされたバージョンの問題であると考えられます。ユーザーやブラウザーのごく一部にのみ影響を与えているかを確認し、GitHub で問題を提出するか、新しいサポート チケットを作成してください。

コンソールのデバッグを有効にする

例外がスローされていない場合は、次の手順として、loggingLevelConsole 設定を構成に追加して、コンソールのデバッグを有効にします。このようにすると、すべての初期化エラーと警告がブラウザー コンソールに送信されます (通常は開発者ツール (F12) で利用可能)。 報告されるエラーの意味はそのメッセージが示すとおりですが、さらにサポートが必要な場合は、GitHub で問題を提出してください。

cfg: {
    instrumentationKey: "INSTRUMENTATION_KEY",
    loggingLevelConsole: 2
}});

Note

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

それでも初期化に失敗する場合は、enableDebug 構成設定を有効にしてみます。 このようにすると、内部エラーはすべて例外としてスローされます (この結果、テレメトリは失われます)。 これは開発者専用の設定であるため、内部チェックの一部として頻繁に例外がスローされてノイズが多くなると考えられます。どの問題が原因で SDK が失敗しているかを特定するには、それらの例外をそれぞれ確認する必要があります。 縮小バージョンではないスクリプトを使用します (下のサンプルの拡張子が ".js" になっており、".min.js" ではないことにご注意ください)。そうしないと、例外が解読できなくなります。

警告

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

src: "https://js.monitor.azure.com/scripts/b/ai.2.js",
cfg:{
    instrumentationKey: "INSTRUMENTATION_KEY",
    enableDebug: true
}});

このようにしてもまだ分析情報が得られない場合は、詳細情報と、サンプル サイト (ある場合) を添えて、GitHub で問題を提出してください。 問題を特定するため、ブラウザー バージョン、オペレーティング システム、JS フレームワークに関する詳細を含めてください。

Application Insights JavaScript CDN がブロックされている

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

この問題を解決するため、その CDN エンドポイントの所有者は、そのエンドポイントに安全ではないというマークを付けたブロックリスト登録者と協力して、関連するリストからそれを削除する必要があります。

CDN エンドポイントが安全ではないと識別されているかどうかは、次で確認できます。

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

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

Application Insights JavaScript CDN がブロックされている (エンド ユーザーによる - ブラウザー、インストールされているブロック、パーソナル ファイアウォールによるブロック)

エンド ユーザーが次に該当しないかどうかを確認します。

  • ブラウザー プラグインをインストールした (通常は、何らかの広告、マルウェア、またはポップアップ ブロック)。
  • ブラウザーやプロキシで Application Insights CDN エンドポイントをブロックしている (または許可していない)。
  • SDK の CDN ドメインをブロックする (または DNS エントリが解決されない) 原因となるファイアウォール規則を構成している。

これらのオプションのいずれかが構成されている場合、ユーザーと協力して (またはドキュメントを提供して)、CDN エンドポイントを許可する必要があります。

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

CDN エンドポイントの例外を追加する

エンド ユーザーと協働するかドキュメントを準備して、Application Insights CDN エンドポイントからスクリプトをダウンロードできるようにするため、それをブラウザーのプラグインやファイアウォール規則の例外一覧 (エンド ユーザーの環境によって異なります) に含める必要があることを知らせます。

Web サイトへのアクセスを許可またはブロックするように Chrome を構成する方法については、このリンクを参照してください。

Application Insights CDN がブロックされている (企業のファイアウォールにより)

エンド ユーザーが企業のネットワークを使用している場合、ファイアウォール ソリューションが原因となっており、IT 部門が何らかの形式のインターネット フィルタリング システムを実装している可能性が高いと考えられます。 この場合、エンド ユーザーが必要とする規則が許可されるように、IT 部門と協力することが必要になります。

企業に関して CDN エンドポイントの例外を追加する

エンド ユーザーに関して例外を追加する場合と似ていますが、Application Insights CDN エンドポイントをドメイン ブロックリスト サービスや許可リスト サービスに含める (または削除する) ことにより、それらのエンドポイントをダウンロードできるよう、企業の IT 部門と協力して、構成を依頼することが必要になります。

警告

企業ユーザーがプライベート クラウドを使用しており、内部ユーザーに CDN エンドポイントへのパブリック アクセスを提供するための例外を作成することができない場合、Application Insights NPM パッケージを使用するか、独自の CDN で Application Insights SDK をホストすることが必要になります。

ブロックされた CDN に関するその他のトラブルシューティング

Note

ユーザーがプライベート クラウドを使用しており、パブリック インターネットにアクセスできない場合、独自の CDN で SDK をホストするか、NPM パッケージを使用する必要があります。

独自の CDN で SDK をホストする

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

NPM パッケージを使用して Application Insights SDK を埋め込む

スニペットやパブリック CDN エンドポイントを使用する代わりに、NPM パッケージを使用して、SDK を独自の JavaScript ファイルの一部として含めることができます。 この SDK は、独自のスクリプト内の別のパッケージになります。

Note

NPM パッケージを使用する場合、コードを分割し、縮小化する助けとして、何らかの JavaScript バンドラーを使用することをお勧めします。

スニペットの場合と同様、独自のスクリプト (SDK NPM パッケージを使用するかどうかに関係なく) も、こちらで説明したのと同じ障害となっている問題の影響を受ける可能性があります。このため、アプリケーション、ユーザー、ご使用のフレームワークに応じて、スニペットのロジックに似たものを実装して、これらの問題を検出および報告できるようにすることをご検討ください。

次のステップ