Устранение неполадок пакета SDK JavaScript для Application Insights

  • Статья

В этой статье рассматриваются способы устранения различных проблем, связанных с пакетом SDK Для JavaScript для Application Insights. Темы в этой статье включают сбой загрузки пакета SDK для веб-приложений JavaScript и поддержку исходной карты для приложений JavaScript.

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

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

Симптомы

В элементе <head> отслеживаемой веб-страницы фрагмент Кода JavaScript (версия 3 или более поздняя версия) создает следующее исключение, когда обнаруживается, что скрипт пакета SDK не скачал или не инициализировал:

Сбой загрузки пакета SDK: не удалось загрузить скрипт пакета SDK для Application Insights (дополнительные сведения см. в стеке)

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

портал Azure снимок экрана исключения с названием

Примечание.

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

портал Azure снимок экрана: сбой загрузки пакета SDK. Сведения о стеке вызовов, времени события, сообщении, типе исключения и методе сбоя.

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

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

В следующем списке приведены наиболее распространенные причины возникновения этого исключения:

  • Периодический сбой сетевого подключения

  • Сбой сети доставки содержимого (CDN) Application Insights

  • Сбой инициализации пакета SDK после загрузки скрипта

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

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

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

Примечание.

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

Причина 1. Периодический сбой сетевого подключения

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

Решение 1a. Скачивание обновленной версии пакета SDK

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

Решение 1b. Использование пакетов npm для внедрения пакета SDK вместе с приложением в один пакет

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

Примечание.

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

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

Вы можете попытаться использовать пакеты npm для внедрения пакета SDK Для Application Insights вместе с отслеживаемой приложением в один пакет. Хотя в этом сценарии по-прежнему может возникать периодический сбой, объединенный пакет предоставляет реальные шансы устранить проблему.

Причина 2. Сбой сети CDN в Application Insights

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

Решение 2. Создание запроса в службу поддержки

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

Причина 3. Пакет SDK не инициализировался после загрузки скрипта

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

Решение 3. Проверка успешной загрузки пакета SDK или исключений JavaScript или включение отладки браузера

Шаг 1. Проверка успешной загрузки пакета SDK

Проверьте, успешно ли скачан пакет SDK. Если скачивание скрипта не произошло, этот сценарий не является причиной сбоя загрузки пакета SDK. Используйте браузер, поддерживающий средства разработчика. Выберите F12, чтобы просмотреть средства разработчика, а затем перейдите на вкладку Сеть . Убедитесь, что скрипт, определенный в конфигурации фрагмента кода src , скачан. Для этого проверка код 200 ответа (успешно) или 304 (не изменен). Чтобы проверить сетевой трафик, можно также использовать средство веб-отладки, например Fiddler.

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

Сценарий Причина Действие
Проблема затрагивает только несколько пользователей и определенную версию браузера или подмножество версий браузера. (Проверьте сведения об обнаруженном исключении.) Эта проблема, скорее всего, возникает только в том случае, если определенные пользователи или среды требуют, чтобы ваше приложение предоставлял дополнительные polyfill реализации. Отправьте файл о проблеме на GitHub.
Эта проблема затрагивает все приложение и всех пользователей. Это проблема, связанная с выпуском. Создайте запрос в службу поддержки.

Если пакет SDK успешно скачан, ознакомьтесь со следующими разделами, чтобы устранить проблему инициализации пакета SDK.

Шаг 2. Проверка наличия исключений JavaScript

Проверьте наличие исключений JavaScript. Используйте браузер, поддерживающий средства разработчика. Выберите F12, чтобы просмотреть средства разработчика, загрузить страницу, а затем проверка, возникли ли исключения. Вызывает ли скрипт ПАКЕТА SDK (например, вai.2.min.js) исключения? В этом случае произошел один из следующих сценариев:

  • Конфигурация, переданная в пакет SDK, содержит непредвиденную конфигурацию.

  • В конфигурации, передаваемой в пакет SDK, отсутствует необходимая конфигурация.

  • Неисправный выпуск был развернут в сети CDN.

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

Примечание.

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

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

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

