sigao-ng-application-insights v0.0.1

SigaoNgApplicationInsights

This library is provides an Angular service to interact with Microsoft's Application Insights service.

Usage

Install the package

Run npm install sigao-ng-application-insights

Import the module

Place the following in your app imports

import { SigaoNgApplicationInsightsModule } from 'sigao-ng-application-insights';

@NgModule({
  declarations: [
    AppComponent,
  ],
  imports: [
    BrowserModule,
    SigaoNgApplicationInsightsModule.forRoot({
    
      // [Required] Enables logging to Application Insights
      enabled: true,

      // [Required] When true, automatically interceps and logs all errors to Application Insights
      interceptErrors: true,

      // [Optional] Configuration for application insights.  Can be set in module definition or at app start
      appInsightsConfig: {
        instrumentationKey: 'your_key_here'
      },

      // [Optional] Properties to be appended to every logging event's properties.
      globalProperties: {
        appVersion: '1.0.0'
      }
    })
  ],
  providers: [],
  bootstrap: [AppComponent]
})

Configuration property: enabled

This flag enables/disables the service. Logging events made with this flag set to false will do nothing. Typically, this flag would be set to "false" for development environments and changed to "true" in production.

Configuration property: interceptErrors

This flag enables/disables automatic error intercepting. If true, all errors captured by Angular's error handling mechanism will be reported to Application Insights.

Configuration property: appInsightsConfig

This object represents Microsoft's configuration for Application Insights. A detailed description of this object can be found here. If your App Insights configuration relies on an external configuration source, you may need to wait until the application loads before initializing the service. If that is the case, do not include the this property and instead use the "initAppInsights" function in the SigaoNgApplicationInsightsService.

Configuration property: globalProperties

This object will be merged with any properties included in a logging event. Global properties will be included even if no logging properties are provided to a logging event.

Using the service

Once the module is included, all you need to do is inject the service. Once injected you will be able to use logging functions as defined here.

import { SigaoNgApplicationInsightsService } from 'sigao-ng-application-insights';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.scss']
})
export class AppComponent {
  constructor(public aiService: SigaoNgApplicationInsightsService) {
  
  	  // Example
      this.aiService.trackPageView('app_root_page');
  }
}

Initializing Application Insights after app load

As mentioned above, certain circumstances may force you to wait until after app load to initialize the service. If this is the case, both appInsightsConfig" and "globalProperties" should not be included in the module definition. Instead, they can be added directly by the service:

import { SigaoNgApplicationInsightsService } from 'sigao-ng-application-insights';
import { Component } from '@angular/core';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.scss']
})
export class AppComponent {

  constructor(public aiService: SigaoNgApplicationInsightsService) {
   
    this.aiService.initAppInsights(
      { instrumentationKey: 'your_key_here' },  // appInsightsConfig
      { appVersion: '1.0.0' })                  // globalProperties
      .then(ai => {
        console.log('AI Loaded!');
      });
  }
}

Accessing Application Insights object directly

If needed, the Application Insights object can be accessed directly via this.aiService.ai

Sigao Usage Disclaimer

This package (along with other "Sigao" marked packages) is designed to be used within our tech stack to support our development efforts. While significant effort has been made to ensure that these packages are tested and maintained, mistakes happen, and there is a good possibility the bug won't be addressed unless it directly impacts our specific use case.

If you encounter a bug that you'd like addressed, feel free to reach out to us and we'll see what we can do!