Включить расширение фреймворка для JavaScript SDK для Application Insights

• Убедитесь, что версия подключаемого модуля React, которую вы хотите установить, совместима с версией Application Insights. Дополнительные сведения см. в разделе "Матрица совместимости" для подключаемого модуля React.

• Вы должны использовать версию > >= 2.0.0 @microsoft/applicationinsights-web. Этот плагин работает только в приложениях на базе react-native. Он не работает с приложениями, использующими платформу Expo или Create React Native App, который основан на платформе Expo.

• Подключаемый модуль Angular НЕ совместим с ECMAScript 3 (ES3).
• При добавлении поддержки новой версии Angular наш пакет npm становится несовместимым с версиями Angular нижнего уровня. Продолжайте использовать старые пакеты npm, пока не будете готовы обновить версию Angular.

Подключаемый модуль React для JavaScript SDK Application Insights позволяет:

• Отслеживание журнала маршрутизаторов
• Отслеживание исключений
• Отслеживание использования компонентов
• Использование Application Insights с контекстом React

Подключаемый модуль React Native для пакета SDK JavaScript для Application Insights позволяет:

• Отслеживание исключений

• Сбор сведений об устройстве

  По умолчанию этот подключаемый модуль автоматически собирает следующее:

  • Уникальный идентификатор устройства (также известный как идентификатор установки).
  • Имя модели устройства (например, iPhone XS, Samsung Galaxy Fold, Huawei P30 Pro и т. д.)
  • Тип устройства (например, телефонная трубка, планшетный ПК и т. д.)

• Отключение автоматической коллекции сведений об устройстве

• Использование собственного класса сбора сведений об устройстве

• Изменить сведения об устройстве

Плагин Angular для набора программных средств разработки на JavaScript от Application Insights позволяет:

• Отслеживание журнала маршрутизаторов
• Отслеживание исключений
• Связывание большего количества пользовательских обработчиков исключений

npm install @microsoft/applicationinsights-react-js @microsoft/applicationinsights-web

• Плагин React Native

  Плагин React Native по умолчанию зависит от react-native-device-info пакета. Необходимо установить и связаться с этим пакетом. Держите пакет react-native-device-info в актуальном состоянии, чтобы собирать последние названия устройств с помощью вашего приложения.

  С версии 3 поддержка доступа к DeviceInfo была абстрагирована в интерфейс IDeviceInfoModule , чтобы разрешить использовать или задать собственный модуль сведений об устройстве. В этом интерфейсе используются те же имена функций и результат 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
  
  

• Управляемый вручную подключаемый модуль устройства для React Native

  Если вы используете React Native Expo, добавьте плагин React Native Manual Device вместо плагина React Native. Плагин React Native использует пакет react-native-device-info package, который не поддерживается в React Native Expo.

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

npm install @microsoft/applicationinsights-angularplugin-js

Инициализируйте подключение к 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();

• Плагин React Native

  Чтобы использовать этот подключаемый модуль, необходимо его создать и добавить в качестве extension в существующий экземпляр 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();
  
  

• Управляемый вручную подключаемый модуль устройства для React Native

  Чтобы использовать этот подключаемый модуль, необходимо отключить автоматическую коллекцию сведений об устройстве или использовать собственный класс сбора сведений об устройстве после добавления расширения в код.

  1. Создайте плагин и добавьте его в существующий экземпляр extension 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. Выполните одно из следующих действий:

     • Отключите автоматическую коллекцию сведений об устройстве.

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

     • Используйте собственный класс сбора сведений об устройстве.

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

Настройте экземпляр Application Insights в входном компоненте в вашем приложении.

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

В следующем примере кода показано, как включить enableAutoRouteTracking поле.

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

React Native не отслеживает изменения маршрутизатора, но отслеживает просмотры страниц.

В следующем примере кода показано, как включить отслеживание журнала маршрутизаторов.

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

Границы ошибок React предоставляют способ адекватно обрабатывать необработанное исключение, когда оно возникает в приложении React. При возникновении такого исключения, скорее всего, необходимо регистрировать исключение. Подключаемый модуль React для Application Insights предоставляет компонент границ ошибки, который автоматически регистрирует исключение при возникновении.

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

Требуется передать в AppInsightsErrorBoundary два свойства. Они являются экземплярами, созданными ReactPlugin для приложения, и компонентами, которые будут отображаться при возникновении исключения. При возникновении необработанного исключения функция trackException вызывается с информацией, предоставленной в границу ошибки, и компонент onError появляется.

Отслеживание необученных исключений включено по умолчанию. Если вы хотите отключить отслеживание неухваченных исключений, установите для него значение disableExceptionCollectiontrue.

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

Чтобы отслеживать неуловимые исключения, настройте ApplicationinsightsAngularpluginErrorService в app.module.ts:

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

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

Цепочка дополнительных пользовательских обработчиков исключений

Когда вам нужно добавить больше пользовательских обработчиков исключений, чтобы приложение могло корректно обрабатывать то, что ранее являлось необработанным исключением, но при этом вы все же хотите сообщить об этом исключении как о сбое приложения.

Чтобы связать дополнительные пользовательские обработчики исключений:

