Partilhar via

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

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 @microsoft/applicationinsights-web

Adicione a extensão ao seu código

Nota

No dia 31 de março de 2025, terminará o suporte à ingestão de chaves de instrumentação. 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:

Nota

Se você estiver usando a versão 5 ou posterior do histórico, a opção basename não é mais suportada em createBrowserHistory.

Em vez de const browserHistory = createBrowserHistory({ basename: '' });, utilize const browserHistory = createBrowserHistory();.

Para verificar qual versão do histórico você está usando, execute npm list history.

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 para Análise de Cliques.

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

    • Para React, 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 Tipo 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 router, a maioria dos utilizadores pode utilizar o campo enableAutoRouteTracking 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 tanto o campo enableAutoRouteTracking quanto o objeto history, pois obterá vários eventos de visualizaçã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 que duas propriedades sejam passadas para ele. Eles são a ReactPlugin instância criada destinada ao aplicativo e um componente a ser apresentado 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 o componente com withAITracking.

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 ComponentDidMount até ao evento ComponentWillUnmount. 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 time.

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.

Captura de tela que mostra um gráfico que exibe a métrica personalizada React Component Engaged Time (segundos) dividido por Nome do Componente

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 withAITracking ordem superior, sem adicionar outro componente à estrutura do 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:

  • A instância do Application Insights pode ser obtida através do useAppInsightsContext Hook.
  • Nome do evento.
  • Objeto de dados de evento que encapsula as alterações que precisam ser controladas.
  • skipFirstRun (opcional) sinalizador para pular a chamada trackEvent 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 a cada atualização do 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.

Próximos passos