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

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

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

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

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

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

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

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

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

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

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

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

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

• Переопределение сведений об устройстве

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

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

npm install @microsoft/applicationinsights-react-js

• Подключаемый модуль 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 Manual

  Если вы используете React Native Expo, добавьте подключаемый модуль устройства React Native Manual вместо подключаемого модуля 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 Manual

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

  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 компонент появляется.

Отслеживание необученных исключений включено по умолчанию. Если вы хотите отключить отслеживание неухваченных исключений, установите для него значение disableExceptionCollection 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();

Чтобы отслеживать неуловимые исключения, настройте 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: в зависимости от того, как вы настроили подключаемый модуль при добавлении расширения в код, этот подключаемый модуль либо:
  • Не собирает сведения об устройстве
  • Использует собственный класс сбора сведений об устройстве

Сведения об устройстве, включая браузер, ОС, версию и язык, уже собираются веб-пакетом 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) метрики и разделения этой пользовательской метрики по Component Name.

Вы также можете выполнять пользовательские запросы , чтобы разделить данные 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 .
• имя события;
• Объект данных события, инкапсулирующий изменения, которые необходимо отслеживать.
• (необязательный) флаг 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.

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

Если вы не хотите собирать сведения об устройстве, можно задать значение disableDeviceCollection 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();

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

Если вы хотите переопределить данные собственного устройства, вы можете использовать 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.