angular-applicationinsights

An implementation of Microsoft Application Insights as a 100% AngularJS module. This module does not utilize the offical Application Insights Javascript SDK, in order to avoid depending on global code outside of the AngularJS platform scope.

Getting Started

Prerequisites

• A Microsoft Application Insights Instrumentation Key:
  • This can be obtained from https://portal.azure.com, and registering an Application Insights resource.
  • A guide based on the latest portal update : Obtaining An Application Insights Instrumentation Key

###Installation

####Via Package

Bower

bower install angular-applicationinsights

NPM

npm i angular-applicationinsights

Nuget

Install-Package angular-applicationinsights

####From Source

> git clone https://github.com/VladimirRybalko/angular-applicationinsights.git
> cd angular-applicationinsights
> npm install
> grunt

Note: the angular-applicationinsights.js file will be in the build/ folder after running grunt.

###Setup

Add a reference to the angular-applicationinsights.js file in your main html file:

   <!-- load angular and angular routes via CDN -->
   <script src="https://ajax.googleapis.com/ajax/libs/angularjs/1.3.10/angular.js"></script>
   <script src="https://ajax.googleapis.com/ajax/libs/angularjs/1.3.10/angular-route.js"></script>
	<!-- load application insights after the angular script, but before your main application module -->
   <script src="build/angular-applicationinsights.js"></script>
   <script language="javascript">
		var amazingApp = angular.module('amazingApp', ['ApplicationInsightsModule']);
   </script>

Configure the provider during your application module's config phase:

<script language="javascript">
	var amazingApp = angular.module('amazingApp', ['ApplicationInsightsModule']);

	amazingApp.config(function(applicationInsightsServiceProvider){
		var options = { applicationName:'amazingApp' };
		// Configuration options are described below 	 
        applicationInsightsServiceProvider.configure('<PUT YOUR APPLICATION INSIGHTS KEY HERE', options );
    });
 </script>

Basic automatic telemetry will be gathered out of the box, but for a direct reference inject the applicationInsightsService into your code:

	amazingApp.controller('mainController',['applicationInsightsService',function(applicationInsightsService){
	applicationInsightsService.trackEvent('An amazing Event happened');
}]);

###Configuration The options object passed to the configure( iKey, options ) has a number of valid settings. Their names and default values are as follows:

var options = {
	// applicationName: used as a 'friendly name' prefix to url paths
	// ex: myAmazingapp/mainView
	applicationName:'',
	// autoPageViewTracking: enables the sending a event to Application Insights when 
	// ever the $locationChangeSuccess event is fired on the rootScope
	autoPageViewTracking: true,
	// autoStateChangeTracking: enables the sending a event to Application Insights when 
	// ever the $stateChangeSuccess event is fired on the rootScope. To enable 'autoPageViewTracking' option should be set too. 
	autoStateChangeTracking: false,
	// autoLogTracking: enables the interception of calls to the $log service and have the trace 
	// data sent to Application Insights.
	autoLogTracking: true,
	// autoExceptionTracking: enables calls to the $exceptionHandler service, usually unhandled exceptions, to have the error and stack data sent to Application Insights.
	autoExceptionTracking: true,
	// sessionInactivityTimeout: The time (in milliseconds) that a user session can be inactive, before a new session will be created (on the next api call). Default is 30mins.
	sessionInactivityTimeout: 1800000,
	// developerMode: Makes the service not post anything to AI but print it to the console instead
	developerMode: false
	};
	

API Reference

trackEvent

Sends a custom event to Application Insights.

// name(String) : Required - the name of the event to be shown in reports.
// properties (Hash) : Optional - a String/String hash object of properties to associate with this event.
// metrics (Hash) : Optional - a String/Number hash object of metrics to associate with this event.

 applicationInsightsService.trackEvent( name, properties, metrics );

trackException

Sends error data to Application Insights.

// exception (Error) : Required - the error object to be processed.
// properties (Hash): Optional - a String/String hash object of properties to associate with this exception

 applicationInsightsService.trackException(exception, properties);

Note: if the autoExceptionTracking option is enabled, this method will be called any time the $exceptionHandler is invoked.

	try
	{
		// z is undefined.
		1 + z;
	}
	catch(e)
	{
		// this will call trackException. Unhandled exceptions will be caught by angularJS and directed to the $exceptionHandler.
		$exceptionHandler(e);
	}

trackMetric

Sends a metric consisting of a name/value pair to Application Insights

// name(String) : Required - the name of the Metric.
// value (Number) : Required -  the value of the metric.
// properties (Hash) : Optional - a String/String hash object of properties to associate with this metric.


 applicationInsightsService.trackMetric( name, value, properties );

trackPageView

Sends telemetry data to Application Insights signifying a view change has occured.

// viewName (String) : Optional - the name of the Page/View to be shown in reports. Defaults to the url path, prefixed with the app name (ex: amazingApp/view2).
// url (String) : Optional - The full url to associate with this view. Defaults to $location.absUrl();
// properties (Hash) : Optional - a String/String hash object of properties to associate with this event.
// metrics (Hash) : Optional - a String/Number hash object of metrics to associate with this event.

 applicationInsightsService.trackPageView( viewName , url, properties, metrics );

This method is invoked automatically any time the $locationChangeSuccess event is fired, and the autoTrackPageviews configuration option is enabled.

trackTraceMessage

Sends a trace log message to Application Insights.

// message (String) : Required - The log message to send to Application Insights.
// severity (String) : Optional - The message severity Level (debug,info,warn, error). Defaults to 'info'. 
// properties (Hash) : Optional - a String/String hash object of properties to associate with this event.

 applicationInsightsService.trackTraceMessage( message, severity, properties);

If the autoLogTracking option is enabled, trackTraceMessage will be called any time one of the $log service methods are called.

// trackTraceMessage will be invoked with a value of 'message' and 'info' as the parameters.
 $log.info('message');

defineUser

Define a new user metadata.

// userId (Guid) : Required - The user unique identifier.
 applicationInsightsService.defineUser( userId );

defineSession

Define a new session identifier of Application Insights.

// sessionId (Guid) : Required - The session identifier.
 applicationInsightsService.defineSession( sessionId );

defineDevice

Define a new device metadata.

// id (Guid) : Required - The device unique identifier.
// type (String) : Required - The device type.
 applicationInsightsService.defineDevice( id, type );