Memecahkan masalah kegagalan pemuatan SDK untuk aplikasi web JavaScript

Pengecualian kegagalan pemuatan SDK dibuat dan dilaporkan oleh cuplikan JavaScript (v3 atau lebih baru) ketika mendeteksi bahwa skrip SDK gagal diunduh atau diinisialisasi. Secara sederhana, klien pengguna akhir (browser) Anda tidak dapat mengunduh SDK Application Insights, atau menginisialisasi dari halaman hosting yang diidentifikasi dan oleh karena itu tidak ada telemetri atau peristiwa yang akan dilaporkan.

Azure portal browser failure overview

Catatan

Pengecualian ini didukung di semua browser utama yang mendukung API fetch() atau XMLHttpRequest. Ini tidak termasuk IE 8 ke bawah, sehingga Anda tidak akan mendapatkan jenis pengecualian ini dilaporkan dari browser tersebut (kecuali jika lingkungan Anda menyertakan polyfill pengambilan).

browser exception detail

Detail tumpukan mencakup informasi dasar dengan URL yang digunakan oleh pengguna akhir.

Nama Deskripsi
<Titik Akhir CDN> URL yang digunakan (dan gagal) untuk mengunduh SDK.
<Tautan Bantuan> URL yang ditautkan ke dokumentasi pemecahan masalah (halaman ini).
<URL Host> URL lengkap halaman yang digunakan pengguna akhir.
<URL Titik Akhir> URL yang digunakan untuk melaporkan pengecualian, nilai ini mungkin berguna dalam mengidentifikasi apakah halaman hosting diakses dari internet publik atau cloud pribadi.

Alasan paling umum untuk pengecualian ini terjadi:

  • Kegagalan konektivitas jaringan terputus-terputus.
  • Terputusnya CDN Application Insights.
  • SDK gagal diinisialisasi setelah memuat skrip.
  • CDN JavaScript Application Insights telah diblokir.

Kegagalan konektivitas jaringan terputus-terputus adalah alasan paling umum untuk pengecualian ini, terutama dalam skenario roaming seluler di mana pengguna kehilangan konektivitas jaringan sewaktu-waktu.

Bagian berikut ini akan menjelaskan cara memecahkan masalah setiap kemungkinan akar masalah kesalahan ini.

Catatan

Beberapa langkah pemecahan masalah mengasumsikan bahwa aplikasi Anda memiliki kontrol langsung terhadap tag <script /> Cuplikan dan konfigurasinya yang dikembalikan sebagai bagian dari halaman HTML hosting. Jika tidak, maka langkah-langkah yang diidentifikasi tidak akan berlaku untuk skenario Anda.

Kegagalan konektivitas jaringan terputus-terputus

Jika pengguna mengalami kegagalan konektivitas jaringan terputus-terputus, maka ada lebih sedikit solusi yang mungkin dan umumnya akan menyelesaikan sendiri dalam waktu singkat. Misalnya, jika pengguna memuat ulang situs Anda (merefresh halaman), file tersebut (akhirnya) akan diunduh dan di-cache secara lokal hingga versi yang diperbarui dirilis.

Catatan

Jika pengecualian ini terus-menerus dan terjadi di banyak pengguna Anda (didiagnosis oleh tingkat yang cepat dan berkelanjutan dari pengecualian ini dilaporkan) bersama dengan pengurangan telemetri klien normal, maka masalah konektivitas jaringan terputus-terputus mungkin bukan menjadi penyebab sebenarnya dari masalah dan Anda harus terus mendiagnosis dengan masalah lain yang diketahui mungkin.

Dengan situasi ini menghosting SDK pada CDN Anda sendiri tidak mungkin memberikan atau mengurangi terjadinya pengecualian ini, karena CDN Anda sendiri akan terpengaruh oleh masalah yang sama.

Hal yang sama juga berlaku saat menggunakan SDK melalui solusi paket NPM. Namun, dari perspektif pengguna akhir, ketika ini terjadi seluruh aplikasi Anda gagal dimuat/diinisialisasi (bukan hanya SDK telemetri - yang tidak mereka lihat secara visual), sehingga mereka kemungkinan besar akan me-refresh situs Anda sampai dimuat sepenuhnya.

Anda juga dapat mencoba menggunakan paket NPM untuk menyematkan SDK Application Insights.

