Habilitar uma extensão de estrutura para o SDK JavaScript do Application Insights

  • Artigo

Além do SDK principal, também há plugins disponíveis para estruturas específicas, como o plug-in React, o plug-in React Native e o plug-in Angular.

Esses plugins fornecem funcionalidade extra e integração com a estrutura específica.

Pré-requisitos

  • Verifique se a versão do plug-in React que você deseja instalar é compatível com sua versão do Application Insights. Para obter mais informações, consulte Matriz de compatibilidade para o plug-in React.

O que o plug-in permite?

O plug-in React para o SDK JavaScript do Application Insights permite:

  • Acompanhe o histórico do roteador
  • Monitorizar exceções
  • Rastreie o uso de componentes
  • Usar o Application Insights com o React Context

Adicionar um plug-in

Para adicionar um plug-in, siga as etapas nesta seção.

Instalar o pacote 


npm install @microsoft/applicationinsights-react-js

Adicione a extensão ao seu código

Nota

A 31 de março de 2025, o suporte da ingestão de chaves de instrumentação terminará. A ingestão de chaves de instrumentação continuará a funcionar, mas não forneceremos mais atualizações ou suporte para o recurso. Transição para cadeias de conexão para aproveitar os novos recursos.

Inicialize uma conexão com o Application Insights:

import React from 'react';
import { ApplicationInsights } from '@microsoft/applicationinsights-web';
import { ReactPlugin } from '@microsoft/applicationinsights-react-js';
import { createBrowserHistory } from "history";
const browserHistory = createBrowserHistory({ basename: '' });
var reactPlugin = new ReactPlugin();
// *** Add the Click Analytics plug-in. ***
/* var clickPluginInstance = new ClickAnalyticsPlugin();
   var clickPluginConfig = {
     autoCapture: true
}; */
var appInsights = new ApplicationInsights({
    config: {
        connectionString: 'YOUR_CONNECTION_STRING_GOES_HERE',
        // *** If you're adding the Click Analytics plug-in, delete the next line. ***
        extensions: [reactPlugin],
     // *** Add the Click Analytics plug-in. ***
     // extensions: [reactPlugin, clickPluginInstance],
        extensionConfig: {
          [reactPlugin.identifier]: { history: browserHistory }
       // *** Add the Click Analytics plug-in. ***
       // [clickPluginInstance.identifier]: clickPluginConfig
        }
    }
});
appInsights.loadAppInsights();

(Opcional) Adicionar o plug-in Click Analytics

Se quiser adicionar o plug-in Click Analytics:

  1. Descomente as linhas do Click Analytics.

  2. Siga um destes procedimentos, dependendo do plug-in que você está adicionando:

    • Para Reagir, exclua extensions: [reactPlugin],.
    • Para o React Native, exclua extensions: [RNPlugin].
    • Para Angular, exclua extensions: [angularPlugin],.

  3. Consulte Usar o plug-in Click Analytics para continuar com o processo de configuração.

Configuração

Esta seção aborda as definições de configuração para as extensões de estrutura para o SDK JavaScript do Application Insights.

Acompanhe o histórico do roteador

Nome Type Necessária? Predefinido Descrição
História objeto Opcional nulo Rastreie o histórico do roteador. Para obter mais informações, consulte a documentação do pacote do roteador React.

Para rastrear o histórico do roteador, a maioria dos usuários pode usar o enableAutoRouteTracking campo na configuração do SDK do JavaScript. Este campo recolhe os mesmos dados para vistas de página que o history objeto.

Use o history objeto quando estiver usando uma implementação de roteador que não atualize a URL do navegador, que é o que a configuração escuta. Você não deve habilitar o campo e history o enableAutoRouteTracking objeto, pois obterá vários eventos de exibição de página.

O exemplo de código a seguir mostra como habilitar o enableAutoRouteTracking campo.

var reactPlugin = new ReactPlugin();
var appInsights = new ApplicationInsights({
    config: {
        connectionString: 'YOUR_CONNECTION_STRING_GOES_HERE',
        enableAutoRouteTracking: true,
        extensions: [reactPlugin]
    }
});
appInsights.loadAppInsights();

Monitorizar exceções

