@gibraltarsoftware/loupe-typescript

loupe-typescript

@gibraltarsoftware/loupe-typescript is a Loupe Agent for web browser applications.

The agent can optionally hook into the window.onerror event to automatically log any uncaught JavaScript errors.

Use of the agent needs to be combined with a server component to correlate the actions your user performs client side with the corresponding server side processing, giving you a better insight into end-to-end functionality. See the project readme for more details.

Installation

You can install the module via npm:

npm install @gibraltarsoftware/loupe-typescript

Installation in Angular

While we receommend using loupe-angular for Angular applications as it wraps up additional functionality, such as auto-handling of uncaught exceptions and the addition of correlation IDs to your HTTP requests. You can of course use the basic agent. You'll want to use the agent throughout your application, so it needs to be globally available, and the simplest way to do this is to wrap it in a service.

1. Install the agent:

npm install @gibraltarsoftware/loupe-typescript

2. Create a wrapper service:

import { LoupeAgent } from '@gibraltarsoftware/loupe-typescript/dist/loupe.agent';

@Injectable({
  providedIn: 'root'
})
export class LoupeService {
  public loupe: LoupeAgent;

  constructor() {
    this.loupe = new LoupeAgent(window, window.document);
  }
}

3. Configure the agent as early as possible in the application lifecycle. We recommend app.component.ts:

import { LoupeService } from '../LoupeService/loupe.service';

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

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

}

Installation in React

1. Install the agent:

npm install @gibraltarsoftware/loupe-typescript

2. Create a wrapper service (LoupeService.js):

import { LoupeAgent } from '@gibraltarsoftware/loupe-typescript';

var loupe = new LoupeAgent(window, window.document);

export default loupe

3. Import the service into your component:

import loupe  from "./LoupeService";

4. Log some details:

const counterObject = { name: "counter", value: this.state.currentCount };
loupe.information(
    "Angular", "Incrementing Counter", 'Counter is now {0}',
    [this.state.currentCount], null, counterObject
);

Installation in NextJS

1. Install the agent:

npm install @gibraltarsoftware/loupe-typescript

2. Create a service to create the agent:

import { LoupeAgent } from '@gibraltarsoftware/loupe-typescript';

var loupe = new LoupeAgent();
loupe.sessionId = 123;
loupe.setLogServer("htpp://localhost:3001");

export default loupe

3. Log some details:

loupe.information("Home Page", "Home Sample Log");

Installation in Javascript

Using a Package Manager

1. Install the agent:

npm install @gibraltarsoftware/loupe-typescript

2. Import the agent package:

import { LoupeAgent } from '@gibraltarsoftware/loupe-typescript';

3. Create a new instance of the agent:

const loupe = new LoupeAgent(window, document);

4. Log some details:

const counterObject = { name: "counter", value: this.state.currentCount };
loupe.information(
    "Angular", "Incrementing Counter", 'Counter is now {0}',
    [this.state.currentCount], null, counterObject
);

Without a Package Manager

If you are creating applications without a package manager, you will need to download/clone this project (loupe-typescript), build it, and use the built Javascript agent code directly.

1. Build the project

npm build

The build generates a javascript source (see dist/loupe.typescript.js), which you can copy to your project folder.

2. Import the Javascript agent into your module code:

var LoupeAgent = require("/js/loupe.typescript");

3. Create a new instance of the agent:

var loupe = new LoupeAgent['loupe-typescript'].LoupeAgent(window, document, platform);

4. Log some details:

const counterObject = { name: "counter", value: this.state.currentCount };
loupe.information(
    "Angular", "Incrementing Counter", 'Counter is now {0}',
    [this.state.currentCount], null, counterObject
);

Creating the Agent

Version 2 introduced a breaking change whereby the constructor arguments have changed. These are now:

• window. Optional. The global Window object. If supplied, the agent hooks into the "onError" method to log uncaught exceptions.
• documen. Optional. The global document object. If supplied, used to obtain document size for client platform details per log message, but only if platform details are also supplied.
• platform. Optional. The client platform details (see interface ILocalPlatform). If supplied they will be attached to the logged client details.

Prior versions included platformjs, which automatically retrieved details of the client (user agent, engine, os, etc). To allow the Loupe Agent to be used in browserless scenarios, this dependency has been removed, but you can still pass in these platform details, either constructing them yourself, or by using platform-js and passing in the appropriate structure. This is shown in the loupe-angular project.

If you wish to supply platform details, then you can install platform and associated types from NPM:

npm install platform
npm install @types/platform

You can then import platform and use the clientPatform as the third parameter on the constructor. Eg:

const loupe = new LoupeAgent(window, window.document, clientPlatform as ILocalPlatform);

If you don't wish to use platform-js, then you can just construct a platform object manually.

You Must Set The Server Location

If you are not passing in the window object, you must set the origin of the log server, so that the agent knows where to send log messages. You can do this via the setLogServer method, which should be done as soon as the agent is created. If the server location is not specified, either directly from setLogServer or inferred from window then an error is thrown when attempting to log messages.

  loupe.setLogServer("https://my-api.mycompany.com");

