Устранение неполадок при загрузке пакета SDK для веб-приложений JavaScript

Исключение "Сбой загрузки пакета SDK" создается и отображается фрагментом кода JavaScript (версии 3 или более поздней версии), когда обнаруживается, что не удается загрузить или инициализировать скрипт пакета SDK. Попросту говоря, клиенту конечных пользователей (браузеру) не удалось загрузить пакет SDK для службы Application Insights или выполнить инициализацию с указанной страницы размещения, поэтому данные телеметрии или событий не будут передаваться.

Azure portal browser failure overview

Примечание

Это исключение поддерживается во всех основных браузерах, поддерживающих API fetch() или API XMLHttpRequest. К числу браузеров не имеющих такой поддержки относится IE версии 8 и более ранних версий, поэтому в этих браузерах исключение такого типа не отображается (если в вашей среде не предусмотрена реализация API fetch в варианте полизаполнения).

browser exception detail

Данные в стеке включают в себя основную информацию с URL-адресами, используемыми конечным пользователем.

Имя Описание
<Конечная точка CDN> URL-адрес, который был использован (безрезультатно) для загрузки пакета SDK.
<Ссылка на справку> URL-адрес, ссылающийся на документацию по устранению неполадок (на этой странице).
<URL-адрес узла> Полный URL-адрес страницы, использованной конечным пользователем.
<URL-адрес конечной точки> URL-адрес, который использовался для информирования об исключении. Это значение может быть полезным при определении того, осуществлялся ли доступ к странице размещения из общедоступного Интернета или частного облака.

Наиболее распространенные причины возникновения этого исключения:

  • Кратковременный сбой сетевого подключения.
  • Сбой сети CDN для Application Insights.
  • Не удается инициализировать пакет SDK после загрузки скрипта.
  • Блокирование сети CDN для Application Insights JavaScript.

Кратковременный сбой сетевого подключения является самой распространенной причиной для этого исключения, особенно в сценариях роуминга для мобильных устройств, когда у пользователей периодически пропадают сетевые подключения.

В следующих разделах описывается, как устранять возможные причины этой ошибки.

Примечание

В некоторых действиях по устранению неполадок предполагается, что ваше приложение напрямую управляет тегом <script /> фрагмента кода и его конфигурацией, возвращаемых в виде части HTML-страницы размещения. Если такое управление отсутствует, указанные здесь действия не применимы к вашему сценарию.

Кратковременный сбой сетевого подключения

Если у пользователя возникают кратковременные сбои подключения к сети, то существует небольшое количество решений, и их применение, как правило, приводит к решению проблемы в течение короткого периода времени. Например, если пользователь перезагружает сайт (обновляет страницу), файлы (в конечном итоге) будут загружены и кэшированы локально до выпуска обновленной версии.

Примечание

Если это исключение возникает постоянно и для многих пользователей (что диагностируется по быстрому и устойчивому уровню информирования об этом исключении) вместе со снижением нормальных показателей телеметрии клиентов, то кратковременные проблемы с сетевым подключением скорее всего, не являются действительной причиной проблем, и следует продолжить диагностику в отношении других известных возможных проблем.

В такой ситуации маловероятно, что размещение пакета SDK в вашей сети CDN будет влиять на появление или уменьшение случаев возникновения этого исключения, так как в вашей сети CDN будет наблюдаться такая же проблема.

То же самое справедливо и при использовании пакета SDK через решение "Пакеты NPM". Однако с точки зрения конечных пользователей, при возникновении этой проблемы приложение не удается загрузить или инициализировать (а не только пакет SDK для телеметрии, который не отображается визуально), поэтому они, скорее всего, будут обновлять сайт до тех пор, пока не произойдет полная загрузка.

Вы также можете попытаться использовать пакеты NPM для внедрения пакета SDK Application Insights.

