Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/bluehalo/ngx-instrumentation

Helper components, classes, and services for instrumenting an Angular.io application
https://github.com/bluehalo/ngx-instrumentation

Last synced: about 1 month ago
JSON representation

Helper components, classes, and services for instrumenting an Angular.io application

Awesome Lists containing this project

README 

        
# @asymmetrik/ngx-instrumentation



[![Build Status][travis-image]][travis-url]



[travis-url]: https://travis-ci.org/Asymmetrik/ngx-instrumentation/

[travis-image]: https://travis-ci.org/Asymmetrik/ngx-instrumentation.svg



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



## Table of Contents

- [Install](#install)

- [Usage](#usage)

- [Structure](#structure)

- [Changelog](#changelog)

- [Contribute](#contribute)

- [License](#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.



```js

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:  



```js

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```.



```js

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:



```html



  ...

  

  

  ...



``` 



### 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:



```js

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:



```js

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.



```js

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.