debugger-logger

Debugger Logger

Debugger Logger is a Node.js utility package for comprehensive logging and request interception. It provides in-depth debugging tools for Node.js applications, capturing HTTP/HTTPS requests, logging events, and managing application state through various utility methods.

Table of Contents

• Installation
• Features
  • Logging Capabilities
  • Event Handling
  • HTTP Request Interception
  • Environment Information
  • Custom Error Handling
• Usage
  • Initialization
  • Basic Logging
  • Event Listeners
  • Intercepting HTTP Requests
  • Restoring Original Modules
• Errors
  • Usage
  • Basics
  • Getting Data
  • Formatting
• License

Installation

To use this package, clone the repository and install dependencies if required:

git clone https://github.com/overlord-303/debugger
cd debugger
npm install

or install via npm:

npm install debugger-logger@stable

Features

Logging Capabilities

• File Logging: Saves log messages to the designated log file.
• Console Logging: Outputs logs to the console.
• Module Call Logging: Logs when a specific module is loaded, useful for tracing dependency execution.
• Custom Log Levels: Supports log levels such as info, debug, error, warning, and traceback.

Event Handling

• Supports adding and removing listeners for custom logging events, including:
  • filelog: Fires on logging events to a file.
  • consolelog: Fires on logging events to the console.
  • modulecall: Fires on logging events related to module loading or compiling.

HTTP Request Interception

• Intercepts HTTP/HTTPS requests: Captures outgoing HTTP and HTTPS requests, logs their details, and measures request duration.
• Module Backup and Restoration: Backs up original request functions (http/https) to restore the modules if needed, preventing conflicts or circular dependencies.

Environment Information

Provides a snapshot of environment details, such as platform, architecture, Node.js version, and process ID, as well as a utility for checking execution time.

Custom Error Handling

• Integrates global error handling for uncaught exceptions and unexpected errors.
• Allows setting custom shutdown and cleanup actions during application exit.

Usage

Initialization

To initialize the Debugger instance, import it into your main application file:

const Debugger = require('debugger-logger');

The Debugger is a singleton and is automatically instantiated as one.

Basic Logging

Logs are provided in the follow format:

[0000-00-00 00:00:00] level: 'content' +0ms

Use various log methods to track application events:

Debugger.log('Info message');
Debugger.logDebug('Debug message');
Debugger.logError('Error message');

Event Listeners

Add or remove event listeners to track specific events:

function log(filePath, content) {
   console.log(`Logged to file: ${filePath}, with message: ${content}.`);
}

Debugger.on('filelog', log);
Debugger.off(Debugger.EVENTS.FILELOG, log);

Intercepting HTTP Requests

Intercepted requests are logged automatically, capturing details such as:

• Request method
• Path and headers
• Status code of the response
• Duration of the request

Restoring Original Modules

If you need to revert back to the original HTTP/HTTPS request functionality:

Debugger.restore('http');
Debugger.restore('https');

Getting environment snapshot

Debugger.getData();

will return an object with the following structure:

{
  env: {
    name: string,
    version: string,
    platform: NodeJS.Platform,
    architecture: NodeJS.Architecture,
    nodePath: string,
    pid: number
  },
  memoryUsage: {
    rss: {
      bytes: number,
      kilobytes: number,
      megabytes: number
    },
    heapTotal: {
      bytes: number,
      kilobytes: number,
      megabytes: number
    },
    heapUsed: {
      bytes: number,
      kilobytes: number,
      megabytes: number
    },
    external: {
      bytes: number,
      kilobytes: number,
      megabytes: number
    },
    arrayBuffers: {
      bytes: number,
      kilobytes: number,
      megabytes: number
    }
  },
  executionTimePassed: number
}

Errors

Basics

MainError is the primary error class used in Debugger Logger to encapsulate detailed error information.

Each MainError instance contains:

• Name: The name of the error.
• Message: An error message providing more detail/context.
• Timestamp: The date and time when the error occurred.
• Stack Trace: A formatted and parsed string of stack trace details for pinpointing the error source.

Usage

Utility function to check if an error is a MainError instance, return value changes based on arguments passed to the function.

Debugger.isMainError(error);              // Returns a boolean.
Debugger.isMainError(errorOne, errorTwo); // Returns an array of booleans.

Getting Data

error.getData();

will return an object with the following structure:

{
    name: string,
    message: string,
    timestamp: Date,
    stack: string,
    code?: string, // Error-Code if created via static method `MainError.fromErrorCode()` or provided via `error.addData()`.
    
    ...key?: any,  // Any key-value pairs added via `error.addData()`.
}

error.getStacktraceArray();

will return an array with the following structure:

[
  number: {
      function?: string,
      file?: string,
      line?: number,
      column?: number,
    
      raw?: string, // If parsing fails the `raw` key is provided instead of the ones listed above.
  }
]

Formatting

error.toJSON();   // Returns a JSON formatted string useful for logging.
error.toString(); // Returns a formatted string useful for logging.

License

This project is licensed under the GNU AGPLv3 License.

^{Back to the top}