react-appinsights

Javascript library to integrate Application Insights in applications built with React.
react-appinsights extends Application Insights with additional React-specific features:

tracking of router changes
React components usage statistics
API to extend the standard telemetry with additional dimensions

Installation

Using npm:

npm install --save react-appinsights

Usage

To initialize Application Insights add the following to the entry point file of your application (e.g. index.js):

import { ReactAI } from "react-appinsights";
ReactAI.initialize({ instrumentationKey: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx" });

See this Application Insights tutorial for Node.js for more details on how to obtain the instrumentation key.

In addition to instrumentationKey, IReactAISettings has following non-mandatory configuration options:

interface IReactAISettings {
  initialContext?: { [key: string]: any }; // Initial context to initialize with
  history?: History; // React router history - to enable page view tracking
  debug?: boolean; // Debug mode: displays debug messages from ReactAI in console
}

Track router changes

To track page views, pass a history object to the init method.
For more information see the documentation of the react-router package.

import ReactAI from "react-appinsights";
import { Router } from "react-router-dom";
import { createBrowserHistory } from "history";

const history = createBrowserHistory();
ReactAI.init({ instrumentationKey: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx", history: history });

ReactDOM.render(
  <Router history={history}>
    <App />
  </Router>,
  document.getElementById("root")
);

Enable React components usage tracking

To enable React components usage tracking, apply the withAITracking higher-order component function.

import { withAITracking } from 'react-appinsights';

class MyComponent extends React.Component {
    ...
}

export default withAITracking(MyComponent);

To change the name string of the component that appears in Application Insights, you can pass a custom name as second argument of withAITracking.

export default withAITracking(MyComponent, "CustomMyComponentName");

It will measure time from the ComponentDidMount event through the ComponentWillUnmount event. However, in order to make this more accurate, it will subtract the time in which the user was idle. In other words, React Component Engaged Time = ComponentWillUnmount timestamp - ComponentDidMount timestamp - idle time.

To see this metric in the Azure portal you need to navigate to the Application Insights resource, select "Metrics" tab and configure the empty charts to display Custom metric named "React Component Engaged Time (seconds)", select aggregation (sum, avg, etc.) of your liking and apply split by "Component Name".

You can also run custom queries to slice and dice AI data to generate reports and visualizations as per your requirements. In the Azure portal, navigate to the Application Insights resource, select "Analytics" from the top menu of the Overview tab and run your query.

Please note that it can take up to 10 minutes for new custom metric to appear in the Azure Portal.

Set application context

To augment all telemetry with additional properties use setContext method. For instance:

ReactAI.setContext({ CorrelationId: "some-unique-correlation-id", Referrer: document.referrer });

This will add CorrelationId and Referrer property to all page views, ajax calls, exceptions and other telemetry sent to Application Insights.

Get original AppInsights object

Use the following method to get the original AppInsights object:

var appInsights = ReactAI.rootInstance;

Refer to this doc for information on the Javascript API of Application Insights.

Advanced configuration

The initialization function is an intersection type made of IReactAISettings & IConfiguration & IConfig - with IReactAISettings provided by the ReactAI library and rest of the configuration provided by Application Insights.

Essentially, instrumentationKey is the only mandatory configuration option but initialization with intersection type allows you to leverage features of both libraries, as in the following example:

ReactAI.initialize({
  // ReactAI config
  instrumentationKey: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx",
  debug: true,
  history: history,
  // AI specific config
  disableCorrelationHeaders: false,
  disableFetchTracking: false,
  enableCorsCorrelation: true,
  isCookieUseDisabled: true
});

pviotti / react-appinsights