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:

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

For Angular 10, use @gibraltarsoftware/[email protected]

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

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

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

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

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.

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.

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

7. Import the references for the new providers:

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:

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

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

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

The endpoint configuration should now look like:

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:

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:

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.

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.

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.

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:

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:

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:

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:

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:

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