다음을 통해 공유

Application Insights JavaScript SDK에 대한 프레임워크 확장 사용

핵심 SDK 외에도 React 플러그 인, React Native 플러그 인 및 Angular 플러그 인과 같은 특정 프레임워크에 사용할 수 있는 플러그 인도 있습니다.

이러한 플러그 인은 추가 기능과 특정 프레임워크와의 통합을 제공합니다.

필수 조건

플러그 인은 무엇을 사용하도록 설정하나요?

Application Insights JavaScript SDK에 대한 React 플러그 인은 다음을 지원합니다.

  • 라우터 기록 추적
  • 예외 추적
  • 구성 요소 사용량 추적
  • React 컨텍스트에서 Application Insights 사용

플러그 인 추가

플러그 인을 추가하려면 이 섹션의 단계를 수행합니다.

패키지 설치


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

코드에 확장 추가

참고

2025년 3월 31일에 계측 키 수집에 대한 지원이 종료됩니다. 계측 키 수집은 계속 작동하지만 더 이상 기능에 대한 업데이트 또는 지원을 제공하지 않습니다. 연결 문자열로 전환하여 새로운 기능을 활용합니다.

Application Insights에 대한 연결을 초기화합니다.

참고

기록 버전 5 이상을 사용하는 경우 createBrowserHistory에서 basename 옵션이 더 이상 지원되지 않습니다.

const browserHistory = createBrowserHistory({ basename: '' }); 대신 const browserHistory = createBrowserHistory();를 사용하세요.

사용 중인 기록 버전을 확인하려면 다음을 실행 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();

(선택 사항) Click Analytics 플러그 인 추가

Click Analytics 플러그 인을 추가하려는 경우:

  1. Click Analytics의 줄 주석 처리를 제거합니다.

  2. 추가하는 플러그 인에 따라 다음 중 하나를 수행합니다.

    • React의 경우 extensions: [reactPlugin],을 삭제합니다.
    • React Native의 경우 extensions: [RNPlugin]을 삭제합니다.
    • Angular의 경우 extensions: [angularPlugin],을 삭제합니다.

  3. 설치 프로세스를 계속하려면 Click Analytics 플러그 인 사용을 참조하세요.

구성

이 섹션에서는 Application Insights JavaScript SDK의 프레임워크 확장에 대한 구성 설정을 설명합니다.

라우터 기록 추적

이름 유형 필수 여부 기본값 설명
역사 객체 선택 사항 널 라우터 기록을 추적합니다. 자세한 내용은 React 라우터 패키지 설명서를 참조하세요.

라우터 기록을 추적하기 위해 대부분의 사용자는 enableAutoRouteTracking에서 필드를 사용할 수 있습니다. 이 필드는 history 개체와 동일한 페이지 보기에 대한 데이터를 수집합니다.

구성이 수신 대기하는 브라우저 URL을 업데이트하지 않는 라우터 구현을 사용하는 경우 history 개체를 사용합니다. 여러 페이지 보기 이벤트가 발생하므로 enableAutoRouteTracking 필드와 history 개체를 모두 사용하도록 설정해서는 안 됩니다.

다음 코드 예제에서는 enableAutoRouteTracking 필드를 활성화하는 방법을 보여 줍니다.

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

예외 추적

React 오류 경계는 React 애플리케이션 내에서 발생할 때 catch되지 않은 예외를 적절하게 처리하는 방법을 제공합니다. 이러한 예외가 발생하면 예외를 기록해야 할 수 있습니다. Application Insights에 대한 React 플러그 인은 발생하는 예외를 자동으로 기록하는 오류 경계 구성 요소를 제공합니다.

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 구성 요소가 나타납니다.

디바이스 정보 수집

브라우저, OS, 버전 및 언어를 포함하는 디바이스 정보는 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합니다.

구성 요소 이름별로 분할된 사용자 지정 메트릭 React 구성 요소 작동 시간(초)을 표시하는 차트를 보여주는 스크린샷

사용자 지정 쿼리를 실행하여 Application Insights 데이터를 분할하여 요구 사항에 따라 보고서 및 시각화를 생성할 수도 있습니다. 다음은 사용자 지정 쿼리의 예입니다. 계속 진행하여 쿼리 편집기에 직접 붙여넣어 테스트합니다.

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

새 사용자 지정 메트릭이 Azure Portal에 표시되는 데 최대 10분이 걸릴 수 있습니다.

React 컨텍스트에서 Application Insights 사용

개별 구성 요소에 대한 변경 내용 추적을 사용자 지정할 수 있도록 일반적인 후크를 제공합니다. 또는 구성 요소의 변경 내용을 추적하기 위해 제공하는 미리 정의된 연락처인 useTrackMetric 또는 useTrackEvent를 사용할 수 있습니다.

Application Insights용 React Hooks는 React Context를 포함하는 측면으로 사용하도록 설계되었습니다. 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>
    );
};

이 Context Provider는 Application Insights를 모든 자식 구성 요소 내에서 useContext Hook로 사용할 수 있도록 합니다.

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 Hook는 구성 요소 구조에 다른 구성 요소를 추가하지 않고도 withAITracking 고차 구성 요소의 기능을 복제합니다. Hook는 두 가지 인수를 사용합니다.

  • useAppInsightsContext Hook에서 가져올 수 있는 Application Insights 인스턴스입니다.
  • 추적할 구성 요소의 식별자, 예를 들어 그 이름과 같은 식별자입니다.
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;

고차 구성 요소처럼 작동하지만 구성 요소 수명 주기가 아닌 Hooks 수명 주기 이벤트에 응답합니다. 특정 상호 작용에서 실행해야 하는 경우 사용자 이벤트에 Hook를 명시적으로 제공해야 합니다.

useTrackEvent (유즈트랙이벤트)

useTrackEvent Hook를 사용하여 단추 클릭 또는 기타 API 호출과 같이 애플리케이션에서 추적해야 할 수 있는 사용자 지정 이벤트를 추적할 수 있습니다. 다음 4개의 인수를 사용합니다.

  • useAppInsightsContext Hook에서 가져올 수 있는 Application Insights 인스턴스입니다.
  • 이벤트의 이름
  • 추적해야 하는 변경 내용을 캡슐화하는 이벤트 데이터 개체입니다.
  • 초기화 시 trackEvent 호출을 건너뛰기 위한 skipFirstRun(선택 사항) 플래그. Hook가 아닌 버전이 작동하는 방식을 좀 더 비슷하게 모방하도록 기본값은 true로 설정됩니다. useEffect Hooks를 사용하면 값의 초기 설정을 포함하여 각 값이 업데이트될 때마다 효과가 트리거됩니다. 따라서 추적이 너무 일찍 시작되어 잠재적으로 원하지 않는 이벤트가 추적됩니다.
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;

Hook를 사용하면 데이터 페이로드가 제공되어 Application Insights에 저장될 때 이벤트에 더 많은 데이터를 추가할 수 있습니다.

샘플 앱

Application Insights React 데모를 확인하세요.

다음 단계