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

• 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.

• Você deve estar usando uma versão >= 2.0.0 do @microsoft/applicationinsights-web. Este plugin só funciona em aplicativos nativos de reação. Ele não funciona com aplicativos que usam a estrutura Expo ou Create React Native App, que é baseada na estrutura Expo.

• O plugin Angular NÃO é compatível com ECMAScript 3 (ES3).
• Quando adicionamos suporte para uma nova versão Angular, nosso pacote npm se torna incompatível com versões Angular de nível inferior. Continue a usar pacotes npm mais antigos até estar pronto para atualizar sua versão Angular.

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

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

• Monitorizar exceções

• Coletar informações do dispositivo

  Por padrão, este plugin coleta automaticamente:

  • ID exclusivo do dispositivo (também conhecido como ID de instalação.)
  • Nome do modelo do dispositivo (como iPhone XS, Samsung Galaxy Fold, Huawei P30 Pro, etc.)
  • Tipo de dispositivo (por exemplo, telefone, tablet, etc.)

• Desativar a recolha automática de informações do dispositivo

• Usar sua própria classe de coleta de informações do dispositivo

• Substituir as informações do dispositivo

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

• Acompanhe o histórico do roteador
• Monitorizar exceções
• Encadeie mais manipuladores de exceção personalizados

npm install @microsoft/applicationinsights-react-js

• React Native Plugin

  Por padrão, o plug-in nativo do React depende do react-native-device-info pacote. Você deve instalar e vincular a este pacote. Mantenha o react-native-device-info pacote atualizado para coletar os nomes de dispositivos mais recentes usando seu aplicativo.

  Desde a v3, o suporte para acessar o DeviceInfo foi abstraído em uma interface IDeviceInfoModule para permitir que você use / defina seu próprio módulo de informações do dispositivo. Esta interface usa os mesmos nomes de função e resultado react-native-device-info.

  
  npm install --save @microsoft/applicationinsights-react-native @microsoft/applicationinsights-web
  npm install --save react-native-device-info
  react-native link react-native-device-info
  
  

• Plug-in de dispositivo manual React Native

  Se você estiver usando o React Native Expo, adicione o React Native Manual Device Plugin em vez do React Native Plugin. O plug-in React Native usa o react-native-device-info package pacote, que o React Native Expo não suporta.

  
  npm install --save @microsoft/applicationinsights-react-native @microsoft/applicationinsights-web
  
  

npm install @microsoft/applicationinsights-angularplugin-js

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();

• Plug-in nativo do React

  Para usar esse plug-in, você precisa construí-lo e adicioná-lo como uma extension instância existente do Application Insights.

  import { ApplicationInsights } from '@microsoft/applicationinsights-web';
  import { ReactNativePlugin } from '@microsoft/applicationinsights-react-native';
  // *** Add the Click Analytics plug-in. ***
  // import { ClickAnalyticsPlugin } from '@microsoft/applicationinsights-clickanalytics-js';
  var RNPlugin = new ReactNativePlugin();
  // *** 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: [RNPlugin]
       // *** Add the Click Analytics plug-in. ***
       /* extensions: [RNPlugin, clickPluginInstance],
               extensionConfig: {
                   [clickPluginInstance.identifier]: clickPluginConfig
            } */
      }
  });
  appInsights.loadAppInsights();
  
  