1. Создайте настраиваемые обработчики исключений, реализующие IErrorService.

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

2. Передайте массив errorServices через extensionConfig.

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

Сведения об устройстве, включая браузер, ОС, версию и язык, уже собираются веб-пакетом Application Insights.

• Плагин React Native: помимо сведений, собираемых веб-пакетом Application Insights из браузера об агенте пользователя, React Native также собирает информацию об устройстве. Сведения об устройстве автоматически собираются при добавлении подключаемого модуля.
• Плагин React Native для ручных устройств: в зависимости от того, как вы настроили плагин при добавлении расширения в код, этот плагин либо:
  • Не собирает сведения об устройстве
  • Использует собственный класс сбора сведений об устройстве

Сведения об устройстве, включая браузер, ОС, версию и язык, уже собираются веб-пакетом Application Insights.

Отслеживание использования компонентов

Функция, уникальная для подключаемого модуля React, заключается в том, что вы можете инструментировать определенные компоненты и отслеживать их по отдельности.

Чтобы снабдить компоненты React отслеживанием использования, примените функцию более высокого порядка withAITracking. Чтобы включить Application Insights для компонента, оберните 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);

Он измеряет время от ComponentDidMount события до ComponentWillUnmount события. Чтобы сделать результат более точным, он вычитает время, в течение которого пользователь бездействовал, с помощью React Component Engaged Time = ComponentWillUnmount timestamp - ComponentDidMount timestamp - idle time.

Изучение данных

Используйте обозреватель метрик Azure Monitor для построения диаграммы по пользовательскому названию метрики React Component Engaged Time (seconds) и разбиения этой пользовательской метрики по .

Вы также можете выполнять пользовательские запросы , чтобы разделить данные Application Insights для создания отчетов и визуализаций в соответствии с вашими требованиями. Ниже приведен пример пользовательского запроса. Перейдите вперед и вставьте его непосредственно в редактор запросов, чтобы проверить его.

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

Для отображения новых пользовательских метрик в портал Azure может потребоваться до 10 минут.

Использование Application Insights с контекстом React

Мы предоставляем общие крючки, позволяющие настроить отслеживание изменений для отдельных компонентов. Кроме того, можно использовать useTrackMetric или useTrackEvent, которые являются предварительно определенными контактами, которые предоставляются для отслеживания изменений компонентов.

Хуки React для Application Insights предназначены для использования контекста React в качестве контейнера. Чтобы использовать Context, инициализируйте Application Insights и импортируйте объект 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>
    );
};

Этот поставщик контекста делает доступным Application Insights как useContext хук во всех его дочерних компонентах.

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

Хук useTrackMetric воспроизводит функциональность компонента более высокого порядка withAITracking, без добавления другого компонента в структуру компонента. Хук принимает два аргумента:

• Экземпляр Application Insights, который можно получить из хука useAppInsightsContext.
• Идентификатор компонента для отслеживания, например его имя.

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;

Он работает как компонент более высокого порядка, но вместо этого реагирует на события жизненного цикла хуков, а не на жизненный цикл компонента. Если необходимо запустить определенные взаимодействия, хук должен быть явно предоставлен для пользовательских событий.

useTrackEvent

Используйте перехватчик useTrackEvent для отслеживания любого настраиваемого события, которое может потребоваться приложению, например, нажатие кнопки или другой вызов API. Он принимает четыре аргумента:

• Экземпляр Application Insights, который можно получить из useAppInsightsContext Hook.
• имя события;
• Объект данных события, инкапсулирующий изменения, которые необходимо отслеживать.
• (необязательный) флаг skipFirstRun для пропуска вызова trackEvent при инициализации. Значение по умолчанию установлено на true, чтобы более точно имитировать поведение версии без перехватчика. При использовании useEffect хуков эффект активируется при каждом обновлении значения, включая начальную установку значения. В результате отслеживание начинается слишком рано, что приводит к отслеживанию потенциально нежелательных событий.

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;

При использовании хука можно предоставить нагрузку данных, чтобы добавить данные в событие при его сохранении в Application Insights.

Отключение автоматической коллекции сведений об устройстве

Если вы не хотите собирать сведения об устройстве, можно задать значение disableDeviceCollectiontrue.

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

Использование собственного класса сбора сведений об устройстве

Если вы хотите изменить данные вашего устройства, вы можете использовать myDeviceInfoModule для сбора информации о нем.

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

Изменить сведения об устройстве

Используйте интерфейс IDeviceInfoModule, чтобы абстрагировать, как плагин может получить доступ к информации об устройстве. Этот интерфейс является отрезаной версией react-native-device-info интерфейса и в основном предоставляется для тестирования.

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

Если события оказываются "заблокированными", так как Promise, возвращенный через getUniqueId, никогда не разрешается или отклоняется, можно вызвать setDeviceId() на плагине для разблокировки этого состояния ожидания. Также настроено автоматическое время ожидания через uniqueIdPromiseTimeout (по умолчанию — 5 секунд), которое будет внутренне вызывать setDeviceId() с любым ранее настроенным значением.

Н/П

Ознакомьтесь с демонстрацией React для Application Insights.

В настоящее время недоступно.

Ознакомьтесь с демонстрацией Application Insights Angular.