Application Insights JavaScript SDK (Web) para TypeScript

Quando Usar

Use esta habilidade quando precisar instrumentar aplicativos de navegador/web com o Application Insights JavaScript SDK (@microsoft/applicationinsights-web). Use para Monitoramento de Usuários Reais (RUM) — visualizações de página, cliques, dependências AJAX/fetch, exceções, eventos personalizados e rastreamentos de agente GenAI no lado do navegador correlacionados ao backend...

Monitoramento de Usuários Reais (RUM) para aplicativos de navegador com @microsoft/applicationinsights-web. Coleta automaticamente visualizações de página, dependências AJAX/fetch, exceções não tratadas e (com o plugin Click Analytics) cliques. Suporta eventos personalizados, métricas e rastreamentos de agente GenAI que seguem as convenções semânticas do OpenTelemetry GenAI e se correlacionam com spans de backend via W3C Trace Context.

Distinto de azure-monitor-opentelemetry-ts, que é para aplicativos de servidor Node.js. Esta habilidade é para código de navegador/web (e React Native).

Antes da Implementação

Pesquise microsoft-docs MCP para padrões de API atuais:

• Consulta: "Application Insights JavaScript SDK setup"
• Consulta: "Application Insights JavaScript SDK configuration"
• Consulta: "Application Insights JavaScript framework extensions React Angular"
• Verifique a versão do pacote: npm view @microsoft/applicationinsights-web version

Pacotes

Instalação

npm i --save @microsoft/applicationinsights-web
# Optional plugins (install only what you use):
npm i --save @microsoft/applicationinsights-clickanalytics-js
npm i --save @microsoft/applicationinsights-react-js @microsoft/applicationinsights-react-native @microsoft/applicationinsights-angularplugin-js

Tipagens vêm com o pacote — nenhuma instalação separada de @types/... é necessária.

String de Conexão

O SDK do navegador requer uma string de conexão no momento da inicialização. Ela é enviada em texto plano para os clientes — a autenticação do Microsoft Entra ID não é suportada para telemetria do navegador. Use um recurso separado do App Insights com autenticação local habilitada para RUM do navegador se precisar isolá-lo da telemetria de backend.

# Vite / CRA / Next.js — expose to client via the public env prefix
VITE_APPINSIGHTS_CONNECTION_STRING="InstrumentationKey=...;IngestionEndpoint=https://...;LiveEndpoint=https://..."
NEXT_PUBLIC_APPINSIGHTS_CONNECTION_STRING="InstrumentationKey=..."

Início Rápido (npm)

import { ApplicationInsights } from "@microsoft/applicationinsights-web";

export const appInsights = new ApplicationInsights({
  config: {
    connectionString: import.meta.env.VITE_APPINSIGHTS_CONNECTION_STRING,
    enableAutoRouteTracking: true,        // SPA route changes -> page views
    enableCorsCorrelation: true,          // propagate Request-Id / traceparent to cross-origin AJAX
    enableRequestHeaderTracking: true,
    enableResponseHeaderTracking: true,
    distributedTracingMode: 2,            // DistributedTracingModes.AI_AND_W3C — emit traceparent for backend correlation
    autoTrackPageVisitTime: true,
    disableFetchTracking: false,          // fetch() is auto-instrumented by default
    excludeRequestFromAutoTrackingPatterns: [/livemetrics\.azure\.com/i]
  }
});

appInsights.loadAppInsights();
appInsights.trackPageView();

Chame loadAppInsights() exatamente uma vez, o mais cedo possível (antes das interações do usuário que você deseja rastrear). Em seguida, trackPageView() para a carga inicial — quando enableAutoRouteTracking estiver ativado, as alterações de rota subsequentes são automáticas.

Início Rápido (Script Loader do SDK)

Recomendado quando você deseja um SDK com atualização automática e sem pipeline de build. Cole isso como o primeiro <script> em <head>:

<script type="text/javascript" src="https://js.monitor.azure.com/scripts/b/ai.3.gbl.min.js" crossorigin="anonymous"></script>
<script type="text/javascript">
  var appInsights = window.appInsights || function (cfg) {

…