Untuk meminimalkan kegagalan konektivitas jaringan terputus-terputus, kami telah menerapkan header Cache-Control pada semua file CDN sehingga setelah browser pengguna akhir mengunduh versi SDK saat ini, tidak perlu mengunduh lagi dan browser akan menggunakan kembali salinan yang diperoleh sebelumnya (lihat cara kerja penembolokan). Jika pemeriksaan penembolokan gagal atau telah ada rilis baru, maka browser pengguna akhir Anda akan perlu mengunduh versi yang diperbarui. Jadi Anda mungkin melihat tingkat latar belakang "kebisingan" dalam skenario kegagalan pemeriksaan atau lonjakan sementara ketika rilis baru terjadi dan tersedia secara umum (disebarkan ke CDN).

Terputusnya CDN Application Insights

Anda dapat mengonfirmasi apakah ada gangguan CDN Application Insights dengan mencoba mengakses titik akhir CDN secara langsung dari browser (misalnya, https://js.monitor.azure.com/scripts/b/ai.2.min.js) dari lokasi yang berbeda dengan pengguna akhir Anda, mungkin dari mesin pengembangan Anda sendiri (dengan asumsi bahwa organisasi Anda belum memblokir domain ini).

Jika dikonfirmasi adanya gangguan, Anda dapat membuat tiket dukungan baru.

SDK gagal diinisialisasi setelah memuat skrip

Jika SDK gagal diinisialisasi, <script /> berhasil diunduh dari CDN tetapi gagal selama inisialisasi. Hal ini mungkin karena dependensi tidak ada atau tidak valid atau beberapa bentuk pengecualian JavaScript.

Hal pertama yang perlu diperiksa adalah apakah SDK berhasil diunduh, jika skrip TIDAK diunduh maka skenario ini bukan penyebab pengecualian kegagalan pemuatan SDK.

Pemeriksaan cepat: Menggunakan browser yang mendukung alat pengembang (F12), validasi pada tab jaringan yang ditentukan skrip dalam konfigurasi cuplikan src diunduh dengan kode respons 200 (berhasil) atau 304 (tidak diubah). Anda juga dapat menggunakan alat seperti fiddler untuk meninjau lalu lintas jaringan.

Bagian di bawah ini mencakup opsi pelaporan yang berbeda, akan merekomendasikan untuk membuat tiket dukungan atau mengajukan masalah di GitHub.

Aturan pelaporan dasar:

  • Jika masalah ini hanya memengaruhi sejumlah kecil pengguna dan subset atau versi browser tertentu (periksa detail tentang pengecualian yang dilaporkan), maka kemungkinan itu masalah pengguna akhir atau lingkungan saja, yang mungkin akan mengharuskan aplikasi Anda untuk memberikan implementasi polyfill tambahan. Untuk ini, ajukan masalah di GitHub.
  • Jika masalah ini memengaruhi seluruh aplikasi Anda dan semua pengguna Anda terpengaruh, maka itu mungkin masalah terkait rilis dan oleh karena itu Anda harus membuat tiket dukungan baru.

Pengecualian JavaScript

Pertama-tama mari kita periksa pengecualian JavaScript, menggunakan browser yang mendukung alat pengembang (F12), memuat halaman dan meninjau apakah ada pengecualian.

Jika ada pengecualian yang dilaporkan dalam skrip SDK (misalnya ai.2.min.js), maka ini dapat menunjukkan bahwa konfigurasi yang diteruskan ke SDK berisi konfigurasi yang diperlukan yang tidak terduga atau tidak ada atau rilis yang rusak telah disebarkan ke CDN.

Untuk memeriksa konfigurasi yang rusak, ubah konfigurasi yang diteruskan ke cuplikan (jika belum) sehingga hanya menyertakan kunci instrumentasi Anda sebagai nilai string.

Catatan

Pada tanggal 31 Maret 2025, dukungan untuk penyerapan kunci instrumentasi akan berakhir. Penyerapan kunci instrumentasi akan berjalan terus, tetapi kami tidak akan lagi menyediakan pembaruan atau dukungan terhadap fitur tersebut. Transisi ke string koneksi untuk memanfaatkan kemampuan baru.

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

Jika saat menggunakan konfigurasi minimal ini, Anda masih melihat pengecualian JavaScript di skrip SDK, buat tiket dukungan baru karena ini akan mengharuskan build yang rusak untuk digulirkan kembali karena mungkin ada masalah dengan versi yang baru disebarkan.

Jika pengecualian menghilang, maka masalah mungkin disebabkan oleh jenis yang tidak cocok atau nilai yang tidak terduga. Mulai tambahkan opsi konfigurasi Anda kembali satu per satu dan uji sampai pengecualian terjadi lagi. Kemudian periksa dokumentasi untuk item yang menyebabkan masalah. Jika dokumentasi tidak jelas atau Anda membutuhkan bantuan, ajukan masalah di GitHub.

Jika konfigurasi Anda sebelumnya disebarkan dan berfungsi tetapi baru mulai melaporkan pengecualian ini, mungkin ada masalah dengan versi yang baru disebarkan, periksa apakah itu hanya memengaruhi sebagian kecil pengguna/browser Anda dan angkat masalah di GitHub atau buat tiket dukungan baru.

Mengaktifkan debugging konsol

Dengan asumsi tidak ada pengecualian yang diberikan, langkah berikutnya adalah mengaktifkan debugging konsol dengan menambahkan pengaturan loggingLevelConsole ke konfigurasi, ini akan mengirim semua kesalahan inisialisasi dan peringatan ke konsol browser (biasanya tersedia melalui alat pengembang (F12)). Setiap kesalahan yang dilaporkan harus jelas dan jika Anda membutuhkan bantuan lebih lanjut ajukan masalah di GitHub.

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

Catatan

Selama inisialisasi, SDK melakukan beberapa pemeriksaan dasar untuk ketergantungan utama yang diketahui. Jika ini tidak disediakan oleh runtime saat ini, SDK akan melaporkan kegagalan sebagai pesan peringatan ke konsol, tetapi hanya jika loggingLevelConsole lebih besar dari nol.

Jika masih gagal menginisialisasi, coba aktifkan pengaturan konfigurasi enableDebug. Ini akan menyebabkan semua kesalahan internal diberikan sebagai pengecualian (yang akan menyebabkan telemetri hilang). Karena ini pengaturan hanya pengembang mungkin akan menjadi berisik dengan pengecualian yang diberikan sebagai bagian dari beberapa pemeriksaan internal, jadi Anda perlu meninjau setiap pengecualian untuk menentukan masalah mana yang menyebabkan SDK gagal. Gunakan versi skrip yang tidak diperkecil (perhatikan ekstensi di bawah ini adalah ".js" dan bukan ".min.js") jika tidak, pengecualian tidak akan dapat dibaca.

Peringatan

Ini adalah pengaturan hanya pengembang dan TIDAK BOLEH diaktifkan di lingkungan produksi penuh karena Anda akan kehilangan telemetri.

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

Jika ini masih tidak memberikan wawasan apa pun, ajukan masalah di GitHub dengan detail dan situs contoh jika ada. Sertakan detail versi browser, sistem operasi, dan kerangka kerja JS untuk membantu mengidentifikasi masalah.

CDN JavaScript Application Insights telah diblokir

CDN mungkin diblokir jika titik akhir CDN SDK JavaScript Application Insights telah dilaporkan dan/atau diidentifikasi tidak aman. Jika hal ini terjadi, itu akan menyebabkan titik akhir menjadi diblokir secara publik dan konsumen daftar ini akan mulai memblokir semua akses.

Untuk mengatasinya, pemilik titik akhir CDN harus bekerja dengan entitas daftar blokir yang telah menandai titik akhir tersebut sebagai tidak aman sehingga dapat dihapus dari daftar yang relevan.

Periksa apakah titik akhir CDN telah diidentifikasi sebagai tidak aman.

Tergantung pada frekuensi aplikasi, firewall, atau lingkungan memperbarui salinan lokalnya dari daftar ini, mungkin perlu waktu yang cukup lama dan/atau memerlukan intervensi manual oleh pengguna akhir atau departemen IT perusahaan untuk memaksa pembaruan atau secara eksplisit memungkinkan titik akhir CDN untuk menyelesaikan masalah.

Jika titik akhir CDN diidentifikasi tidak aman, buat tiket dukungan untuk memastikan bahwa masalah diselesaikan sesegera mungkin.

CDN JavaScript Application Insights diblokir (oleh pengguna akhir - diblokir oleh browser; pemblokir yang diinstal; firewall pribadi)

Periksa apakah pengguna akhir Anda memiliki:

  • Menginstal plug-in browser (biasanya beberapa jenis pemblokir iklan, malware, atau popup).
  • Memblokir (atau tidak mengizinkan) titik akhir CDN Application Insights di browser atau proksi mereka.
  • Mengonfigurasi aturan firewall yang menyebabkan domain CDN untuk SDK diblokir (atau entri DNS tidak terselesaikan).

Jika mereka telah mengonfigurasi salah satu opsi ini, Anda harus bekerja dengan mereka (atau memberikan dokumentasi) untuk mengizinkan titik akhir CDN.

Ada kemungkinan bahwa plug-in yang telah mereka instal menggunakan daftar blokir publik. Jika bukan itu masalahnya, maka kemungkinan besar beberapa solusi lain yang dikonfigurasi secara manual atau menggunakan daftar blokir domain pribadi.

Menambahkan pengecualian untuk titik akhir CDN

Bekerja dengan pengguna akhir Anda atau berikan dokumentasi yang memberi tahu mereka bahwa mereka harus mengizinkan skrip dari titik akhir CDN Application Insights diunduh dengan menyertakannya dalam daftar pengecualian aturan plug-in atau firewall browser mereka (akan bervariasi berdasarkan lingkungan pengguna akhir).

Berikut adalah contoh cara mengonfigurasi Chrome untuk mengizinkan atau memblokir akses ke situs web.

CDN Application Insights diblokir (oleh firewall perusahaan)

Jika pengguna akhir Anda berada di jaringan perusahaan, maka kemungkinan besar solusi firewall dan departemen IT mereka telah menerapkan suatu sistem pemfilteran internet. Dalam hal ini, Anda harus bekerja dengan mereka untuk mengizinkan aturan yang diperlukan untuk pengguna akhir Anda.

Menambahkan pengecualian untuk titik akhir CDN untuk perusahaan

Ini serupa dengan menambahkan pengecualian untuk pengguna akhir, tetapi Anda harus bekerja dengan departemen IT perusahaan untuk meminta mereka mengonfigurasi titik akhir CDN Application Insights untuk diunduh dengan menyertakan (atau menghapus) mereka di setiap layanan daftar blokir atau daftar izin domain.

Peringatan

Jika pengguna perusahaan Anda menggunakan cloud privat dan tidak dapat mengaktifkan segala bentuk pengecualian untuk memberi pengguna internal mereka akses publik untuk titik akhir CDN maka Anda harus menggunakan paket NPM Application Insights atau menghosting SDK Application Insights di CDN Anda sendiri.

Pemecahan masalah tambahan untuk CDN yang diblokir

Catatan

Jika pengguna Anda menggunakan cloud privat dan tidak memiliki akses ke internet publik, Anda harus meng-host SDK di CDN Anda sendiri atau menggunakan paket NPM.

Meng-host SDK di CDN Anda sendiri

Daripada pengguna akhir Anda mengunduh SDK Application Insights dari CDN publik, Anda dapat meng-host SDK Application Insights dari titik akhir CDN Anda sendiri. Disarankan agar Anda menggunakan versi tertentu (ai.2.#.#.min.js) sehingga lebih mudah untuk mengidentifikasi versi mana yang Anda gunakan. Perbarui juga secara teratur ke versi saat ini (ai.2.min.js) sehingga Anda dapat memanfaatkan perbaikan bug dan fitur baru yang tersedia.

Menggunakan paket NPM untuk menyematkan SDK Application Insight

Daripada menggunakan cuplikan dan titik akhir CDN publik, Anda dapat menggunakan paket NPM untuk menyertakan SDK sebagai bagian dari file JavaScript Anda sendiri. SDK akan menjadi paket lain dalam skrip Anda sendiri.

Catatan

Disarankan agar saat menggunakan paket NPM Anda juga harus menggunakan beberapa bentuk bundler JavaScript untuk membantu pemisahan kode dan minifikasi.

Seperti halnya cuplikan, ada kemungkinan juga bahwa skrip Anda sendiri (dengan atau tanpa menggunakan paket NPM SDK) dapat dipengaruhi oleh masalah pemblokiran yang sama yang tercantum di sini, jadi tergantung pada aplikasi, pengguna, dan kerangka kerja, Anda mungkin ingin mempertimbangkan untuk menerapkan sesuatu yang mirip dengan logika dalam cuplikan untuk mendeteksi dan melaporkan masalah ini.

Langkah berikutnya