Nuns Playing Mozart

    @gibraltarsoftware/loupe-angular
    TypeScript icon, indicating that this package has built-in type declarations

    12.1.0 • Public • Published

    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
    
    1. Import the service into your main component (app.component.ts)
    import { LoupeService } from '@gibraltarsoftware/loupe-angular';
    
    1. Inject the service into your main component (app.component.ts)
      constructor(private readonly loupe: LoupeService) {
        ...
      }
    
    1. 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');
      }
    
    1. 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 }
      ]
    
    1. 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 }
      ]
    
    1. 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
    
    1. 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();
    
    1. 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();
    });
    
    1. 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.

    1. 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:

    License

    This module is licensed under ISC

    Install

    npm i @gibraltarsoftware/loupe-angular

    DownloadsWeekly Downloads

    28

    Version

    12.1.0

    License

    ISC

    Unpacked Size

    147 kB

    Total Files

    20

    Last publish

    Collaborators

    • davesussman
    • mattgibraltar