@gibraltarsoftware/loupe-angular

loupe-angular

@gibraltarsoftware/loupe-angular is a wrapper for the Loupe TypeScript Agent, providing logging and error handling capabilities for your Angular applications.

The module automatically creates a Loupe client logger and provides a sample Angular ErrorHandler that can be enabled by configuring your application providers; this enables any uncaught errors in your Angular application to be logged to Loupe. It additionally exposes the Loupe Agent to your Angular application as an injectable service named LoupeService.

Installation

You can install the module via npm. The version you install should be the same as the major version of your Angular project, as the loupe-angular library tracks the major versions of Angular. So if you are using the latest version of Angular, you can just use the following NPM command to install the latest version of the loupe-angular library:

npm install @gibraltarsoftware/loupe-angular

If you are using a previous version of Angular, for example, version 9, then you should install the explicit loupe-angular version:

npm install @gibraltarsoftware/loupe-angular@9.0.0

For Angular 10, use @gibraltarsoftware/loupe-angular@10.0.1

We do not publish a version of the loupe-angular library for unreleased and beta versions of Angular. If you are using these beta versions and wish to use Loupe for client logging, then you should clone this repository and manually import the source from the projects\loupe-angular\src\lib folder.

All Loupe client logging is designed to send log information to a server which handles logging to a Loupe server; please refer to the main documentation for references to the server logging portion, as installation and configuration depends upon your server.

Installation and Execution Steps

The following detail the exact steps required to enable Loupe logging in your Web applications.

1. Install Loupe

npm install @gibraltarsoftware/loupe-angular

2. Import the service into your main component (app.component.ts)

import { LoupeService } from '@gibraltarsoftware/loupe-angular';

3. Inject the service into your main component (app.component.ts)

  constructor(private readonly loupe: LoupeService) {
    ...
  }

4. Set the initial properties and call the Loupe methods:

  constructor(private readonly loupe: LoupeService) {
    // to set the Loupe target, if not the same domain or port
    this.loupe.setLogServer('https://mysite.com');

    // log a message
    this.loupe.information("WebClient", 'App Started', 'The client application has started');
  }

5. Configure the error handler in your application module (app.module.ts). This will use the Loupe error handler for any uncaught uncaught errors, log them to Loupe, and allow the existing Angular error handlers to also handle the error.

  providers: [
    { provide: ErrorHandler, useClass: LoupeErrorHandler }
  ]

6. Configure the interceptor in your application module (app.module.ts). This will automatically have the Loupe Session ID added as a header to all HTTP requests, which helps allow the server Loupe component to correlate requests.

  providers: [
    { provide: HTTP_INTERCEPTORS, useClass: LoupeHeaderHttpConfigInterceptor, multi: true }
  ]

With both the error handler and the interceptor configured, your providers section will be:

  providers: [
    { provide: ErrorHandler, useClass: LoupeErrorHandler },
    { provide: HTTP_INTERCEPTORS, useClass: LoupeHeaderHttpConfigInterceptor, multi: true }
  ]

7. Import the references for the new providers:

import { LoupeErrorHandler } from '@gibraltarsoftware/loupe-angular';
import { LoupeHeaderHttpConfigInterceptor } from '@gibraltarsoftware/loupe-angular';

You will also need to add references for ErrorHandler and HTTP_INTERCEPTORS; the first should be added alongside the import for NgModule, and the latter as a new import. So your imports should now include:

import { NgModule, ErrorHandler } from '@angular/core';
import { HTTP_INTERCEPTORS } from '@angular/common/http';

.NET Core and Angular

For a .NET Core Web Application using Angular, you need to install both the server and client components.

1. Install server component, a package Loupe.Agent.AspNetCore that can be installed via NuGet in the Visual Studio Package Manager, or from the command line:

dotnet add package Loupe.Agent.AspNetCore

2. Configure the server component to log to Loupe and to accept client requests. In Startup.cs**, add the following to the ConfigureServices method:

services.AddLoupe().AddClientLogging();

3. Add the following to the endpoint configuration, in the Configure method:

endpoints.MapLoupeClientLogger();

The endpoint configuration should now look like:

app.UseEndpoints(endpoints =>
{
    endpoints.MapControllerRoute(
        name: "default",
        pattern: "{controller}/{action=Index}/{id?}");

    endpoints.MapLoupeClientLogger();
});

4. Install the client package from NPM. The simplest way to do this is to right-mouse click on the ClientApp** folder and select Open in Terminal. Then from the terminal, install the NPM package:

npm install @gibraltarsoftware/loupe-angular

Note that this tracks the latest full release of Angular. If using the Angular Web Template in Visual Studio 2019 you will need to explicitly install the version 9 of the angular-loupe library, since the Visual Studio template uses Angular 9.

5. You can now import and use the service, starting in app.component.ts:

import { Component } from '@angular/core';
import { LoupeService } from '@gibraltarsoftware/loupe-angular';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html'
})
export class AppComponent {
  title = 'app';

  constructor(private readonly loupe: LoupeService) {
    this.loupe.information("WebClient", 'App Started', 'The application has started');
  }
}

