Ativar a Monitorização de Utilizador Real do Application Insights do Azure Monitor

  • Artigo

O SDK JavaScript do Microsoft Azure Monitor Application Insights coleta dados de uso, o que permite monitorar e analisar o desempenho de aplicativos Web JavaScript. Isso é comumente chamado de Monitoramento de Usuário Real ou RUM.

O SDK JavaScript do Application Insights tem um SDK base e vários plug-ins para mais recursos.

Conceptual diagram that shows the Application Insights JavaScript SDK, its plugins/extensions, and their relationship to each other.

Coletamos visualizações de página por padrão. Mas se você também quiser coletar cliques por padrão, considere adicionar o plug-in Click Analytics Auto-Collection:

Nós fornecemos o plugin Debug e o plug-in Performance para depuração/teste. Em casos raros, é possível construir sua própria extensão adicionando um plug-in personalizado.

Pré-requisitos

Começar

Siga as etapas nesta seção para instrumentar seu aplicativo com o SDK JavaScript do Application Insights.

Gorjeta

Boas notícias! Estamos a tornar ainda mais fácil ativar o JavaScript. Confira onde JavaScript (Web) SDK Loader Script injeção por configuração está disponível!

Adicionar o código JavaScript

Dois métodos estão disponíveis para adicionar o código para habilitar o Application Insights por meio do SDK JavaScript do Application Insights:

Método Quando devo usar este método?
JavaScript (Web) SDK Loader Script Para a maioria dos clientes, recomendamos o JavaScript (Web) SDK Loader Script porque você nunca precisa atualizar o SDK e obtém as atualizações mais recentes automaticamente. Além disso, você tem controle sobre quais páginas você adiciona o SDK JavaScript do Application Insights.
Pacote npm Você deseja trazer o SDK para seu código e habilitar o IntelliSense. Essa opção só é necessária para desenvolvedores que precisam de mais eventos e configurações personalizadas. Esse método é necessário se você planeja usar a extensão React, React Native ou Angular Framework.

  1. Cole o JavaScript (Web) SDK Loader Script na parte superior de cada página para a qual você deseja habilitar o Application Insights.

    De preferência, você deve adicioná-lo como o primeiro script em sua <head> seção para que ele possa monitorar quaisquer problemas potenciais com todas as suas dependências.

    Se o Internet Explorer 8 for detetado, o JavaScript SDK v2.x será carregado automaticamente.

    <script type="text/javascript">