• Plug-in de dispositivo manual React Native

  Para usar este plug-in, você deve desativar a coleta automática de informações do dispositivo ou usar sua própria classe de coleta de informações do dispositivo depois de adicionar a extensão ao seu código.

  1. Construa o plug-in e adicione-o como uma extension instância existente do Application Insights.

     import { ApplicationInsights } from '@microsoft/applicationinsights-web';
     import { ReactNativePlugin } from '@microsoft/applicationinsights-react-native';
     
     var RNMPlugin = new ReactNativePlugin();
     var appInsights = new ApplicationInsights({
         config: {
             instrumentationKey: 'YOUR_INSTRUMENTATION_KEY_GOES_HERE',
             extensions: [RNMPlugin]
         }
     });
     appInsights.loadAppInsights();
     

  2. Execute um dos seguintes procedimentos:

     • Desative a coleta automática de informações do dispositivo.

       import { ApplicationInsights } from '@microsoft/applicationinsights-web';
       
       var RNMPlugin = new ReactNativeManualDevicePlugin();
       var appInsights = new ApplicationInsights({
           config: {
               instrumentationKey: 'YOUR_INSTRUMENTATION_KEY_GOES_HERE',
               disableDeviceCollection: true,
               extensions: [RNMPlugin]
           }
       });
       appInsights.loadAppInsights();
       

     • Use sua própria classe de coleta de informações do dispositivo.

       import { ApplicationInsights } from '@microsoft/applicationinsights-web';
       
       // Simple inline constant implementation
       const myDeviceInfoModule = {
           getModel: () => "deviceModel",
           getDeviceType: () => "deviceType",
           // v5 returns a string while latest returns a promise
           getUniqueId: () => "deviceId",         // This "may" also return a Promise<string>
       };
       
       var RNMPlugin = new ReactNativeManualDevicePlugin();
       RNMPlugin.setDeviceInfoModule(myDeviceInfoModule);
       
       var appInsights = new ApplicationInsights({
           config: {
               instrumentationKey: 'YOUR_INSTRUMENTATION_KEY_GOES_HERE',
               extensions: [RNMPlugin]
           }
       });
       
       appInsights.loadAppInsights();
       

Configure uma instância do Application Insights no componente de entrada do seu aplicativo:

import { Component } from '@angular/core';
import { ApplicationInsights } from '@microsoft/applicationinsights-web';
import { AngularPlugin } from '@microsoft/applicationinsights-angularplugin-js';
// *** Add the Click Analytics plug-in. ***
// import { ClickAnalyticsPlugin } from '@microsoft/applicationinsights-clickanalytics-js';
import { Router } from '@angular/router';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.css']
})
export class AppComponent {
    constructor(
        private router: Router
    ){
        var angularPlugin = new AngularPlugin();
     // *** Add the Click Analytics plug-in. ***
     /* var clickPluginInstance = new ClickAnalyticsPlugin();
        var clickPluginConfig = {
          autoCapture: true
        }; */
        const appInsights = new ApplicationInsights({
            config: {
                connectionString: 'YOUR_CONNECTION_STRING_GOES_HERE',
                // *** If you're adding the Click Analytics plug-in, delete the next line. ***  
                extensions: [angularPlugin],
             // *** Add the Click Analytics plug-in. ***
             // extensions: [angularPlugin, clickPluginInstance],
                extensionConfig: {
                    [angularPlugin.identifier]: { router: this.router }
                 // *** Add the Click Analytics plug-in. ***
                 // [clickPluginInstance.identifier]: clickPluginConfig
                }
            } 
         });
        appInsights.loadAppInsights();
    }
}

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();

O React Native não rastreia as alterações do roteador, mas rastreia as visualizações de página.

O exemplo de código a seguir mostra como habilitar o rastreamento do histórico do roteador.

import { Component } from '@angular/core';
import { ApplicationInsights } from '@microsoft/applicationinsights-web';
import { AngularPlugin } from '@microsoft/applicationinsights-angularplugin-js';
import { Router } from '@angular/router';



@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.css']
})
export class AppComponent {
    constructor(
        private router: Router
    ){
        var angularPlugin = new AngularPlugin();
        const appInsights = new ApplicationInsights({ config: {
        connectionString: 'YOUR_CONNECTION_STRING',
        extensions: [angularPlugin],
        extensionConfig: {
            [angularPlugin.identifier]: { router: this.router }
        }
        } });
        appInsights.loadAppInsights();
    }
}

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 ReactPlugin instância criada para o aplicativo e um componente a ser processado 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.

O rastreamento de exceções não detetadas é habilitado por padrão. Se quiser desativar o rastreamento de exceções não detetadas, defina disableExceptionCollection como true.

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

var RNPlugin = new ReactNativePlugin();
var appInsights = new ApplicationInsights({
    config: {
        connectionString: 'YOUR_CONNECTION_STRING_GOES_HERE',
        disableExceptionCollection: true,
        extensions: [RNPlugin]
    }
});
appInsights.loadAppInsights();

Para rastrear exceções não detetadas, configure ApplicationinsightsAngularpluginErrorService em app.module.ts:

import { ApplicationinsightsAngularpluginErrorService } from '@microsoft/applicationinsights-angularplugin-js';

@NgModule({
  ...
  providers: [
    {
      provide: ErrorHandler,
      useClass: ApplicationinsightsAngularpluginErrorService
    }
  ]
  ...
})
export class AppModule { }