When you run your application you will now see a message logged to Loupe; if you use the browser developer tools you can see a log pessage being sent to the server, and you can use Loupe Desktop to view the message in more detail.

Examples

You should set the log server (if applicable) as soon as your application starts. The AppComponent is a good place to do this.

import { LoupeService } from '@gibraltarsoftware/loupe-angular';

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

  constructor(private readonly loupe: LoupeService) {
    loupe.setLogServer('https://myserver.com');
  }
  
}

The setLogServer call should be used when your application is not hosted in that same domain or port as the server application that collects the logs. Note that your server application will need to support CORS for your client application.

Error Handlers

To use the error handler and HTTP interceptors, modify your app.module.ts and add the Loupe error handler as a provider for the Angular ErrorHandler.

  providers: [
    { provide: ErrorHandler, useClass: LoupeErrorHandler }
  ]

Remember to import the references for ErrorHandler and LoupeErrorHandler.

You can of course, create your own error handler to log uncaught errors to Loupe.

Correlating requests

To allow the Loupe server component to correlate requests, you can include the Loupe HTTP Interceptor in your providers, which will add the Loupe Agent and Session IDs to all HTTP requests.

  providers: [
    { provide: ErrorHandler, useClass: LoupeErrorHandler },
    { provide: HTTP_INTERCEPTORS, useClass: LoupeHeaderHttpConfigInterceptor, multi: true }
  ]

Remember to import the references for HTTP_INTERCEPTORS and LoupeHeaderHttpConfigInterceptor.

Service Usage

In other components you follow the same injection pattern, by using the Loupe service:

import { LoupeService } from '@gibraltarsoftware/loupe-angular';

@Component({
  selector: 'app-first',
  templateUrl: './first.component.html',
  styleUrls: ['./first.component.css']
})
export class FirstComponent implements OnInit {

  constructor(
    private readonly LoupeService: LoupeService
  ) { }

  ngOnInit(): void {
    this.loupe.information('WebClient', 'Component Initialization', 'The first component is initializing');
  }
}

Routing

Hooking into route change events is a good way to track page changes. For this you can subscribe to router events from within AppComponent or the AppRoutingModule:

import { LoupeService } from '@gibraltarsoftware/loupe-angular';

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

  constructor(private readonly loupe: LoupeService) {
    loupe.setLogServer('https://myserver.com');

    this.router.events
    .pipe(filter(x => x instanceof NavigationStart))
    .subscribe((evnt: RouterEvent) => {
      this.loupe.information("WebClient", "NavigationStart", evnt.url);
    });
  }
  
}

Error Handlers

While the Loupe Angular package provides a default error handler for you to use as a provider, you can of course, create your own handler for this purpose. Create your own Error Handler class by extending ErrorHandler and define your own custom behaviour to log to Loupe:

import { Injectable } from '@angular/core';
import { LoupeErrorHandler } from '@gibraltarsoftware/loupe-angular';

@Injectable()
export class MyErrorHandler extends LoupeErrorHandler {
  
  constructor(private readonly loupe: LoupeService) {
      super();
  }

  handleError(error: any) {
    // Use built-in behaviour by including this line
    super.handleError(error);

    // Use custom behaviour here
    this.loupe.recordException(error, null, 'Uncaught Exception');
  }
}

The recordException method wraps up some intelligence to extract error details and a stack trace (if available) from the supplied error. The supplied LoupeErrorHandler identifies different error types and

Once defined, you provide the handler in your providers array in AppModule:

@NgModule({
  declarations: [
    AppComponent,
    NavMenuComponent,
    HomeComponent,
    CounterComponent,
    FetchDataComponent
  ],
  imports: [
    BrowserModule.withServerTransition({ appId: 'ng-cli-universal' }),
    HttpClientModule,
    FormsModule,
    RouterModule.forRoot([
      { path: '', component: HomeComponent, pathMatch: 'full' },
      { path: 'counter', component: CounterComponent },
      { path: 'fetch-data', component: FetchDataComponent },
    ])
  ],
  providers: [
    { provide: ErrorHandler, useClass: MyErrorHandler }
  ],
  bootstrap: [AppComponent]
})
export class AppModule { }

Source Information

When an exception is passed into one of the logging methods, the agent will extract the source code information from the stack trace. Without the exception this is not an automatic procedure for performance reasons. However, you can manually supply the details using the MethodSourceInfo parameter. For example:

  public incrementCounter() {
    this.currentCount++;

    const someObject = { name: "test", code: 123 };
    this.loupe.information(
      "Angular", "Incrementing Counter", 'Counter is now {0}',
      [this.currentCount], null, JSON.stringify(someObject), 
      new MethodSourceInfo("counter.component.ts", "incrementCounter", 23)
    );
  }

MethodSourceInfo takes four parameters:

1. File name
2. Method name
3. An optional line number
4. An optional column number

Do remember though, that the line and column numbers don't update if you change your code.

More Examples

For more usage examples see the Sample ASP.NET Core Applications:

• ASP.NET Core application with Angular 8 frontend
• ASP.NET Core application with Angular 10 frontend

License

This module is licensed under ISC