Если исключение исчезнет, возможно, проблема возникает из-за несоответствия типов или непредвиденного значения. Начните устранение неполадок, восстанавливая параметры конфигурации по одному, и тестируйте после каждого изменения, пока не возникнет исключение снова. Затем проверка документацию по элементу, который вызывает проблему. Если документация неясна или вам нужна помощь, отправьте запрос на 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 выполняет некоторые основные проверки на наличие известных основных зависимостей. Если текущая среда выполнения не предоставляет эти проверки, среда выполнения сообщает о сбоях в виде предупреждающих сообщений в консоль (но только в том случае, если 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. Блокировка сети CDN JavaScript для Application Insights

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

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

Проверьте следующие веб-сайты безопасности в Интернете, чтобы узнать, идентифицируют ли они конечную точку CDN как небезопасную:

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

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

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

Причина 4a: блокировка пользователя (браузер, установленный блокировщик или личный брандмауэр)

Проверьте, выполнили ли пользователи какие-либо из следующих действий по настройке:

  • Установленный подключаемый модуль браузера (обычно в виде рекламы, вредоносных программ или блокирования всплывающих окон)

  • Заблокированы или запрещены конечные точки CDN Application Insights в браузере или прокси-сервере

  • Настроено правило брандмауэра, которое вызывает блокировку домена CDN для пакета SDK (или сбой при разрешении записи DNS)

Решение 4a. Добавление исключений из списка блокировок для конечных точек CDN

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

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

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

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

Причина 4b: блокировка корпоративного брандмауэра

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

Решение 4b1. Добавление исключений для конечных точек CDN для корпораций

Важно!

Используют ли ваши пользователи частное облако и у них нет доступа к общедоступному Интернету? В этом случае необходимо либо использовать пакеты npm Application Insights для внедрения пакета SDK, либо разместить пакет SDK для Application Insights в собственной сети CDN.

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

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

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

Решение 4b3. Использование пакетов npm для внедрения пакета SDK Для Application Insights

Вместо использования фрагмента кода и добавления общедоступных конечных точек CDN можно использовать пакеты npm , чтобы включить пакет SDK как часть собственных файлов JavaScript. Пакет SDK становится еще одним пакетом в ваших скриптах. Дополнительные сведения см. в разделе настройка на основе npm на странице GitHub пакета SDK для JavaScript для Application Insights.

Примечание.

При использовании пакетов npm рекомендуется также использовать некоторую форму пакета JavaScript , которая помогает выполнять разделение и минификацию кода.

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

Устранение неполадок с поддержкой сопоставления источника для приложений JavaScript

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

Проблема Описание
Обязательные параметры управления доступом на основе ролей Azure (Azure RBAC) в контейнере BLOB-объектов Любому пользователю на портале, который использует эту функцию, должна быть назначена по крайней мере роль читателя данных BLOB-объектов хранилища для контейнера BLOB-объектов. Эту роль необходимо назначить всем, кто хочет использовать исходные карты с помощью этой функции. В зависимости от того, как был создан контейнер, возможно, эта роль не была назначена автоматически вам или вашей команде.
Исходная карта не найдена Чтобы устранить эту проблему, выполните следующие действия.
  1. Убедитесь, что соответствующая карта источника отправлена в правильный контейнер BLOB-объектов.
  2. Убедитесь, что исходный файл карты получает свое имя из файла JavaScript, с которым он сопоставляется, и что он имеет расширение MAP-файла . Например, /static/js/main.4e2ca5fa.chunk.js выполняет поиск большого двоичного объекта с именемmain.4e2ca5fa.chunk.js.map.
  3. Проверьте консоль браузера, чтобы узнать, регистрирует ли она какие-либо ошибки. Включите эти выходные данные в любой запрос в службу поддержки.

Исправлено предупреждение "Щелкните строки событий без значения parentId"

При использовании Application Insights и подключаемого модуля автоматического сбора click Analytics в приложении в книге application Insights может появиться следующее предупреждение телеметрии: "Щелкните строки событий без значения parentId".

Причина

Эта проблема может возникнуть, если родительский идентификатор не указан в родительском элементе HTML. Это условие приводит к активации события во всех его родительских элементах.

Решение

Чтобы устранить эту проблему, добавьте data-parentid атрибут или data-<customPrefix>-parentid в родительский элемент HTML. Ниже приведен пример HTML-кода:

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

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

Заявление об отказе от ответственности за сведения о продуктах сторонних производителей

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

Свяжитесь с нами для получения помощи

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