Encadeie mais manipuladores de exceção personalizados

Encadeie mais manipuladores de exceção personalizados quando quiser que o aplicativo manipule normalmente o que anteriormente seria uma exceção não tratada, mas ainda deseja relatar essa exceção como uma falha de aplicativo.

Para encadear mais manipuladores de exceção personalizados:

1. Crie manipuladores de exceção personalizados que implementam IErrorService.

   import { IErrorService } from '@microsoft/applicationinsights-angularplugin-js';
   
   export class CustomErrorHandler implements IErrorService {
       handleError(error: any) {
           ...
       }
   }
   

2. Passe a matriz errorServices através de extensionConfig.

   extensionConfig: {
           [angularPlugin.identifier]: {
             router: this.router,
             errorServices: [new CustomErrorHandler()]
           }
         }
   

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.

• Plug-in React Native: Além das informações do agente do usuário do navegador, que são coletadas pelo pacote da Web do Application Insights, o React Native também coleta informações do dispositivo. As informações do dispositivo são coletadas automaticamente quando você adiciona o plug-in.
• React Native Manual Device Plugin: Dependendo de como você configurou o plug-in quando adicionou a extensão ao seu código, este plug-in:
  • Não coleta informações do dispositivo
  • Usa sua própria classe de coleta de 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.

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);

Ele mede o tempo desde o evento até o ComponentDidMount ComponentWillUnmount 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 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.

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:

• 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.

Desativar a recolha automática de informações do dispositivo

Se não quiser recolher as informações do dispositivo, pode definir disableDeviceCollection como true.

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

var RNPlugin = new ReactNativePlugin();
var appInsights = new ApplicationInsights({
    config: {
        connectionString: 'YOUR_CONNECTION_STRING_GOES_HERE',
        disableDeviceCollection: true,
        extensions: [RNPlugin]
    }
});
appInsights.loadAppInsights();

Usar sua própria classe de coleta de informações do dispositivo

Se pretender substituir as informações do seu próprio dispositivo, pode utilizar myDeviceInfoModule para recolher as informações do seu próprio dispositivo.

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

// Simple inline constant implementation
const myDeviceInfoModule = {
    getModel: () => "deviceModel",
    getDeviceType: () => "deviceType",
    // v5 returns a string while latest returns a promise
    getUniqueId: () => "deviceId",         // This "may" also return a Promise<string>
};

var RNPlugin = new ReactNativePlugin();
RNPlugin.setDeviceInfoModule(myDeviceInfoModule);

var appInsights = new ApplicationInsights({
    config: {
        connectionString: 'YOUR_CONNECTION_STRING_GOES_HERE',
        extensions: [RNPlugin]
    }
});

appInsights.loadAppInsights();

Substituir as informações do dispositivo

Use a IDeviceInfoModule interface para abstrair como o plug-in pode acessar as informações do dispositivo. Esta interface é uma versão despojada da react-native-device-info interface e é fornecida principalmente para testes.

export interface IDeviceInfoModule {
    /**
     * Returns the Device Model
     */
    getModel: () => string;

    /**
     * Returns the device type
     */
    getDeviceType: () => string;

    /**
     * Returns the unique Id for the device. To support both the current version and previous
     * versions react-native-device-info, this may return either a `string` or `Promise<string>`.
     * When a promise is returned, the plugin will "wait" for the promise to `resolve` or `reject`
     * before processing any events. This WILL cause telemetry to be BLOCKED until either of these
     * states, so when returning a Promise, it MUST `resolve` or `reject`. Tt can't just never resolve.
     * There is a default timeout configured via `uniqueIdPromiseTimeout` to automatically unblock
     * event processing when this issue occurs.
     */
    getUniqueId: () => Promise<string> | string;
}

Se os eventos estão sendo "bloqueados" porque a via getUniqueId retornada Promise nunca é resolvida / rejeitada, você pode chamar setDeviceId() o plugin para "desbloquear" este estado de espera. Há também um tempo limite automático configurado via uniqueIdPromiseTimeout (padrão para 5 segundos), que irá chamar setDeviceId() internamente com qualquer valor configurado anteriormente.

N/A

Confira a demonstração do Application Insights React.

Atualmente indisponível.

Confira a demonstração do Application Insights Angular.