Solução de problemas do SDK do JavaScript do Application Insights
Este artigo discute como solucionar vários problemas que envolvem o SDK do JavaScript do Application Insights. Os assuntos neste artigo incluem falha de carregamento do SDK para aplicativos Web JavaScript e suporte ao mapa de origem para aplicativos JavaScript.
Solucionar problemas de falha de carregamento do SDK para aplicativos Web JavaScript
As seções a seguir discutem os sintomas, as causas e as soluções para um cenário específico de falha de carregamento do SDK para aplicativos Web JavaScript.
Sintomas
<No elemento head> da página da Web que você está monitorando, o snippet JavaScript (versão 3 ou posterior) cria e relata a seguinte exceção quando detecta que o script do SDK não foi baixado ou inicializado:
Falha de CARREGAMENTO do SDK: Falha ao carregar o script do SDK do Application Insights (consulte a pilha para obter detalhes)
Essa mensagem indica que o cliente do usuário (navegador) não pode baixar o SDK do Application Insights ou inicializar na página de hospedagem identificada. Portanto, você não vê nenhuma telemetria ou eventos.
Observação
Essa exceção é suportada em todos os principais navegadores que suportam a API ou XMLHttpRequest.fetch() Essas versões do navegador excluem o Microsoft Internet Explorer 8 e versões anteriores. Portanto, esses navegadores não relatarão esse tipo de exceção, a menos que seu ambiente inclua um polyfill de busca.
Os detalhes da pilha incluem as informações básicas sobre os URLs que estão sendo usados pelo usuário.
| Nome | Descrição |
|---|---|
| <Ponto de Extremidade da CDN> | A URL que foi usada (e falhou) para baixar o SDK. |
| <Link de ajuda> | Uma URL que aponta para a documentação de solução de problemas (esta página). |
| <URL do host> | A URL completa da página que o usuário estava usando. |
| <URL do Ponto de Extremidade> | A URL que foi usada para relatar a exceção. Esse valor pode ajudar a identificar se a Internet pública ou uma nuvem privada acessou a página de hospedagem. |
A lista a seguir contém os motivos mais comuns pelos quais essa exceção ocorre:
Falha de conectividade de rede intermitente
Interrupção da CDN (Rede de Distribuição de Conteúdo) do Application Insights
Falha na inicialização do SDK após carregar o script
Bloqueio da CDN JavaScript do Application Insights
A falha intermitente de conectividade de rede é o motivo mais comum para essa exceção, especialmente em cenários de roaming móvel.
As seções a seguir discutem como solucionar cada possível causa raiz desse erro.
Observação
Algumas dessas etapas pressupõem que seu aplicativo tenha controle direto do script/>tag do Snippet <e sua configuração retornada como parte da página HTML de hospedagem. Se essas condições não se aplicarem ao seu cenário, essas etapas também não se aplicarão.
Causa 1: falha intermitente de conectividade de rede
Se o usuário tiver falhas intermitentes de conectividade de rede, haverá menos soluções possíveis do que para outras causas. No entanto, essa falha geralmente se resolve rapidamente. Por exemplo, se o usuário atualizar a página para recarregar seu site, os arquivos serão baixados e armazenados em cache localmente até o lançamento de uma versão atualizada.
Solução 1a: baixar uma versão atualizada do SDK
Para minimizar a falha intermitente de conectividade de rede, implementamos Cache-Control cabeçalhos em todos os arquivos CDN. Depois que o navegador do usuário baixa a versão atual do SDK, ele não precisa baixá-lo novamente porque reutiliza a cópia obtida anteriormente. (Veja como funciona o cache.) Se a verificação de cache falhar ou houver uma nova versão disponível, o navegador do usuário precisará baixar a versão atualizada. Portanto, você pode ver um nível de "ruído" em segundo plano no cenário de falha de verificação. Ou você pode ver um pico temporário quando uma nova versão ocorre e se torna disponível para o público geral (implantada na CDN).
Solução 1b: usar pacotes npm para inserir o SDK junto com o aplicativo em um único pacote
A exceção de falha de carga do SDK é persistente e ocorre para muitos usuários junto com uma redução na telemetria normal do cliente? Nesse caso, problemas intermitentes de conectividade de rede provavelmente não são a verdadeira causa do problema e você deve explorar outras causas possíveis.
Observação
Uma indicação comum de que essa falha ocorre para vários usuários é que a exceção é relatada em um nível rápido e sustentado.
Nessa situação, é improvável que a hospedagem do SDK em sua própria CDN forneça ou reduza as ocorrências dessa exceção. O mesmo problema afeta sua própria CDN e também ocorre se você usar o SDK por meio de uma solução de pacote npm. A falha do último cenário ocorre especialmente se o Application Insights estiver incluído em um pacote diferente daquele do aplicativo que está sendo monitorado, pois a falha é garantida em pelo menos um desses pacotes. Do ponto de vista do usuário, quando essa exceção ocorre, todo o aplicativo falha ao carregar ou inicializar, não apenas o SDK de telemetria (que os usuários não veem). Portanto, os usuários provavelmente continuarão atualizando seu site até que ele seja carregado completamente.
Você pode tentar usar pacotes npm para inserir o SDK do Application Insights junto com o aplicativo monitorado em um único pacote. Embora uma falha de intermitência ainda possa ocorrer nesse cenário, um pacote combinado oferece uma chance real de corrigir o problema.
Causa 2: interrupção da CDN do Application Insights
Para verificar se há uma interrupção da CDN do Application Insights, tente acessar o ponto de extremidade da CDN diretamente do navegador de um local diferente daquele dos usuários. Por exemplo, você pode tentar acessar https://js.monitor.azure.com/scripts/b/ai.2.min.js de seu próprio computador de desenvolvimento. (Isso pressupõe que sua organização não bloqueou esse domínio.)
Solução 2: criar um tíquete de suporte
Se você verificar que existe uma interrupção, poderá criar um novo tíquete de suporte.
Causa 3: o SDK não inicializou após carregar o script
Se o SDK não for inicializado, o <script /> ainda será baixado com êxito da CDN, mas falhará durante a inicialização. Essa falha ocorre devido a dependências ausentes ou inválidas ou devido a alguma forma de exceção de JavaScript.
Solução 3: verifique se há um download bem-sucedido do SDK ou exceções de JavaScript ou habilite a depuração do navegador
Etapa 1: verificar se há um download bem-sucedido do SDK
Verifique se o SDK foi baixado com êxito. Se nenhum download de script ocorreu, esse cenário não será a causa da exceção de falha de carregamento do SDK. Use um navegador que ofereça suporte a ferramentas de desenvolvedor. Selecione F12 para exibir as ferramentas de desenvolvedor e, em seguida, selecione a guia Rede. Verifique se o script definido na configuração do snippet src foi baixado. Para fazer isso, verifique o código 200 de resposta (sucesso) ou 304 (não alterado). Para examinar o tráfego de rede, você também pode usar uma ferramenta de depuração da Web, como o Fiddler.
Se o download do SDK não tiver sido bem-sucedido, examine a tabela a seguir para entender as diferentes opções de relatório.
| Cenário | Motivo | Action |
|---|---|---|
| O problema afeta apenas alguns usuários e uma versão específica do navegador ou um subconjunto de versões do navegador. (Verifique os detalhes sobre a exceção relatada.) | O problema provavelmente só ocorrerá se usuários ou ambientes específicos exigirem que seu aplicativo forneça implementações extras polyfill . |
Registre um problema no GitHub. |
| O problema afeta todo o aplicativo e todos os usuários. | É um problema relacionado ao lançamento. | Crie um novo tíquete de suporte. |
Se o SDK foi baixado com êxito, examine as seções a seguir para ajudar a corrigir o problema de inicialização do SDK.
Etapa 2: verificar se há exceções de JavaScript
Verifique se há exceções de JavaScript. Use um navegador que ofereça suporte a ferramentas de desenvolvedor. Selecione F12 para exibir as ferramentas do desenvolvedor, carregar a página e verificar se ocorreram exceções. O script do SDK (por exemplo, no ai.2.min.js) causa exceções? Nesse caso, ocorreu um dos seguintes cenários:
A configuração passada para o SDK contém uma configuração inesperada.
A configuração passada para o SDK não tem uma configuração necessária.
Uma versão defeituosa foi implantada no CDN.
Para verificar se há uma configuração defeituosa, altere a configuração passada para o snippet (se você ainda não tiver feito isso) para que ele inclua apenas sua chave de instrumentação como um valor de string. O código a seguir mostra um exemplo de alteração de configuração de snippet.
Observação
O suporte para assimilação de chaves de instrumentação termina em 31 de março de 2025. A ingestão de chave de instrumentação continuará funcionando, mas não forneceremos mais atualizações ou suporte para o recurso. Consulte Transição para cadeias de conexão para aproveitar os novos recursos.
<script type="text/javascript">
...
src: "https://js.monitor.azure.com/scripts/b/ai.2.min.js",
cfg: {
instrumentationKey: "<instrumentation-key-guid>"
}});
</script>
Ao usar essa configuração mínima, se você ainda vir uma exceção de JavaScript no script do SDK, crie um novo tíquete de suporte. Para corrigir o problema, você deve reverter a compilação defeituosa. Isso ocorre porque uma versão recém-implantada é provavelmente a causa do problema.
Se a exceção desaparecer, uma incompatibilidade de tipo ou um valor inesperado provavelmente está causando o problema. Inicie a solução de problemas restaurando suas opções de configuração uma a uma e teste após cada alteração até que a exceção ocorra novamente. Em seguida, verifique a documentação do item que causa o problema. Se a documentação não estiver clara ou se você precisar de ajuda, registre um problema no GitHub.
Sua configuração foi implantada e funcionando anteriormente, mas agora está relatando essa exceção? Nesse caso, pode haver um problema que afete uma versão recém-implantada. Verifique se a exceção afeta apenas um pequeno conjunto de usuários ou navegadores. Registre um problema no GitHub ou crie um novo tíquete de suporte.
Etapa 3: Habilitar a depuração do console do navegador
Se nenhuma exceção lançada tiver ocorrido, você deverá habilitar a depuração do console adicionando a configuração loggingLevelConsole à configuração, conforme mostrado no exemplo de configuração de snippet a seguir. Essa alteração envia todos os erros e avisos de inicialização para o console do navegador. (Para exibir o console do navegador, selecione F12 para abrir as ferramentas do desenvolvedor e, em seguida, selecione o Guia Console .) Quaisquer erros relatados devem ser autoexplicativos. Se precisar de mais ajuda, registre um problema no 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>
Observação
Durante a inicialização, o SDK faz algumas verificações básicas para dependências principais conhecidas. Se o runtime atual não fornecer essas verificações, o runtime relatará as falhas como mensagens de aviso para o console (mas somente se o valor da loggingLevelConsole configuração for maior que zero).
Se o SDK ainda não for inicializado, tente habilitar a configuração enableDebug. Depois de fazer essa alteração, todos os erros internos são lançados como exceções. Isso causa uma perda de telemetria. Como essa configuração é apenas para desenvolvedores, ela provavelmente faz com que mais exceções sejam geradas devido a verificações internas. Revise cada exceção para determinar qual problema está causando a falha do SDK. Use a versão não minimizada do script (alterando a extensão do nome do arquivo de .min.js para apenas .js). Caso contrário, as exceções serão ilegíveis. O código a seguir mostra as alterações de configuração do snippet de exemplo.
Aviso
Essa configuração somente para desenvolvedores NUNCA deve ser habilitada em um ambiente de produção completo, pois isso faz com que você perca a telemetria.
<script type="text/javascript">
...
src: "https://js.monitor.azure.com/scripts/b/ai.2.js",
cfg:{
instrumentationKey: "<instrumentation-key-guid>",
enableDebug: true
}});
</script>
Se essa ação ainda não fornecer insights, você deverá registrar um problema no GitHub fornecendo os detalhes e um site de exemplo, se usar um. Inclua a versão do navegador, o sistema operacional e os detalhes da estrutura JavaScript para ajudar a identificar o problema.
Causa 4: bloqueio da CDN JavaScript do Application Insights
Um bloqueio de CDN será possível se um ponto de extremidade de CDN do SDK do JavaScript do Application Insights for relatado ou identificado como não seguro. Nessa situação, o endpoint é bloqueado publicamente e os consumidores dessas listas começam a bloquear todo o acesso.
Para resolver esse problema, o proprietário do ponto de extremidade da CDN deve trabalhar com a entidade de lista de bloqueios que marcou o ponto de extremidade como não seguro. Em seguida, a entidade da lista de bloqueios pode remover o ponto de extremidade da lista relevante.
Verifique os seguintes sites de segurança na Internet para saber se eles identificam o endpoint da CDN como inseguro:
Pode levar muito tempo para resolver esse problema. Os usuários ou departamentos de TI corporativos podem ter que forçar uma atualização ou permitir explicitamente os pontos de extremidade da CDN. O tempo total necessário para resolver esse problema depende da frequência exigida pelo aplicativo, firewall ou ambiente para atualizar suas cópias locais das listas.
Se o endpoint da CDN for identificado como não seguro, crie um tíquete de suporte para resolver o problema o mais rápido possível.
As seções a seguir descrevem mais especificamente como um bloqueio pode ocorrer e como corrigi-lo.
Causa 4a: Bloqueio do usuário (navegador, bloqueador instalado ou firewall pessoal)
Verifique se os usuários executaram alguma das seguintes ações de configuração:
Instalou um plug-in de navegador (normalmente na forma de um bloqueador de anúncios, malware ou pop-up)
Bloqueou ou não permitiu os pontos de extremidade da CDN do Application Insights em seu navegador ou proxy
Configurou uma regra de firewall que causa um bloqueio do domínio CDN para o SDK (ou uma falha ao resolver a entrada DNS)
Solução 4a: adicionar exceções de lista de bloqueios para endpoints de CDN
Se os usuários executaram qualquer uma das ações de configuração listadas, trabalhe com eles (ou forneça documentação) para permitir os pontos de extremidade da CDN.
Os usuários podem ter instalado plug-ins que usam a lista de bloqueios pública. Caso contrário, eles provavelmente estão usando outra solução configurada manualmente ou os plug-ins estão usando uma lista de bloqueio de domínio privado.
Diga aos usuários para permitir o download de scripts dos pontos de extremidade da CDN do Application Insights incluindo os pontos de extremidade na lista de exceções de regra de firewall ou plug-in do navegador. Essas listas variam de acordo com o ambiente do usuário.
Aqui está um exemplo dessa situação que mostra como configurar o Google Chrome para permitir ou bloquear o acesso a sites.
Causa 4b: bloqueio de firewall corporativo
Se os usuários estiverem em uma rede corporativa, o firewall corporativo provavelmente será a origem do bloqueio da CDN. O departamento de TI corporativo provavelmente implementou alguma forma de sistema de filtragem da Internet.
Solução 4b1: Adicionar exceções para pontos de extremidade CDN para corporações
Importante
Seus usuários usam uma nuvem privada e não têm acesso à Internet pública? Nesse caso, você precisa usar os pacotes npm do Application Insights para inserir o SDK ou hospedar o SDK do Application Insights em sua própria CDN.
Trabalhe com o departamento de TI da sua empresa para permitir as regras necessárias para seus usuários. Essa solução é semelhante à adição de exceções para usuários. Faça com que o departamento de TI configure os pontos de extremidade da CDN do Application Insights para download, incluindo-os (ou removendo-os) em qualquer serviço de lista de bloqueio ou lista de permissões de domínio.
Solução 4b2: hospedar o SDK em sua própria CDN
Em vez de fazer com que os usuários baixem o SDK do Application Insights da CDN pública, você pode hospedar o SDK do Application Insights em seu próprio ponto de extremidade da CDN. Recomendamos que você use uma versão específica (ai.2.#.#.min.js) do SDK para facilitar a identificação de qual versão você está usando. Além disso, atualize o SDK regularmente para a versão atual (ai.2.min.js) para que você possa usar as correções de bugs e os novos recursos disponíveis.
Solução 4b3: Usar pacotes npm para inserir o SDK do Application Insights
Em vez de usar o snippet e adicionar pontos de extremidade CDN públicos, você pode usar os pacotes npm para incluir o SDK como parte de seus próprios arquivos JavaScript. O SDK se torna apenas mais um pacote dentro de seus próprios scripts. Para obter mais informações, consulte a seção de configuração baseada em npm da página GitHub do SDK do JavaScript do Application Insights.
Observação
Recomendamos que, ao usar pacotes npm, você também use alguma forma de empacotador JavaScript para ajudá-lo a fazer divisão e minificação de código.
Assim como acontece com o snippet, os mesmos problemas de bloqueio que aparecem aqui podem afetar seus próprios scripts (com ou sem o uso dos pacotes npm do SDK). Dependendo do aplicativo, dos usuários e da estrutura, considere implementar algo semelhante à lógica no snippet para detectar e relatar esses problemas.
Solucionar problemas de suporte ao mapa de origem para aplicativos JavaScript
A tabela a seguir explica determinados problemas que envolvem o suporte ao mapa de origem para aplicativos JavaScript e oferece estratégias para ajudar a corrigir esses problemas.
| Problema | Descrição |
|---|---|
| Configurações necessárias de RBAC (controle de acesso baseado em função) do Azure em seu contêiner de blob | Qualquer usuário no portal que usa esse recurso deve receber pelo menos uma função de Leitor de Dados de Blob de Armazenamento para o contêiner de blob. Você deve atribuir essa função a qualquer pessoa que queira usar os mapas de origem por meio desse recurso. A depender de como o contêiner foi criado, essa função pode não ter sido atribuída automaticamente a você ou à sua equipe. |
| Source map não encontrado | Para corrigir esse problema, execute as seguintes ações:
|
Corrija o aviso "Clique em linhas de evento sem valor parentId"
Quando você usa o Application Insights e o plug-in de Coleta Automática do Click Analytics no aplicativo, o seguinte aviso de telemetria pode aparecer na pasta de trabalho do Application Insights: "Clique em Linhas de evento sem valor parentId".
Motivo
Esse problema pode ocorrer se a ID pai não for especificada no elemento HTML pai. Essa condição faz com que o evento seja acionado em todos os seus elementos pai.
Solução
Para corrigir esse problema, adicione o data-parentid atributo or data-<customPrefix>-parentid ao elemento HTML pai. Aqui está um exemplo do código HTML:
<div data-heart-id="demo Header" data-heart-parentid="demo.Header" data-heart-parent-group="demo.Header.Group">
Próximas etapas
Aviso de isenção de responsabilidade para informações de terceiros
Os produtos de terceiros mencionados neste artigo são produzidos por empresas independentes da Microsoft. A Microsoft não oferece nenhuma garantia, implícita ou não, do desempenho ou da confiabilidade desses produtos.
Entre em contato conosco para obter ajuda
Se você tiver dúvidas ou precisar de ajuda, crie uma solicitação de suporte ou peça ajuda à comunidade de suporte do Azure. Você também pode enviar comentários sobre o produto para a comunidade de comentários do Azure.