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
Using npm:
npm install --save react-appinsights
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
}
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")
);
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.
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.
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.
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
});