Os limites de erro do React fornecem uma maneira de lidar graciosamente com uma exceção não detetada quando ela ocorre em um aplicativo React. Quando essa exceção ocorre, é provável que a exceção precise ser registrada. O plug-in React para Application Insights fornece um componente de limite de erro que registra automaticamente a exceção quando ela ocorre.

import React from "react";
import { reactPlugin } from "./AppInsights";
import { AppInsightsErrorBoundary } from "@microsoft/applicationinsights-react-js";

const App = () => {
    return (
        <AppInsightsErrorBoundary onError={() => <h1>I believe something went wrong</h1>} appInsights={reactPlugin}>
            /* app here */
        </AppInsightsErrorBoundary>
    );
};

O AppInsightsErrorBoundary requer dois adereços para ser passado para ele. Eles são a instância criada para o aplicativo e um componente a ReactPlugin ser renderizado quando ocorre uma exceção. Quando ocorre uma exceção não tratada, trackException é chamada com as informações fornecidas para o limite de erro e o onError componente aparece.

Coletar informações do dispositivo

As informações do dispositivo, que incluem navegador, sistema operacional, versão e idioma, já estão sendo coletadas pelo pacote da Web do Application Insights.

Configuração (outros)

Rastreie o uso de componentes

Um recurso exclusivo do plug-in React é que você pode instrumentar componentes específicos e rastreá-los individualmente.

Para instrumentar componentes do React com rastreamento de uso, aplique a withAITracking função de componente de ordem superior. Para habilitar o Application Insights para um componente, envolva withAITracking o componente:

import React from 'react';
import { withAITracking } from '@microsoft/applicationinsights-react-js';
import { reactPlugin, appInsights } from './AppInsights';

// To instrument various React components usage tracking, apply the `withAITracking` higher-order
// component function.

class MyComponent extends React.Component {
    ...
}

// withAITracking takes 4 parameters (reactPlugin, Component, ComponentName, className). 
// The first two are required and the other two are optional.

export default withAITracking(reactPlugin, MyComponent);

Mede o tempo desde o evento até ao ComponentDidMountComponentWillUnmount evento. Para tornar o resultado mais preciso, ele subtrai o tempo em que o usuário ficou ocioso usando React Component Engaged Time = ComponentWillUnmount timestamp - ComponentDidMount timestamp - idle timeo .

Explore os seus dados

Use o explorador de métricas do Azure Monitor para plotar um gráfico para o nome React Component Engaged Time (seconds) da métrica personalizada e dividir essa métrica personalizada por Component Name.

Screenshot that shows a chart that displays the custom metric React Component Engaged Time (seconds) split by Component Name

Você também pode executar consultas personalizadas para dividir dados do Application Insights para gerar relatórios e visualizações de acordo com suas necessidades. Aqui está um exemplo de uma consulta personalizada. Vá em frente e cole-o diretamente no editor de consultas para testá-lo.

customMetrics
| where name contains "React Component Engaged Time (seconds)"
| summarize avg(value), count() by tostring(customDimensions["Component Name"])

Pode levar até 10 minutos para que novas métricas personalizadas apareçam no portal do Azure.

Usar o Application Insights com o React Context

Fornecemos ganchos gerais para permitir que você personalize o controle de alterações para componentes individuais. Como alternativa, você pode usar useTrackMetric ou useTrackEvent, que são contatos predefinidos que fornecemos para acompanhar as alterações nos componentes.

Os React Hooks for Application Insights foram projetados para usar o React Context como um aspeto de contenção para ele. Para usar Context, inicialize o Application Insights e importe o objeto Context:

import React from "react";
import { AppInsightsContext } from "@microsoft/applicationinsights-react-js";
import { reactPlugin } from "./AppInsights";

const App = () => {
    return (
        <AppInsightsContext.Provider value={reactPlugin}>
            /* your application here */
        </AppInsightsContext.Provider>
    );
};

Este provedor de contexto disponibiliza o Application Insights como um useContext gancho em todos os componentes filhos dele:

import React from "react";
import { useAppInsightsContext } from "@microsoft/applicationinsights-react-js";

const MyComponent = () => {
    const appInsights = useAppInsightsContext();
    const metricData = {
        average: engagementTime,
        name: "React Component Engaged Time (seconds)",
        sampleCount: 1
      };
    const additionalProperties = { "Component Name": 'MyComponent' };
    appInsights.trackMetric(metricData, additionalProperties);
    
    return (
        <h1>My Component</h1>
    );
}
export default MyComponent;
useTrackMetric