!(function (cfg){function e(){cfg.onInit&&cfg.onInit(i)}var S,u,D,t,n,i,C=window,x=document,w=C.location,I="script",b="ingestionendpoint",E="disableExceptionTracking",A="ai.device.";"instrumentationKey"[S="toLowerCase"](),u="crossOrigin",D="POST",t="appInsightsSDK",n=cfg.name||"appInsights",(cfg.name||C[t])&&(C[t]=n),i=C[n]||function(l){var d=!1,g=!1,f={initialize:!0,queue:[],sv:"7",version:2,config:l};function m(e,t){var n={},i="Browser";function a(e){e=""+e;return 1===e.length?"0"+e:e}return n[A+"id"]=i[S](),n[A+"type"]=i,n["ai.operation.name"]=w&&w.pathname||"_unknown_",n["ai.internal.sdkVersion"]="javascript:snippet_"+(f.sv||f.version),{time:(i=new Date).getUTCFullYear()+"-"+a(1+i.getUTCMonth())+"-"+a(i.getUTCDate())+"T"+a(i.getUTCHours())+":"+a(i.getUTCMinutes())+":"+a(i.getUTCSeconds())+"."+(i.getUTCMilliseconds()/1e3).toFixed(3).slice(2,5)+"Z",iKey:e,name:"Microsoft.ApplicationInsights."+e.replace(/-/g,"")+"."+t,sampleRate:100,tags:n,data:{baseData:{ver:2}},ver:4,seq:"1",aiDataContract:undefined}}var h=-1,v=0,y=["js.monitor.azure.com","js.cdn.applicationinsights.io","js.cdn.monitor.azure.com","js0.cdn.applicationinsights.io","js0.cdn.monitor.azure.com","js2.cdn.applicationinsights.io","js2.cdn.monitor.azure.com","az416426.vo.msecnd.net"],k=l.url||cfg.src;if(k){if((n=navigator)&&(~(n=(n.userAgent||"").toLowerCase()).indexOf("msie")||~n.indexOf("trident/"))&&~k.indexOf("ai.3")&&(k=k.replace(/(\/)(ai\.3\.)([^\d]*)$/,function(e,t,n){return t+"ai.2"+n})),!1!==cfg.cr)for(var e=0;e<y.length;e++)if(0<k.indexOf(y[e])){h=e;break}var i=function(e){var a,t,n,i,o,r,s,c,p,u;f.queue=[],g||(0<=h&&v+1<y.length?(a=(h+v+1)%y.length,T(k.replace(/^(.*\/\/)([\w\.]*)(\/.*)$/,function(e,t,n,i){return t+y[a]+i})),v+=1):(d=g=!0,o=k,c=(p=function(){var e,t={},n=l.connectionString;if(n)for(var i=n.split(";"),a=0;a<i.length;a++){var o=i[a].split("=");2===o.length&&(t[o[0][S]()]=o[1])}return t[b]||(e=(n=t.endpointsuffix)?t.location:null,t[b]="https://"+(e?e+".":"")+"dc."+(n||"services.visualstudio.com")),t}()).instrumentationkey||l.instrumentationKey||"",p=(p=p[b])?p+"/v2/track":l.endpointUrl,(u=[]).push((t="SDK LOAD Failure: Failed to load Application Insights SDK script (See stack for details)",n=o,r=p,(s=(i=m(c,"Exception")).data).baseType="ExceptionData",s.baseData.exceptions=[{typeName:"SDKLoadFailed",message:t.replace(/\./g,"-"),hasFullStack:!1,stack:t+"\nSnippet failed to load ["+n+"] -- Telemetry is disabled\nHelp Link: https://go.microsoft.com/fwlink/?linkid=2128109\nHost: "+(w&&w.pathname||"_unknown_")+"\nEndpoint: "+r,parsedStack:[]}],i)),u.push((s=o,t=p,(r=(n=m(c,"Message")).data).baseType="MessageData",(i=r.baseData).message='AI (Internal): 99 message:"'+("SDK LOAD Failure: Failed to load Application Insights SDK script (See stack for details) ("+s+")").replace(/\"/g,"")+'"',i.properties={endpoint:t},n)),o=u,c=p,JSON&&((r=C.fetch)&&!cfg.useXhr?r(c,{method:D,body:JSON.stringify(o),mode:"cors"}):XMLHttpRequest&&((s=new XMLHttpRequest).open(D,c),s.setRequestHeader("Content-type","application/json"),s.send(JSON.stringify(o))))))},a=function(e,t){g||setTimeout(function(){!t&&f.core||i()},500),d=!1},T=function(e){var n=x.createElement(I),e=(n.src=e,cfg[u]);return!e&&""!==e||"undefined"==n[u]||(n[u]=e),n.onload=a,n.onerror=i,n.onreadystatechange=function(e,t){"loaded"!==n.readyState&&"complete"!==n.readyState||a(0,t)},cfg.ld&&cfg.ld<0?x.getElementsByTagName("head")[0].appendChild(n):setTimeout(function(){x.getElementsByTagName(I)[0].parentNode.appendChild(n)},cfg.ld||0),n};T(k)}try{f.cookie=x.cookie}catch(p){}function t(e){for(;e.length;)!function(t){f[t]=function(){var e=arguments;d||f.queue.push(function(){f[t].apply(f,e)})}}(e.pop())}var r,s,n="track",o="TrackPage",c="TrackEvent",n=(t([n+"Event",n+"PageView",n+"Exception",n+"Trace",n+"DependencyData",n+"Metric",n+"PageViewPerformance","start"+o,"stop"+o,"start"+c,"stop"+c,"addTelemetryInitializer","setAuthenticatedUserContext","clearAuthenticatedUserContext","flush"]),f.SeverityLevel={Verbose:0,Information:1,Warning:2,Error:3,Critical:4},(l.extensionConfig||{}).ApplicationInsightsAnalytics||{});return!0!==l[E]&&!0!==n[E]&&(t(["_"+(r="onerror")]),s=C[r],C[r]=function(e,t,n,i,a){var o=s&&s(e,t,n,i,a);return!0!==o&&f["_"+r]({message:e,url:t,lineNumber:n,columnNumber:i,error:a,evt:C.event}),o},l.autoExceptionInstrumented=!0),f}(cfg.cfg),(C[n]=i).queue&&0===i.queue.length?(i.queue.push(e),i.trackPageView({})):e();})({
src: "https://js.monitor.azure.com/scripts/b/ai.3.gbl.min.js",
// name: "appInsights",
// ld: 0,
// useXhr: 1,
crossOrigin: "anonymous",
// onInit: null,
// cr: 0,
cfg: { // Application Insights Configuration
 connectionString: "YOUR_CONNECTION_STRING"
}});
</script>

  2. (Opcional) Adicione ou atualize a configuração opcional do JavaScript (Web) SDK Loader Script, dependendo se você precisa otimizar o carregamento de sua página da Web ou resolver erros de carregamento.

    Screenshot of the JavaScript (Web) SDK Loader Script. The parameters for configuring the JavaScript (Web) SDK Loader Script are highlighted.

Configuração do JavaScript (Web) SDK Loader Script

Nome Type Necessária? Description
src string Obrigatório A URL completa de onde carregar o SDK. Esse valor é usado para o atributo "src" de um script /> tag adicionado <dinamicamente. Você pode usar o local CDN público ou o seu próprio local hospedado privadamente.
nome string Opcional O nome global do SDK inicializado. Use essa configuração se precisar inicializar dois SDKs diferentes ao mesmo tempo.

O valor padrão é appInsights, portanto window.appInsights , é uma referência à instância inicializada.

Nota: Se você atribuir um valor de nome ou se uma instância anterior tiver sido atribuída ao nome global appInsightsSDK, o código de inicialização do SDK exigirá que ele esteja no namespace global para window.appInsightsSDK=<name value> garantir que o esqueleto correto do JavaScript (Web) SDK Loader Script e os métodos proxy sejam inicializados e atualizados.
ld Número em EM Opcional Define o atraso de carregamento a aguardar antes de tentar carregar o SDK. Use essa configuração quando a página HTML estiver falhando ao carregar porque o JavaScript (Web) SDK Loader Script está carregando no momento errado.

O valor padrão é 0ms após o tempo limite. Se você usar um valor negativo, a marca de script será imediatamente adicionada à <head> região da página e bloqueará o evento de carregamento de página até que o script seja carregado ou falhe.
useXhr boolean Opcional Essa configuração é usada apenas para relatar falhas de carregamento do SDK. Por exemplo, essa configuração é útil quando o JavaScript (Web) SDK Loader Script está impedindo o carregamento da página HTML, fazendo com que fetch() fique indisponível.

O relatório primeiro tenta usar fetch() se disponível e, em seguida, fallback para XHR. Defina essa configuração para true ignorar a verificação de busca. Essa configuração só é necessária se seu aplicativo estiver sendo usado em um ambiente onde a busca não enviaria os eventos de falha, como se o JavaScript (Web) SDK Loader Script não estiver sendo carregado com êxito.
origem cruzada string Opcional Ao incluir essa configuração, a marca de script adicionada para baixar o SDK inclui o atributo crossOrigin com esse valor de cadeia de caracteres. Use essa configuração quando precisar fornecer suporte para CORS. Quando não definido (o padrão), nenhum atributo crossOrigin é adicionado. Os valores recomendados não são definidos (o padrão), "", ou "anônimo". Para todos os valores válidos, consulte a documentação do atributo HTML de origem cruzada.
onInit function(aiSdk) { ... } Opcional Essa função de retorno de chamada é chamada depois que o script SDK principal foi carregado e inicializado com êxito a partir da CDN (com base no valor src). Essa função de retorno de chamada é útil quando você precisa inserir um inicializador de telemetria. Ele passou por um argumento, que é uma referência à instância do SDK que está sendo chamada e também é chamada antes da primeira exibição de página inicial. Se o SDK já tiver sido carregado e inicializado, esse retorno de chamada ainda será chamado. Observação : durante o processamento da matriz sdk.queue, esse retorno de chamada é chamado. NÃO é possível adicionar mais itens à fila porque eles são ignorados e descartados. (Adicionado como parte do JavaScript (Web) SDK Loader Script versão 5--o valor sv:"5" dentro do script).
CR boolean Opcional Se o SDK falhar ao carregar e o valor do ponto de extremidade definido for src o local da CDN pública, essa opção de configuração tentará carregar imediatamente o SDK de um dos seguintes pontos de extremidade CDN de backup:
  • js.monitor.azure.com
  • js.cdn.applicationinsights.io
  • js.cdn.monitor.azure.com
  • js0.cdn.applicationinsights.io
  • js0.cdn.monitor.azure.com
  • js2.cdn.applicationinsights.io
  • js2.cdn.monitor.azure.com
  • az416426.vo.msecnd.net
NOTA: az416426.vo.msecnd.net é parcialmente suportado, por isso não é recomendado.

Se o SDK for carregado com êxito a partir de um ponto de extremidade CDN de backup, ele será carregado a partir do primeiro ponto de extremidade disponível, que será determinado quando o servidor executar uma verificação de carga bem-sucedida. Se o SDK falhar ao carregar de qualquer um dos pontos de extremidade CDN de backup, a mensagem de erro Falha do SDK será exibida.

Quando não definido, o valor padrão é true. Se você não quiser carregar o SDK a partir dos pontos de extremidade CDN de backup, defina esta opção de configuração como false.

Se você estiver carregando o SDK de seu próprio ponto de extremidade CDN hospedado privadamente, essa opção de configuração não será aplicável.

Cole a cadeia de conexão em seu ambiente

Para colar a cadeia de conexão em seu ambiente, execute estas etapas:

  1. Navegue até o painel Visão geral do recurso do Application Insights.

  2. Localize a cadeia de conexão.

  3. Selecione o ícone Copiar para a área de transferência para copiar a cadeia de conexão para a área de transferência.

    Screenshot that shows Application Insights overview and connection string.

  4. Substitua o espaço reservado "YOUR_CONNECTION_STRING" no código JavaScript pela cadeia de conexão copiada para a área de transferência.

    O connectionString formato deve seguir "InstrumentationKey=xxxx;....". Se a cadeia de caracteres fornecida não atender a esse formato, o processo de carregamento do SDK falhará.

    A cadeia de conexão não é considerada um token ou chave de segurança. Para obter mais informações, consulte As novas regiões do Azure exigem o uso de cadeias de conexão?.

(Opcional) Adicionar configuração do SDK

A configuração opcional do SDK é passada para o SDK JavaScript do Application Insights durante a inicialização.

Para adicionar a configuração do SDK, adicione cada opção de configuração diretamente em connectionString. Por exemplo:

Screenshot of JavaScript code with SDK configuration options added and highlighted.

(Opcional) Adicionar configuração avançada do SDK

Se você quiser usar os recursos extras fornecidos por plug-ins para estruturas específicas e, opcionalmente, ativar o plug-in Click Analytics, consulte:

Confirmar que os dados estão fluindo

  1. Vá para o recurso do Application Insights para o qual você habilitou o SDK.

  2. No menu de recursos do Application Insights à esquerda, em Investigar, selecione o painel de pesquisa Transações.

  3. Abra o menu suspenso Tipos de evento e selecione Selecionar tudo para desmarcar as caixas de seleção no menu.

  4. No menu suspenso Tipos de eventos, selecione:

    • Vista de Página para Azure Monitor Application Insights Monitorização de Utilizadores Reais
    • Evento personalizado para o plug-in Click Analytics Auto-Collection.

    Pode levar alguns minutos para que os dados apareçam no portal. Se os únicos dados exibidos forem uma exceção de falha de carregamento, consulte Solucionar problemas de falha de carregamento do SDK para aplicativos Web JavaScript.

    Em alguns casos, se várias instâncias de versões diferentes do Application Insights estiverem em execução na mesma página, poderão ocorrer erros durante a inicialização. Para esses casos e a mensagem de erro exibida, consulte Executando várias versões do SDK JavaScript do Application Insights em uma sessão. Se você encontrou um desses erros, tente alterar o namespace usando a name configuração. Para obter mais informações, consulte Configuração do JavaScript (Web) SDK Loader Script.

    Screenshot of the Application Insights Transaction search pane in the Azure portal with the Page View option selected. The page views are highlighted.

  5. Se você quiser consultar dados para confirmar que os dados estão fluindo:

    1. Selecione Logs no painel esquerdo.

      Quando você seleciona Logs, a caixa de diálogo Consultas é aberta, que contém consultas de exemplo relevantes para seus dados.

    2. Selecione Executar para a consulta de exemplo que deseja executar.

    3. Se necessário, você pode atualizar a consulta de exemplo ou escrever uma nova consulta usando Kusto Query Language (KQL).

      Para operadores KQL essenciais, consulte Aprenda operadores KQL comuns.

Perguntas mais frequentes

Esta secção fornece respostas a perguntas comuns.

Quais são as contagens de usuários e sessões?

  • O JavaScript SDK define um cookie de usuário no web client, para identificar usuários que retornam, e um cookie de sessão para atividades de grupo.
  • Se não houver um script do lado do cliente, você pode definir cookies no servidor.
  • Se um usuário real usar seu site em navegadores diferentes, ou usando navegação privada/anônima, ou máquinas diferentes, eles serão contados mais de uma vez.
  • Para identificar um usuário conectado em máquinas e navegadores, adicione uma chamada para setAuthenticatedUserContext().

O que é o desempenho/sobrecarga do SDK do JavaScript?

O SDK JavaScript do Application Insights tem uma sobrecarga mínima em seu site. Com apenas 36 KB compactados e levando apenas ~15 ms para inicializar, o SDK adiciona uma quantidade insignificante de tempo de carregamento ao seu site. Os componentes mínimos da biblioteca são carregados rapidamente quando você usa o SDK e o script completo é baixado em segundo plano.

Além disso, enquanto o script é baixado da CDN, todo o acompanhamento da sua página é enfileirado, para que você não perca nenhuma telemetria durante todo o ciclo de vida da página. Esse processo de configuração fornece à sua página um sistema de análise perfeito que é invisível para seus usuários.

Quais navegadores são suportados pelo JavaScript SDK?

Chrome Firefox IE Opera Safari
Chrome mais recente ✔ Firefox mais recente ✔ v3.x: IE 9+ & Microsoft Edge ✔
v2.x: Compatível com IE 8+ & Microsoft Edge ✔		 Opera mais recente ✔ Safari mais recente ✔

Onde posso encontrar exemplos de código para o JavaScript SDK?

Para obter exemplos executáveis, consulte Exemplos do SDK JavaScript do Application Insights.

Qual é a compatibilidade do ES3/Internet Explorer 8 com o JavaScript SDK?

Precisamos tomar as medidas necessárias para garantir que esse SDK continue a "funcionar" e não interrompa a execução do JavaScript quando carregado por um navegador mais antigo. Seria ideal não suportar navegadores mais antigos, mas muitos grandes clientes não podem controlar qual navegador seus usuários escolhem usar.

Esta declaração não significa que suportamos apenas o menor conjunto comum de recursos. Precisamos manter a compatibilidade do código ES3. Novos recursos precisam ser adicionados de uma maneira que não interrompa a análise de JavaScript do ES3 e adicionados como um recurso opcional.

Consulte GitHub para obter detalhes completos sobre o suporte ao Internet Explorer 8.

O SDK do JavaScript é de código aberto?

Sim, o SDK JavaScript do Application Insights é de código aberto. Para visualizar o código-fonte ou contribuir para o projeto, consulte o repositório oficial do GitHub.

Suporte

  • Se não conseguir executar a aplicação ou se não estiver a obter dados como esperado, consulte o artigo dedicado à resolução de problemas.
  • Para perguntas comuns sobre o SDK do JavaScript, consulte as Perguntas frequentes.
  • Para problemas de suporte do Azure, abra um tíquete de suporte do Azure.
  • Para obter uma lista de problemas abertos relacionados ao SDK JavaScript do Application Insights, consulte a página Problemas do GitHub.
  • Use a extensão do Visualizador de Telemetria para listar os eventos individuais na carga útil da rede e monitorar as chamadas internas no Application Insights.

Próximos passos