CORS and Credentials

When sending log messages to your API, you may need to include credentials. The setLogServer has an optional parameter that allows you to set the request credentials. For example:

  loupe.setLogServer("https://my-api.mycompany.com", "same-origin");

This would limit credentials to be from the same origina as the web application. Values are taken from the RequestCredentials, and can be "omit", "same-origin", or "include". The default for the Loupe Agent is "include". See Request: credentials property for more details.

API

• constructor(window?: Window, document?: Document, clientPlatform?: ILocalPlatform) - creates a new instance of the agent.

• critical(category: string, caption: string, description: string, parameters?: any[] | null, exception?: any | null, details?: any | null, methodSourceInfo?: * MethodSourceInfo | null) - write a categorized Crticial message to Loupe.

• error(category: string, caption: string, description: string, parameters?: any[] | null, exception?: any | null, details?: any | null, methodSourceInfo?: * MethodSourceInfo | null) - write a categorized Error message to Loupe.

• information(category: string, caption: string, description: string, parameters?: any[] | null, exception?: any | null, details?: any | null, methodSourceInfo?: MethodSourceInfo | null) - write a categorized Information message to Loupe.

• warning(category: string, caption: string, description: string, parameters?: any[] | null, exception?: any | null, details?: any | null, methodSourceInfo?: * MethodSourceInfo | null) - write a categorized Warning message to Loupe.

• verbose(category: string, caption: string, description: string, parameters?: any[] | null, exception?: any | null, details?: any | null, methodSourceInfo?:MethodSourceInfo | null) - write a categorized Verbose message to Loupe.

• write(severity: LogMessageSeverity, category: string, caption: string, description: string, parameters?: any[] | null, exception?: any | null, details?: any |null, methodSourceInfo?: MethodSourceInfo | null) - write a categorized message to Loupe.

• recordException(exception: any, details?: any, category?: string) - write an exception to Loupe. Parses out a stack trace from the exception.

• setLogServer(value: string | null) - set the target endpoint for log message. If not set, the current host is used with the default log point of /Loupe/Log.

• addHeader(header: Header) - add the header to the request when logging to Loupe.

• clientSessionHeader() - gets the Header used as the agent session id.

• resetMessageInterval(interval: number) - resets the interval used to batch up and send messages. This interval starts at 10 milliseconds and increases if there are failures to send; messages are stored in the browser local storage and resent in order when communication is restored.

• flushToServer() - immediately send any queued messages to the server.

The critical, error, information, warning and verbose methods are all convenience wrappers over the write method. For these, the parameters are:

• category - The application subsystem or logging category that the log message is associated with, which supports a dot-delimited hierarchy (eg the logger name).
• caption - A simple single-line message caption. (Will not be processed for formatting).
• description - Additional multi-line descriptive message (or may be null) which can be a format string followed by corresponding args.
• parameters - Optional. A variable number of arguments referenced by the formatted description string (or no arguments to skip formatting).
• exception - Optional. The error details. This can be a string detailing the exception, an Exception object, or a JavaScript Error object.
• details - Optional. A JSON object, or string version of, with additional details to be logged and shown in the details in Loupe Desktop and Loupe Server. This is useful for passing contextual or state information that could be useful for diagnostics.
• methodSourceInfo - Optional. Details of the file, method, line and column number. This allows source information to be passed without the performance overhead of working out the current file and line (eg by examining the stack, which may well be different with compressed source, especially if source maps are not being used).

Examples

The first step to using Loupe is to create an instance of the agent, optionally passing in the window and document objects. If present, window will be used to hook into unhandled exceptions, and document will be used to get the page resolution. You can also optionally provide platform details (see the LocalPlatform interface) that will be logged along with requests; this can be manually created, or extracted from platform-js.

const loupe = new LoupeAgent(window, document);

If your server project is hosted on a different domain or port, then you'll need to set the target:

loupe.setLogServer('https://myserver.com/');

Next, start logging:

loupe.information('WebClient', 'Application Started', 'The application has started');

The description supports C# style string formatting parameters, which should be passed as an array in parameters. For example:

loupe.information('WebClient', 'Event Occurred', 'User event occurred\r\nUser: {0}\r\nEvent: {1}',
    [user.name, event.name]);

For errors and additional details you can use:

const err = new Error('Custom application error details');
loupe.error('Web', 'Error Occurred', 'An error occurred', null, err,
    {user: user.name, state: app.state});

The additional details parameter can be either a string or a JSON object.

The agent will attempt to parse stack traces and source details from the error, but to add source information manually you can use the MethodSourceInfo:

const err = new Error('Custom application error details');
loupe.error('Web', 'Error Occurred', 'An error occurred', null, err,
    {user: user.name, state: app.state},
    new MethodSourceInfo('index.js', 'init', 47));

For me examples, see the sample project.

Dependencies

• stacktrace-js for stack trace handling for uncaught window errors.

License

This module is licensed under ISC