Чтобы свести к минимуму кратковременные сбои сетевого подключения, мы реализовали заголовки Cache-Control для всех файлов CDN, так что после того, как браузер конечного пользователя загрузит текущую версию пакета SDK, этот пакет не нужно будет загружать повторно, и браузер будет использовать ранее полученную копию (см. раздел как работает кэширование). Если проверка кэширования завершается ошибкой или выйдет новый выпуск пакета, то браузеру конечного пользователя нужно будет загрузить обновленную версию. Поэтому в сценариях со сбоем проверки или с временным всплеском нагрузки, когда новый выпуск предоставляется в общий доступ (развертывается в CDN), может наблюдаться фоновый уровень "шума" .

Сбой сети CDN для Application Insights

Вы можете удостовериться в сбое сети CDN для Application Insights, попытавшись получить доступ к конечной точке CDN непосредственно из браузера (например, https://js.monitor.azure.com/scripts/b/ai.2.min.js) в расположении, отличном от расположения пользователя, возможно с вашего собственного компьютера для разработки (если ваша организация не заблокировала этот домен).

Если вы убедитесь в наличии сбоя, можно создать новый запрос в службу поддержки.

Не удается инициализировать пакет SDK после загрузки скрипта

Если не удается инициализировать пакет SDK, это означает, что <скрипт / > успешно загружен из CDN, но во время инициализации происходит сбой. Это может быть вызвано отсутствием необходимых зависимостей или их недопустимостью, или какой-либо разновидностью исключения JavaScript.

В первую очередь нужно проверить, что пакет SDK был успешно загружен, если же скрипт НЕ был загружен, тогда рассматриваемый сценарий не является причиной возникновения ошибки при загрузке пакета SDK.

Быстрая проверка: используя браузер, поддерживающий инструменты разработчика (F12), проверьте на вкладке "Сеть", что скрипт, определенный в конфигурации фрагмента кода src, был загружен с кодом отклика 200 (успешно) или 304 (без изменений). Для просмотра сетевого трафика можно также использовать такой инструмент, как Fiddler.

В следующих разделах приводятся различные варианты создания отчетов, поэтому рекомендуется либо создать запрос в службу поддержки, либо сообщить об ошибке на GitHub.

Основные правила создания отчетов:

  • Если эта ошибка возникает только у небольшого количества пользователей и при использовании конкретных версий браузера или только их части (см. подробные сведения о регистрируемом исключении), тогда скорее всего эта проблема относится только к конечному пользователю или рабочей среде, и вам, вероятно, потребуется предоставить дополнительные реализации polyfill в вашем приложении. В таком случае вам необходимо сообщить о проблеме на GitHub.
  • Если эта проблема затрагивает все приложение и всех пользователей, возможно, она относится к определенному выпуску, поэтому следует создать новый запрос в службу поддержки.

Исключения JavaScript

Сначала можно проверить наличие исключений для JavaScript. Используя браузер, поддерживающий средства разработчика (F12), загрузите страницу и проверьте, не возникли ли какие-либо исключения.

Если в скрипте пакета SDK регистрируются исключения (например ai.2.min.js), это может означать, что конфигурация, переданная в пакет SDK, содержит непредусмотренную настройку или наоборот в ней отсутствует необходимая настройка, или же в CDN развернут сбойный выпуск.

Чтобы проверить конфигурацию, приводящую к ошибкам, измените конфигурацию, передаваемую во фрагмент кода (если это еще не сделано) так, чтобы она включала в себя только ключ инструментирования в виде строкового значения.

Примечание

Поддержка приема ключей инструментирования будет завершена 31 марта 31, 2025 г. Прием ключей инструментирования будет и дальше осуществляться, но мы больше не будем предоставлять обновления или поддержку для этой функции. Перейдите на строки подключения, чтобы использовать новые возможности.

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

Если при использовании минимальной конфигурации по-прежнему наблюдается исключение JavaScript в скрипте пакета SDK, создайте новый запрос в службу поддержки, так как в этой ситуации потребуется откат неисправной сборки, вследствие того, что проблема, вероятно, вызывается новой развернутой версией.

Если исключение исчезнет, то, скорее всего, проблема была обусловлена несоответствием типов или непредусмотренным значением. Начните добавлять параметры в конфигурацию по одному и выполняйте проверку, пока это исключение не возникнет снова. Затем проверьте документацию для элемента, вызвавшего ошибку. Если документация не прояснит рассматриваемую проблему или вам потребуется помощь, сообщите о проблеме на GitHub.

Если конфигурация была уже давно развернута и функционировала нормально, а сообщения об этом исключении только начали появляться, это может означать, что проблема вызвана новой развернутой версией. Нужно проверить, влияет ли эта проблема только на небольшое число пользователей или браузеров, и либо сообщить о проблеме на GitHub, либо создать новый запрос в службу поддержки.

Включение отладки в консоли

При условии, что исключения больше не возникают, можно выполнить следующий шаг и включить отладку в консоли путем добавления в конфигурацию параметра loggingLevelConsole, при этом все ошибки инициализации и предупреждения будут отправляться в консоль браузера (которая обычно доступна через инструменты разработчика (F12)). Все сообщения об ошибках обычно понятны без дополнительных пояснений, и если вам потребуется дополнительная помощь, сообщите о проблеме на GitHub.

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

Примечание

Во время инициализации пакет SDK выполняет некоторые базовые проверки по удовлетворению известных основных зависимостей. Если эти зависимости не предоставляются текущей рабочей средой, сообщения об ошибках будут отображаться в консоли, но только в том случае, если значение loggingLevelConsole больше нуля.

Если инициализация по-прежнему не удается, попробуйте включить в конфигурации параметр enableDebug. Это приведет к тому, что все внутренние ошибки будут выдаваться как исключение (что приведет к потере данных телеметрии). Так как этот параметр предназначен только для разработчиков, будет отображаться большое количество информации об исключениях при выполнении некоторых внутренних проверок, и придется проверить каждое исключение, чтобы определить причину сбоя пакета SDK. Используйте не сокращенную версию скрипта (обратите внимание на расширение ниже: .js, а не .min.js); в противном случае информация об исключениях будет недоступна для чтения.

Предупреждение

Этот параметр предназначен только для разработчиков и никогда не должен включаться на уровне всей производственной среды, так как данные телеметрии будут недоступными.

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

Если эта рекомендация также не приводит к получению ценных сведений, следует сообщить о проблеме на GitHub, указав подробности и приведя пример сайта, если таковой имеется. Чтобы облегчить определение причины проблемы, включите сведения о версии браузера, операционной системе и платформе JS.

Блокирование сети CDN для Application Insights JavaScript

Блокирование сети CDN возможно, если конечная точка сети CDN пакета SDK для Application Insights JavaScript указана и (или) определена как ненадежная. В этом случае эта конечная точка добавляется в общедоступный список блокировки, и пользователи таких списков будут полностью блокировать доступ к ней.

Для устранения этой проблемы владельцу конечной точки CDN необходимо обратиться в инстанцию, формирующую список блокировки и пометившую эту конечную точку как ненадежную, с запросом об удалении ее из соответствующего списка.

Проверьте, определена ли конечная точка CDN как ненадежная.

В зависимости от частоты обновления локальных копий этих списков в приложениях, брандмауэрах или в рабочих средах на эту операцию может потребоваться значительное количество времени и (или) непосредственное участие конечных пользователей или корпоративных ИТ-отделов для принудительного выполнения этого обновления или предоставления явного разрешения на использование конечных точек CDN с целью устранения рассматриваемой проблемы.

Если конечная точка CDN определена как ненадежная, создайте запрос в службу поддержки, чтобы гарантировать скорейшее решение этой проблемы.

Блокирование сети CDN для Application Insights JavaScript (на уровне конечного пользователя — блокирование браузером, установкой средств блокировки, персональным брандмауэром)

Проверьте конечных пользователей на наличие у них:

  • Установленных подключаемых модулей браузера (обычно это разные типы блокировщиков рекламы, вредоносных программ или всплывающих окон).
  • Заблокированных (или запрещенных) конечных точек CDN для Application Insights на уровне браузера или прокси-сервера.
  • Настроенных правил брандмауэра, вызывающих блокировку домена CDN для пакета SDK (или записи DNS, которую не удается разрешить).

Если у пользователей реализованы какие-либо из вышеперечисленных вариантов, необходимо провести с ними соответствующую работу (или предоставить документацию), чтобы разрешить доступ для нужных конечных точек CDN.

Возможно, что в установленном подключаемом модуле используется общедоступный список блокировки. Если это не так, то скорее всего имеется другое настроенное вручную решение или используется список блокировки из частного домена.

Добавление исключений для конечных точек CDN

Необходимо провести соответствующую работу с конечными пользователями или предоставить им документацию с информацией о том, что они должны разрешать загрузку скриптов с конечных точек CDN для Application Insights, включив эти конечные точки в список исключений для подключаемого модуля или для правил брандмауэра (зависит от рабочей среды пользователя).

Ниже приведен пример настройки браузера Chrome для разрешения или блокировки доступа к веб-сайтам.

Блокирование сети CDN для Application Insights (с помощью корпоративного брандмауэра)

Если конечные пользователи находятся в корпоративной сети, то скорее всего некая разновидность системы фильтрации в Интернете реализована ИТ-отделом и осуществляется с помощью брандмауэра. В этом случае нужно обратиться в ИТ-отдел, чтобы предоставить конечным пользователям необходимые правила доступа.

Добавление исключений для конечных точек CDN на корпоративном уровне

Эта ситуация аналогична случаю с добавлением исключений для конечных пользователей, но здесь нужно провести работу с корпоративным ИТ-отделом, чтобы была выполнена настройка в отношении конечных точек CDN для Application Insights с разрешением загрузки путем включения этих конечных точек в списки, разрешающие их использование, или удаления этих конечных точек из списков блокировки в любых доменных службах.

Предупреждение

Если корпоративный пользователь работает на основе частного облака и не может реализовать никакого исключения для предоставления внутренним пользователям общего доступа к конечным точкам CDN, необходимо использовать пакеты NPM для Application Insights или разместить пакет SDK для Application Insights в собственной сети CDN.

Дополнительные способы устранения неполадок для заблокированной сети CDN

Примечание

Если пользователи работают на основе частного облака без доступа к сети Интернет общего пользования, вам нужно разместить пакет SDK в собственной сети CDN или использовать пакеты NPM.

Размещение пакета SDK в собственной сети CDN

Вместо того, чтобы конечным пользователям нужно было загружать пакет SDK для Application Insights из общедоступной сети CDN, можно разместить пакет SDK для Application Insights на конечной точке в собственной сети CDN. Рекомендуется использовать определенную версию (ai.2.#.#.min.js), чтобы упростить идентификацию используемой версии. Также нужно выполнять регулярное обновление до текущей версии (ai.2.min.js), чтобы использовать исправления ошибок и новые функции, которые становятся доступными.

Использование пакетов NPM с целью внедрения пакета SDK для Application Insights

Вместо фрагмента кода и общедоступных конечных точек сети CDN можно использовать пакеты NPM, чтобы включить пакет SDK в состав собственных файлов JavaScript. Таким образом пакет SDK станет просто одним из пакетов в ваших скриптах.

Примечание

При использовании пакетов NPM рекомендуется также использовать какое-либо средство увязки в пакеты JavaScript для облегчения разделения кода и минификации.

Как и в случае с фрагментом кода, также возможно, что работа ваших собственных скриптов (с использованием пакетов NPM для SDK или без их использования) может быть сопряжена с теми же проблемами блокировки, которые перечислены в этой статье, поэтому в зависимости от приложения, пользователей и вашей платформы может потребоваться реализация некоторого логического алгоритма во фрагменте кода для обнаружения рассматриваемых здесь проблем и информирования о них.

Дальнейшие действия