Neologistic Paraphasic Mumbling

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

    1.4.0 • Public • Published

    loupe-typescript

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

    The agent will 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
    
    1. 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);
      }
    }
    
    1. 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
    
    1. Create a wrapper service (LoupeService.js):
    import { LoupeAgent } from '@gibraltarsoftware/loupe-typescript';
    
    var loupe = new LoupeAgent(window, window.document);
    
    export default loupe
    
    1. Import the service into your component:
    import loupe  from "./LoupeService";
    
    1. 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 Javascript

    Using a Package Manager

    1. Install the agent:
    npm install @gibraltarsoftware/loupe-typescript
    
    1. Import the agent package:
    import { LoupeAgent } from '@gibraltarsoftware/loupe-typescript';
    
    1. Create a new instance of the agent:
    const loupe = new LoupeAgent(window, document);
    
    1. 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.

    1. Import th the Javascript agent into your module code:
    import "/js/loupe.javascript.js";
    
    1. Create a new instance of the agent:
    const loupe = new exports["loupe-typescript"].LoupeAgent(window, document);
    
    1. 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
    );
    

    API

    • 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, passing in the window and document objects:

    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.
    • platform for obtaining platform details fo the client

    License

    This module is licensed under ISC

    Install

    npm i @gibraltarsoftware/loupe-typescript

    DownloadsWeekly Downloads

    14

    Version

    1.4.0

    License

    ISC

    Unpacked Size

    552 kB

    Total Files

    28

    Last publish

    Collaborators

    • davesussman
    • mattgibraltar