O useTrackMetric gancho replica a funcionalidade do componente de ordem superior, sem adicionar outro componente à estrutura do withAITracking componente. O Gancho tem dois argumentos:

  • A instância do Application Insights, que pode ser obtida no useAppInsightsContext Hook.
  • Um identificador para o componente para rastreamento, como seu nome.
import React from "react";
import { useAppInsightsContext, useTrackMetric } from "@microsoft/applicationinsights-react-js";

const MyComponent = () => {
    const appInsights = useAppInsightsContext();
    const trackComponent = useTrackMetric(appInsights, "MyComponent");
    
    return (
        <h1 onHover={trackComponent} onClick={trackComponent}>My Component</h1>
    );
}
export default MyComponent;

Ele opera como o componente de ordem superior, mas responde a eventos do ciclo de vida do Hooks em vez de um ciclo de vida do componente. Se houver necessidade de execução em interações específicas, o Gancho precisa ser explicitamente fornecido aos eventos do usuário.

useTrackEvent

Use o useTrackEvent Gancho para rastrear qualquer evento personalizado que um aplicativo precise rastrear, como um clique no botão ou outra chamada de API. São necessários quatro argumentos:

  • Instância do Application Insights, que pode ser obtida no useAppInsightsContext Hook.
  • Nome do evento.
  • Objeto de dados de evento que encapsula as alterações que precisam ser controladas.
  • skipFirstRun (opcional) sinalizador para ignorar a trackEvent chamada na inicialização. O valor padrão é definido para true imitar mais de perto a maneira como a versão não-Hook funciona. Com useEffect Ganchos, o efeito é acionado em cada atualização de valor, incluindo a configuração inicial do valor. Como resultado, o rastreamento começa muito cedo, o que faz com que eventos potencialmente indesejados sejam rastreados.
import React, { useState, useEffect } from "react";
import { useAppInsightsContext, useTrackEvent } from "@microsoft/applicationinsights-react-js";

const MyComponent = () => {
    const appInsights = useAppInsightsContext();
    const [cart, setCart] = useState([]);
    const trackCheckout = useTrackEvent(appInsights, "Checkout", cart);
    const trackCartUpdate = useTrackEvent(appInsights, "Cart Updated", cart);
    useEffect(() => {
        trackCartUpdate({ cartCount: cart.length });
    }, [cart]);
    
    const performCheckout = () => {
        trackCheckout();
        // submit data
    };
    
    return (
        <div>
            <ul>
                <li>Product 1 <button onClick={() => setCart([...cart, "Product 1"])}>Add to Cart</button></li>
                <li>Product 2 <button onClick={() => setCart([...cart, "Product 2"])}>Add to Cart</button></li>
                <li>Product 3 <button onClick={() => setCart([...cart, "Product 3"])}>Add to Cart</button></li>
                <li>Product 4 <button onClick={() => setCart([...cart, "Product 4"])}>Add to Cart</button></li>
            </ul>
            <button onClick={performCheckout}>Checkout</button>
        </div>
    );
}

export default MyComponent;

Quando o gancho é usado, uma carga útil de dados pode ser fornecida a ele para adicionar mais dados ao evento quando ele é armazenado no Application Insights.

Aplicativo de exemplo

Confira a demonstração do Application Insights React.

Perguntas mais frequentes

Esta secção fornece respostas a perguntas comuns.

Como o Application Insights gera informações do dispositivo, como navegador, sistema operacional, idioma e modelo?

O navegador passa a cadeia de caracteres do Agente do Usuário no cabeçalho HTTP da solicitação. O serviço de ingestão do Application Insights usa o UA Parser para gerar os campos que você vê nas tabelas de dados e experiências. Como resultado, os usuários do Application Insights não podem alterar esses campos.

Ocasionalmente, esses dados podem estar ausentes ou imprecisos se o usuário ou a empresa desativar o envio do User Agent nas configurações do navegador. Os regexes do UA Parser podem não incluir todas as informações do dispositivo. Ou o Application Insights pode não ter adotado as atualizações mais recentes.

Próximos passos