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:
``bash
git clone https://github.com/overlord-303/debugger
cd debugger
npm install
`
or install via npm:
`bash
npm install debugger-logger@stable
`

---

Features

$3

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

$3

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

$3

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

$3

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.

$3

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

---

Usage

$3

To initialize the Debugger instance, import it into your main application file:
`javascript
const Debugger = require('debugger-logger');
`

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

$3

Logs are provided in the follow format:
``text
[0000-00-00 00:00:00] level: 'content' +0ms
``

Use various log methods to track application events:
`javascript
Debugger.log('Info message');
Debugger.logDebug('Debug message');
Debugger.logError('Error message');
`

$3

Add or remove event listeners to track specific events:
`javascript
function log(filePath, content) {
console.log(Logged to file: ${filePath}, with message: ${content}.);
}

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

$3

Intercepted requests are logged automatically, capturing details such as:
- Request method
- Path and headers
- Status code of the response
- Duration of the request

$3

If you need to revert back to the original HTTP/HTTPS request functionality:
`javascript
Debugger.restore('http');
Debugger.restore('https');
`

$3

`javascript
Debugger.getData();
`
will return an object with the following structure:
`javascript
{
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

$3

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.

$3

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

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

$3

``javascript
error.getData();
``
will return an object with the following structure:
``javascript
{
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().
}
``



``javascript
error.getStacktraceArray();
``
will return an array with the following structure:
``javascript
[
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.
}
]
``

$3

``javascript
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}