@asymmetrik/ngx-instrumentation

Components, services, and classes to help instrument Angular.io applications

Table of Contents

• Install
• Usage
• Structure
• Changelog
• Contribute
• License

Install

Install the package and its peer dependencies via npm (or yarn):

npm install ngx-instrumentation

If you want to run the demo, clone the repository, perform an npm install, npm run demo and then go to http://localhost:4200

Usage

This library consists of an instrumentation service as well as several integrations. The instrumentation service handles "events" that are generated by the integrations.

Include the Instrumentation Module

The first step is to include the ngx-instrumentation module in your application.

import { InstrumentationModule } from '@asymmetrik/ngx-instrumentation';

...
imports: [
    ...
    InstrumentationModule.forRoot()
]
...

Configure An Instrumentation Service

Step two is to provide your desired instrumentation service to the application. You should do this in your application module to ensure the service is available to the entire application.

There are two instrumentation services included in this package: InstrumentationService and ServerInstrumentationService. InstrumentationService logs all events to the console, which is likely only useful in development and testing. ServerInstrumentationService submits all events to a configurable REST endpoint, which is useful if you want to log events to your server. If you would like to send events to a custom external service (e.g., Piwik, Google Analytics, etc.), you can provide your own service.

Instrumentation Service (Browser Console Logging only)

The default instrumentation service (InstrumentationService) logs events to the browser console and is only really useful for development and testing purposes. To use it, provide InstrumentationService as follows:

import { InstrumentationModule, InstrumentationService } from '@asymmetrik/ngx-instrumnetation';
...
providers: [
    ...
    InstrumentationService
]
...

Server Instrumentation Service (Server Logging)

For server-side logging of events, use the ServerInstrumentationService.

To configure this service, you must pass a factory method to the provider and use useFactory. This avoids a cyclical dependency and allows you to customize the REST endpoint for collecting the metrics. In the following example, the REST call will be a POST to api/metrics.

import { HttpBackend, HttpClientModule } from '@angular/common/http';
import { InstrumentationModule, InstrumentationService, ServerInstrumentationService } from '@asymmetrik/ngx-instrumentation';

@NgModule({
  ...
  imports: [
  	...
    HttpClientModule,
    InstrumentationModule,
    ...
  ],
  providers: [
  	...
    { provide: InstrumentationService, useFactory: serverInstrumentationServiceFactory, deps: [ HttpBackend ] },
    ...
  ],
  ...
})
export class AppModule { }

export function serverInstrumentationServiceFactory(httpBackend: HttpBackend) {
	const svc = new ServerInstrumentationService(httpBackend);
	svc.url = '/api/metrics';

	return svc;
}

Custom Service

To use your own custom service, configuration would be similar to that of ServerInstrumentationService. The actual service should extend the InstrumentationService class.

Configure Integrations

Once the instrumentation service is configured, you need to set up the integrations that will generate metrics. Currently, the plugin contains the following integrations:

• Router Event Handler
• Global Error Handler
• HTTP Interceptor

Router Event Handler

This integration listens to Router events and passes them to the instrumentation service, including the previous and current route information. It is implemented as a component that needs to be placed in the application template. See the following example:

<section class="container">
  ...
  <!-- Insert the following component into your application template -->
  <routerInstrumentation></routerInstrumentation>
  ...
</section>

Global Error Handler

This integration captures handles errors generated by the application and passes them to the instrumentation service. To configure it, you have to provide the InstrumentErrorHandler to the application as follows:

import { ErrorHandler, NgModule } from '@angular/core';
import { InstrumentationModule, InstrumentErrorHandler } from '@asymmetrik/ngx-instrumentation';

@NgModule({
  ...
  providers: [
    { provide: ErrorHandler, useClass: InstrumentErrorHandler }
    ...
  ],
  ...
})
export class AppModule { }

Note: The global error handler will handle all Angular zone errors. To help with development (and to ensure that errors aren't ignored), the plugin still logs errors to the client error console. To disable this and hide all Angular errors from the client, you can configure the InstrumentErrorHandler using useFactory as follows:

import { ErrorHandler, NgModule } from '@angular/core';
import { InstrumentationModule, InstrumentErrorHandler, InstrumentationService } from '@asymmetrik/ngx-instrumentation';

@NgModule({
  ...
  providers: [
  	...
    { provide: ErrorHandler, useFactory: errorHandlerFactory, deps: [ InstrumentationService ] },
    ...
  ],
  ...
})
export class AppModule { }

export function errorHandlerFactory(instrumentationService: InstrumentationService) {
	const handler = new InstrumentErrorHandler(instrumentationService);
	handler.logErrorsToConsole = true;

	return handler;
}

HTTP Interceptor

This integration captures all HTTP calls made in the application. Excludes parameters and body info by default (so it doesn't log sensitive information like passwords). You can override the config by using useFactory like how you do for the ServerInstrumentationService. To configure it, you have to provide the Instrument HTTP interceptor.

import { HTTP_INTERCEPTORS, HttpClient, HttpClientModule } from '@angular/common/http';
import { InstrumentationModule, InstrumentHttpInterceptor } from '@asymmetrik/ngx-instrumentation';

@NgModule({
  ...
  imports: [
  	...
    HttpClientModule,
    InstrumentationModule,
    ...
  ],
  providers: [
    HttpClient,
    { provide: HTTP_INTERCEPTORS, useClass: InstrumentHttpInterceptor, multi: true },
    ...
  ],
  ...
})
export class AppModule { }

Changelog

1.0.0

• Angular 7
• Started using the HtmlWebpackPlugin to generate the index.html file in the dist dir, so you don't need to add /src/demo to the end of the URL to hit the demo.

Contribute

PRs accepted. If you are part of Asymmetrik, please make contributions on feature branches off of the develop branch. If you are outside of Asymmetrik, please fork our repo to make contributions.

License

See LICENSE in repository for details.