Super Server Logs

https://github.com/wiselibs/super-server-logs
Admin
Super Server Logs is a high-performance library for reading and writing server logs with built-in...
Tokens:18,225
Snippets:132
Trust Score:8.2
License:MIT
Update:6 months ago
Show doc for...
Tokens:
Raw
### Install super-server-logs

Source: https://github.com/wiselibs/super-server-logs/blob/master/README.md

Install the library using npm. Requires Node.js v18.4.x or later.

```bash
npm install super-server-logs
```

--------------------------------

### Tail Logs in Real-Time with LogReader

Source: https://context7.com/wiselibs/super-server-logs/llms.txt

Monitor log files in real-time using the `tail` method. This is useful for live monitoring and requires a `pollInterval` to be set. The example shows how to filter and display logs based on type and level, and how to break the loop based on a condition.

```javascript
const { LogReader, LogDirectorySource, LogType, LogLevel } = require('super-server-logs');

const reader = new LogReader(new LogDirectorySource('./logs', {
  lazy: true,         // Files only open when actively reading
  pollInterval: 200   // Required for tailing
}));

// Tail from current time with custom poll interval
const options = { pollInterval: 100 }; // Check every 100ms

console.log('Starting real-time log monitoring...');

for await (const log of reader.tail(Date.now(), options)) {
  const timestamp = new Date(log.timestamp).toISOString();

  // Filter and display based on log type and level
  if (log.level <= LogLevel.ERROR) {
    console.log(`[${timestamp}] ERROR:`, log.toJSON());
  } else if (log.type === LogType.REQUEST) {
    console.log(`[${timestamp}] ${log.getHttpMethod()} ${log.url}`);
  } else if (log.type === LogType.RESPONSE) {
    console.log(`[${timestamp}] Response: ${log.statusCode}`);
  }

  // Break on specific condition
  if (shouldStop) break;
}
```

--------------------------------

### Implement Custom Vfs for Remote Log Source

Source: https://context7.com/wiselibs/super-server-logs/llms.txt

Extend the Vfs class to create a custom log source that fetches logs from a remote server. This involves implementing setup, teardown, size, and read methods to interact with the remote API. Ensure proper handling of byte offsets and lengths for reading log data.

```javascript
const { LogReader, Vfs } = require('super-server-logs');

// Custom Vfs for reading logs from a remote server
class RemoteLogSource extends Vfs {
  constructor(baseUrl, options = {}) {
    super({
      cacheSize: options.cacheSize || 16777216,

      async setup(saveToCache) {
        // Initialize connection, fetch metadata, etc.
        this.metadata = await fetch(`${baseUrl}/metadata`).then(r => r.json());
      },

      async teardown() {
        // Cleanup resources
      },

      async size(saveToCache) {
        const response = await fetch(`${baseUrl}/size`);
        const size = parseInt(await response.text(), 10);
        return size;
      },

      async read(byteOffset, byteLength, saveToCache) {
        const response = await fetch(`${baseUrl}/read`, {
          headers: {
            'Range': `bytes=${byteOffset}-${byteOffset + byteLength - 1}`
          }
        });
        const buffer = await response.arrayBuffer();
        const data = new Uint8Array(buffer);

        // Optionally cache the data for future reads
        saveToCache(byteOffset, data);

        return data;
      }
    });

    this.baseUrl = baseUrl;
  }
}

// Usage with custom Vfs
const source = new RemoteLogSource('https://logs.example.com/api');
const reader = new LogReader(source);

const HOUR = 1000 * 60 * 60;
for await (const log of reader.range(Date.now() - HOUR, Date.now())) {
  console.log(log.toJSON());
}
```

--------------------------------

### reader.bulkTail

Source: https://github.com/wiselibs/super-server-logs/blob/master/docs/readers.md

Continuously yields chunks of raw binary logs starting from a minimum timestamp.

```APIDOC
## reader.bulkTail([minTimestamp[, options]])

### Description
Continuously yields chunks of raw binary logs, including all logs with a timestamp greater than or equal to `minTimestamp`. New chunks are yielded indefinitely until the iterable is stopped.

### Method
GET (conceptual)

### Endpoint
Not applicable (this is a method call on a reader object)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **minTimestamp** (number) - Optional - The minimum timestamp (inclusive). Defaults to `Date.now()`.
- **options** (Object) - Optional - Configuration options.
  - **pollInterval** (number) - Optional - The delay in milliseconds between polls to the log source. Defaults to `200`.

### Returns
- **AsyncIterable<Buffer>** - An asynchronous iterable yielding chunks of raw binary log data.

### Request Example
```js
for await (const chunk of reader.bulkTail()) {
	socket.write(chunk);
}
```

### Response
#### Success Response (200)
- **Buffer** (Buffer) - A chunk of raw binary log data.

#### Response Example
```json
// Raw binary data representing log chunks
```
```

--------------------------------

### Continuously Tail Raw Log Chunks

Source: https://github.com/wiselibs/super-server-logs/blob/master/docs/readers.md

Employ `reader.bulkTail` to receive raw binary log chunks indefinitely, starting from a specified minimum timestamp. This method is efficient for piping logs to external systems. Newly written chunks are yielded until the iterable is stopped.

```js
for await (const chunk of reader.bulkTail()) {
	socket.write(chunk);
}
```

--------------------------------

### Initialize LogReader with LogDirectorySource

Source: https://github.com/wiselibs/super-server-logs/blob/master/docs/readers.md

Instantiate a LogReader by providing a LogDirectorySource, which points to the directory containing log files.

```javascript
const dirname = './logs';
const reader = new LogReader(new LogDirectorySource(dirname));
```

--------------------------------

### Real-time Bulk Tailing and Streaming

Source: https://context7.com/wiselibs/super-server-logs/llms.txt

Continuously tail log files in real-time and stream new log entries as binary chunks over a network socket. This enables live log monitoring and aggregation.

```javascript
// Real-time bulk tailing
async function tailAndStreamLogs(socket) {
  for await (const chunk of reader.bulkTail(Date.now(), { pollInterval: 100 })) {
    socket.write(chunk);
  }
}
```

--------------------------------

### Tail Logs from a Directory

Source: https://github.com/wiselibs/super-server-logs/blob/master/docs/readers.md

Use LogDirectorySource to tail logs from a specified directory. Configure options like lazy loading and polling interval for efficient log monitoring.

```javascript
const dirname = './logs';
const reader = new LogReader(new LogDirectorySource(dirname, {
	lazy: true,
	pollInterval: 200,
}));

for await (const log of reader.tail(Date.now())) {
	console.log(log.timestamp);
}
```

--------------------------------

### Initialize MasterLogger for Master Process Logging

Source: https://context7.com/wiselibs/super-server-logs/llms.txt

Configure MasterLogger in the master process for logging cluster events and ad-hoc messages. Set buffer size, output delay, compression, and debug log limits. Essential lifecycle events like STARTING_UP, WORKER_SPAWNED, and WORKER_EXITED should be logged. Handle uncaught exceptions and ensure logs are flushed on shutdown.

```javascript
const { MasterLogger } = require('super-server-logs');
const cluster = require('cluster');

const masterLogger = new MasterLogger('./logs/app.log', {
  highWaterMark: 32768, // 32 KiB buffer before flush
  outputDelay: 200,     // Flush every 200ms maximum
  compression: true,    // Enable compression
  pingDelay: 60000,     // Internal ping every 60 seconds
  debugLogLimit: 100    // Keep 100 debug logs in memory
});

// Required: Log startup event first
masterLogger.STARTING_UP();

// Spawn workers and log each spawn
for (let i = 0; i < 4; i++) {
  const worker = cluster.fork();
  masterLogger.WORKER_SPAWNED(worker.id);
}

// Log when all workers are online
masterLogger.STARTING_UP_COMPLETED();

// Ad-hoc logging at various levels
masterLogger.info({ event: 'config_loaded', path: '/etc/app/config.json' });
masterLogger.warn({ event: 'deprecated_feature', feature: 'legacyAuth' });
masterLogger.error({ event: 'cache_failure', service: 'redis' });
masterLogger.critical({ event: 'database_down', host: 'db.example.com' });
masterLogger.debug({ event: 'memory_usage', heapUsed: process.memoryUsage().heapUsed });

// Track worker exits
cluster.on('exit', (worker, code, signal) => {
  masterLogger.WORKER_EXITED(worker.id, code, signal);
});

// Handle uncaught exceptions
process.on('uncaughtException', (err) => {
  masterLogger.UNCAUGHT_EXCEPTION(err);
  masterLogger.flush();
  process.exit(1);
});

// Graceful shutdown
process.on('SIGTERM', () => {
  masterLogger.SHUTTING_DOWN();
  // ... shutdown workers ...
  masterLogger.SHUTTING_DOWN_COMPLETED();
  masterLogger.close();
});

// Ensure logs are written on exit
process.on('exit', () => masterLogger.flush());
```

--------------------------------

### LogDirectorySource Constructor

Source: https://github.com/wiselibs/super-server-logs/blob/master/docs/readers.md

Initializes a new LogDirectorySource to read logs from a specified directory. Supports options for caching, polling interval, lazy file opening, and immutability.

```APIDOC
## new LogDirectorySource(dirname[, options])

### Description
Initializes a new LogDirectorySource to read logs from a specified directory.

### Parameters
#### Path Parameters
- **dirname** (string) - Required - The path of the log directory.

#### Request Body
- **options** (Object) - Optional - Configuration options for the LogDirectorySource.
	- **cacheSize** (number) - Optional - The maximum amount of filesystem data (in bytes) to cache in memory. Default: `16777216` (16 MiB).
	- **pollInterval** (number | null) - Optional - The delay, in milliseconds, between filesystem polls to detect new logs. Default: `null` (never).
	- **lazy** (boolean) - Optional - If `true`, files are only kept open while actively being read. Default: `false`.
	- **immutable** (boolean) - Optional - If `true`, optimizations are enabled assuming no live server is writing to the logs. Default: `false`.

### Notes
- By default, logs are read from a single snapshot. Setting `pollInterval` enables tailing.
- `lazy: true` causes files to be opened only during active reads, which is useful for long-term tailing but may throw exceptions for deleted old logs.
- `immutable: true` can be set if no live server is writing to logs, enabling performance optimizations.

### Request Example
```js
const dirname = './logs';
const reader = new LogReader(new LogDirectorySource(dirname, {
	lazy: true,
	pollInterval: 200,
}));

for await (const log of reader.tail(Date.now())) {
	console.log(log.timestamp);
}
```
```

--------------------------------

### Initialize and Use WorkerLogger

Source: https://context7.com/wiselibs/super-server-logs/llms.txt

Initialize WorkerLogger with configuration options and use it to log worker lifecycle events and ad-hoc messages. Handles uncaught exceptions and log rotation.

```javascript
const { WorkerLogger } = require('super-server-logs');
const http = require('http');

const workerLogger = new WorkerLogger('./logs/app.log', {
  highWaterMark: 32768,
  outputDelay: 200,
  compression: true,
  debugLogLimit: 100
});

// Log worker lifecycle events
workerLogger.WORKER_STARTED();

// Perform setup (database connections, etc.)
async function setup() {
  // ... setup code ...
}

setup().then(() => {
  workerLogger.WORKER_GOING_ONLINE();

  const server = http.createServer((req, res) => {
    // Create a new RequestLogger for each request
    const requestLogger = workerLogger.newRequest();

    // Handle request using requestLogger (see RequestLogger section)
    handleRequest(req, res, requestLogger);
  });

  server.listen(3000, () => {
    workerLogger.WORKER_ONLINE();
  });
});

// Ad-hoc logging
workerLogger.info({ event: 'cache_hit', key: 'user:123' });
workerLogger.warn({ event: 'slow_query', duration: 5000 });
workerLogger.debug({ event: 'processing_step', step: 'validation' });

// Handle uncaught exceptions
process.on('uncaughtException', (err) => {
  workerLogger.UNCAUGHT_EXCEPTION(err);
  workerLogger.flush();
  process.exit(1);
});

// Handle log rotation from master process
process.on('message', (msg) => {
  if (msg.type === 'rotate') {
    workerLogger.rotate(msg.filename);
  }
});

// Graceful shutdown
process.on('SIGTERM', async () => {
  workerLogger.WORKER_GOING_OFFLINE();
  // ... close server and connections ...
  workerLogger.WORKER_OFFLINE();
  // ... teardown ...
  workerLogger.WORKER_DONE();
  workerLogger.close();
});
```

--------------------------------

### Initialize LogManager for Log Rotation

Source: https://context7.com/wiselibs/super-server-logs/llms.txt

Set up LogManager in the master process to handle log file rotation based on size, age, and polling interval. Listen for 'rotate' events to update loggers and 'error' events for error handling. Ensure cleanup by calling manager.close() on process exit.

```javascript
const { LogManager, MasterLogger, WorkerLogger } = require('super-server-logs');
const cluster = require('cluster');

// Create a log manager in the master process
const manager = new LogManager('./logs', {
  pollInterval: 5000,       // Check for rotation every 5 seconds
  logSizeLimit: 2147483648, // 2 GiB maximum total log size
  logAgeLimit: 31536000000, // 1 year maximum age
  granularity: 20           // Split into ~20 files for precise cleanup
});

// Listen for rotation events to update all loggers
manager.on('rotate', (filename) => {
  masterLogger.rotate(filename);
  // Send filename to workers via IPC
  for (const worker of Object.values(cluster.workers)) {
    worker.send({ type: 'rotate', filename });
  }
});

manager.on('error', (err) => {
  console.error('Log manager error:', err);
});

// Access current state
console.log('Log directory:', manager.dirname);
console.log('Current log file:', manager.filename);

// Cleanup on shutdown
process.on('exit', () => manager.close());
```

--------------------------------

### Vfs Class

Source: https://github.com/wiselibs/super-server-logs/blob/master/docs/readers.md

Abstract base class for custom log sources. Allows reading logs from arbitrary sources, such as in a browser.

```APIDOC
## Vfs

### Description
An abstract class that serves as a base for custom log sources. Implementing `Vfs` allows reading logs from any arbitrary source, enabling use cases like reading raw binary logs in a browser.

### Usage
To implement a `Vfs`, refer to the source code provided in `../src/shared/vfs.js`.
```

--------------------------------

### LogEntry Utility Methods

Source: https://github.com/wiselibs/super-server-logs/blob/master/docs/readers.md

Utility methods available on LogEntry objects for formatting and retrieving specific data.

```APIDOC
### log.getRequestId()

- Returns: (string)

Returns the [UUIDv4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) `log.requestId` converted to a string.

### log.getIpAddress()

- Returns: (string)

Returns the [IPv4](https://en.wikipedia.org/wiki/Internet_protocol_version_4) or [IPv6](https://en.wikipedia.org/wiki/Internet_protocol_version_6) address `log.ipAddress` converted to a string.
```

--------------------------------

### Read Logs from Directory with LogReader

Source: https://context7.com/wiselibs/super-server-logs/llms.txt

Use LogReader and LogDirectorySource to read logs from a specified directory. Configure cache size, polling interval, and file handling behavior. This snippet demonstrates reading logs within a time range and processing different log types.

```javascript
const { LogReader, LogDirectorySource, LogType, LogLevel } = require('super-server-logs');

// Create a reader for a log directory
const source = new LogDirectorySource('./logs', {
  cacheSize: 16777216,  // 16 MiB cache
  pollInterval: 200,    // Enable tailing with 200ms polling
  lazy: false,          // Keep files open (prevents deletion during read)
  immutable: false      // Assume live server may be writing
});

const reader = new LogReader(source);

// Read logs from the last 24 hours
const DAY = 1000 * 60 * 60 * 24;
const minTime = Date.now() - DAY;
const maxTime = Date.now();

for await (const log of reader.range(minTime, maxTime)) {
  console.log({
    timestamp: new Date(log.timestamp).toISOString(),
    type: log.type,
    level: log.level,
    workerId: log.workerId
  });

  // Handle different log types
  if (log.type === LogType.REQUEST) {
    console.log('Request:', log.getHttpMethod(), log.url, 'from', log.getIpAddress());
  } else if (log.type === LogType.RESPONSE) {
    console.log('Response:', log.statusCode);
    if (log.error) {
      const errorInfo = log.getError();
      console.log('Error:', errorInfo.stack || errorInfo.value);
      console.log('Debug logs:', errorInfo.debug);
    }
  } else if (log.type === LogType.LOG) {
    console.log('Log data:', JSON.parse(log.data));
  }
}

// Read in reverse order (newest first)
for await (const log of reader.rangeReversed(minTime, maxTime)) {
  console.log(log.timestamp, log.type);
  // Stop after first 100 logs
  if (--limit <= 0) break;
}
```

--------------------------------

### Tail Logs in Real-time

Source: https://github.com/wiselibs/super-server-logs/blob/master/docs/readers.md

Use reader.tail() to asynchronously iterate over logs as they are written. New logs are yielded indefinitely. Logs are yielded in ascending order.

```javascript
for await (const log of reader.tail()) {
	console.log(log.timestamp);
}
```

--------------------------------

### Receive and Parse Bulk Logs

Source: https://context7.com/wiselibs/super-server-logs/llms.txt

Receive raw binary log chunks from a network socket and parse them into log blocks and then individual LogEntry objects. This is useful for log aggregation on the receiving end.

```javascript
// Receive and parse bulk logs on the other end
async function receiveBulkLogs(socket) {
  // Wrap socket as async iterable
  const chunks = socketToAsyncIterable(socket);

  // Parse chunks into log blocks
  for await (const block of BulkParser.read(chunks)) {
    // Parse each block into LogEntry objects
    for (const log of BulkParser.parse(block)) {
      console.log(log.timestamp, log.type);
    }
  }
}
```

--------------------------------

### Master Logging Methods

Source: https://github.com/wiselibs/super-server-logs/blob/master/docs/writers.md

Methods for writing different levels of logs and specific event logs.

```APIDOC
### Master logging methods

The following methods each write data to the log file. Each method is used for a particular purpose.

- `masterLogger.STARTING_UP()`: This MUST be the first thing logged whenever a master process first starts up.
- `masterLogger.STARTING_UP_COMPLETED()`: This SHOULD be logged after all workers have been spawned, and their HTTP servers have all been started.
- `masterLogger.SHUTTING_DOWN()`: This SHOULD be logged when the master process wants to initiate a graceful shutdown procedure, but before any workers have been instructed to shut down.
- `masterLogger.SHUTTING_DOWN_COMPLETED()`: This SHOULD be logged after the master process finishes shutting down, and all workers have exited (regardless of whether the shutdown was actually graceful).
- `masterLogger.WORKER_SPAWNED(workerId)`: This MUST be logged whenever the master process spawns a new worker process.
- `masterLogger.WORKER_EXITED(workerId, exitCode, signal)`: This MUST be logged whenever the master process detects that a worker process has exited.
- `masterLogger.UNCAUGHT_EXCEPTION(error)`: This SHOULD be logged whenever an uncaught exception is detected within the master process.
- `masterLogger.critical(data)`: This writes a CRITICAL-level log.
- `masterLogger.error(data)`: This writes an ERROR-level log.
- `masterLogger.warn(data)`: This writes a WARN-level log.
- `masterLogger.info(data)`: This writes an INFO-level log.
- `masterLogger.debug(data)`: This buffers a DEBUG-level log, which will be written if/when the next UNCAUGHT_EXCEPTION log is written.
```

--------------------------------

### Stream Logs Over Network with BulkParser

Source: https://context7.com/wiselibs/super-server-logs/llms.txt

Stream raw binary log chunks over a network socket for efficient log aggregation. This method is suitable for piping logs to external systems.

```javascript
const { LogReader, LogDirectorySource, BulkParser } = require('super-server-logs');
const net = require('net');

const reader = new LogReader(new LogDirectorySource('./logs', {
  pollInterval: 200
}));

// Stream logs over network to external system
async function streamLogsToServer(socket) {
  const DAY = 1000 * 60 * 60 * 24;

  // Bulk methods yield raw binary chunks (more efficient)
  for await (const chunk of reader.bulkRange(Date.now() - DAY, Date.now())) {
    socket.write(chunk);
  }
}
```

--------------------------------

### Bulk Log Parsing

Source: https://github.com/wiselibs/super-server-logs/blob/master/docs/readers.md

APIs for reading and parsing bulk streams of log data.

```APIDOC
## BulkParser.read(chunks)

### Description
Given an AsyncIterable containing chunks of raw binary logs, this returns an AsyncIterable that yields well-formed "log blocks". These blocks can subsequently be parsed by `BulkParser.parse(block)` to extract the LogEntrys.

### Method
GET (Implicit)

### Endpoint
N/A (Method on BulkParser)

### Parameters
#### Request Body
- **chunks** (AsyncIterable<Buffer>) - Required - A "bulk" stream of raw binary logs.

### Returns
- **AsyncIterable<Buffer>**: An AsyncIterable yielding well-formed "log blocks".

### Request Example
```js
for await (const block of BulkParser.read(rawChunks)) {
	for (const log of BulkParser.parse(block)) {
		console.log(log.timestamp);
	}
}
```
```

```APIDOC
## BulkParser.readReversed(chunks)

### Description
Given an AsyncIterable containing reverse-order chunks of raw binary logs, this returns an AsyncIterable that yields well-formed "log blocks". These blocks can subsequently be parsed by `BulkParser.parse(block)` to extract the LogEntrys.

### Method
GET (Implicit)

### Endpoint
N/A (Method on BulkParser)

### Parameters
#### Request Body
- **chunks** (AsyncIterable<Buffer>) - Required - A reverse "bulk" stream of raw binary logs.

### Returns
- **AsyncIterable<Buffer>**: An AsyncIterable yielding well-formed "log blocks" in reverse order.

### Request Example
```js
for await (const block of BulkParser.readReversed(rawChunks)) {
	for (const log of BulkParser.parse(block)) {
		console.log(log.timestamp);
	}
}
```
```

```APIDOC
## BulkParser.parse(block)

### Description
This is used in conjunction with `BulkParser.read()` or `BulkParser.readReversed()` to parse a "bulk" log stream.

### Method
GET (Implicit)

### Endpoint
N/A (Method on BulkParser)

### Parameters
#### Request Body
- **block** (Buffer) - Required - A well-formed "log block".

### Returns
- **Iterable<LogEntry>**: An Iterable yielding LogEntry objects.

### Request Example
```js
for await (const block of BulkParser.read(rawChunks)) {
	for (const log of BulkParser.parse(block)) {
		console.log(log.timestamp);
	}
}
```
```

--------------------------------

### WorkerLogger Constructor

Source: https://github.com/wiselibs/super-server-logs/blob/master/docs/writers.md

Initializes a new WorkerLogger instance. This logger is intended for use within each worker process of a server cluster.

```APIDOC
## WorkerLogger Constructor

### Description
Initializes a new WorkerLogger instance. This logger is intended for use within each worker process of a server cluster. If the specified log file does not exist, it will be created.

### Method
`new WorkerLogger(filename[, options])`

### Parameters
#### Path Parameters
- **filename** (string) - Required - The path of the log file.

#### Query Parameters
- **options** (Object) - Optional - Configuration options for the logger.
	- **highWaterMark** (number) - Optional - The maximum amount of data (in bytes) that can be buffered before being flushed. Defaults to `32768` (32 KiB).
	- **outputDelay** (number) - Optional - The maximum amount of time (in milliseconds) that data can be buffered for, before being flushed. Defaults to `200`.
	- **compression** (boolean) - Optional - Whether or not to compress logs. Defaults to `true`.
	- **debugLogLimit** (number) - Optional - The maximum number of DEBUG logs to keep in memory before discarding the oldest ones. Defaults to `100`.

### Notes
- Setting `highWaterMark` or `outputDelay` to `0` disables batching, which significantly impacts logging performance.

### Request Example
```javascript
const workerLogger = new WorkerLogger('/var/log/my-worker.log', {
  highWaterMark: 65536,
  outputDelay: 500,
  compression: false,
  debugLogLimit: 50
});
```

### Response
This method does not return a value directly, but initializes a `WorkerLogger` object.
```

--------------------------------

### Worker Logging Methods

Source: https://github.com/wiselibs/super-server-logs/blob/master/docs/writers.md

Methods for writing various types of logs to the file. Each method serves a specific purpose for tracking worker process lifecycle and events.

```APIDOC
## Worker Logging Methods

### Description
These methods are used to write different types of log messages to the file managed by the `WorkerLogger`.

### Methods
- `workerLogger.WORKER_STARTED()`: Logged when the worker process begins execution, before any setup.
- `workerLogger.WORKER_GOING_ONLINE()`: Logged after setup is complete, but before the HTTP server starts.
- `workerLogger.WORKER_ONLINE()`: Logged when the worker process's HTTP server has successfully started.
- `workerLogger.WORKER_GOING_OFFLINE()`: Logged when the worker process initiates a graceful shutdown.
- `workerLogger.WORKER_OFFLINE()`: Logged when the worker process's HTTP server has shut down successfully.
- `workerLogger.WORKER_DONE()`: Logged after the worker process completes its teardown procedures.
- `workerLogger.UNCAUGHT_EXCEPTION(error)`: Logged when an uncaught exception occurs. The `error` object should be passed.
- `workerLogger.critical(data)`: Writes a CRITICAL-level log message. `data` can be any type.
- `workerLogger.error(data)`: Writes an ERROR-level log message. `data` can be any type.
- `workerLogger.warn(data)`: Writes a WARN-level log message. `data` can be any type.
- `workerLogger.info(data)`: Writes an INFO-level log message. `data` can be any type.
- `workerLogger.debug(data)`: Buffers a DEBUG-level log message. It is only written if an `UNCAUGHT_EXCEPTION` occurs.

### Request Example
```javascript
workerLogger.WORKER_STARTED();
workerLogger.error('Failed to connect to database.');
workerLogger.debug('Processing user request...');
```

### Response
These methods do not return a value.
```

--------------------------------

### LogEntry Class Structure

Source: https://github.com/wiselibs/super-server-logs/blob/master/docs/readers.md

Details the properties of a LogEntry object, including common fields and type-specific fields for various log types.

```APIDOC
## LogEntry Class

This class represents individual log entries. Every LogEntry has the following properties:

- `log.timestamp` (number): A millisecond unix timestamp indicating when the log was written.
- `log.type` (number): The log type. Possible values are defined by the [LogType](#enum-logtype) enum.
- `log.level` (number): The log level. Possible values are defined by the [LogLevel](#enum-loglevel) enum.
- `log.workerId` (number | null): The ID of the worker that wrote this log. A value of `null` indicates that it was written by the master process of the [server cluster](https://nodejs.org/api/cluster.html).
- `log.nonce` (number): An unsigned 16-bit integer. Logs can be uniquely identified by combining their `timestamp`, `nonce`, and `workerId`.

Additional properties depending on the log's type:

### LogType.REQUEST:
- `log.requestId` (Buffer): A 16-byte [UUIDv4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) used to uniquely identify the HTTP request.
- `log.httpVersionMajor` (number): The first integer of the request's HTTP version.
- `log.httpVersionMinor` (number): The second integer of the request's HTTP version.
- `log.ipAddress` (number | Buffer): Either the [IPv4 address](https://en.wikipedia.org/wiki/Internet_protocol_version_4) as an unsigned 32-bit integer, or the [IPv6 address](https://en.wikipedia.org/wiki/Internet_protocol_version_6) as a 16-byte [Buffer].
- `log.method` (number | string): Either a well-known HTTP method defined by the [HttpMethod](#enum-httpmethod) enum, or an unrecognized HTTP method as a literal string.
- `log.url` (string): The URL that was sent in the request's header ([`req.url`](https://nodejs.org/api/http.html#messageurl)).

### LogType.REQUEST_META:
- `log.requestId` (Buffer): A 16-byte [UUIDv4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) used to uniquely identify the HTTP request.
- `log.data` (string): Application-specific metadata that was associated with the request, stored as stringified JSON.

### LogType.RESPONSE:
- `log.requestId` (Buffer): A 16-byte [UUIDv4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) used to uniquely identify the HTTP request.
- `log.statusCode` (number): The status code used to respond to the request.
- `log.error` (string | null): Details describing an exception that occured while trying to handle the request. To get a human-readable version, use [`log.getError()`](#loggeterror).

### LogType.RESPONSE_FINISHED:
- `log.requestId` (Buffer): A 16-byte [UUIDv4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) used to uniquely identify the HTTP request.
- `log.error` (string | null): Details describing an exception that occured after responding to the request, but before the response stream was finished. To get a human-readable version, use [`log.getError()`](#loggeterror).

### LogType.LOG:
- `log.requestId` (Buffer | null): A 16-byte [UUIDv4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) used to uniquely identify the HTTP request. A value of `null` is used for logs that are not associated with a request.
- `log.data` (string): The logged data, stored as stringified JSON.

### LogType.LIFECYCLE:
- `log.event` (number): The type of lifecycle event that occured. Possible values are defined by the [Lifecycle](#enum-lifecycle) enum.
- Additional properties for `log.event === Lifecycle.WORKER_EXITED`:
  - `log.exitCode` (number | null): The exit code of the worker process (if it exited normally).
  - `log.signal` (string | null): The POSIX signal that terminated the worker process (if any).

### LogType.UNCAUGHT_EXCEPTION:
- `log.error` (string): Details describing an uncaught exception that occured within the process. To get a human-readable version, use [`log.getError()`](#loggeterror).
```

--------------------------------

### LogManager Utility Methods

Source: https://github.com/wiselibs/super-server-logs/blob/master/docs/writers.md

Utility methods for flushing, rotating, and closing the log manager.

```APIDOC
### masterLogger.flush()

Flushes the logger's internal buffer, writing the logs to the filesystem. This happens synchronously, so it can be used within [`process.on('exit')`](https://nodejs.org/api/process.html#event-exit).

### masterLogger.rotate(filename)

Changes the logger's file to the new `filename`. This happens synchronously.

### masterLogger.close()

Closes the logger, flushing any remaining logs to the filesystem. This happens synchronously, so it can be used within [`process.on('exit')`](https://nodejs.org/api/process.html#event-exit).

### masterLogger.closed

- `closed` (boolean) - Indicates whether or not the logger is closed.
```

--------------------------------

### Initialize and Use RequestLogger

Source: https://context7.com/wiselibs/super-server-logs/llms.txt

Initialize RequestLogger and use it within an HTTP request handler to log request details, metadata, and response status. Buffers debug logs until an error occurs.

```javascript
const { WorkerLogger } = require('super-server-logs');

const workerLogger = new WorkerLogger('./logs/app.log');

async function handleRequest(req, res, requestLogger) {
  // Log the incoming request (captures method, URL, IP, HTTP version)
  requestLogger.REQUEST(req);

  // Add custom metadata to the request
  requestLogger.REQUEST_META({
    userId: req.headers['x-user-id'],
    sessionId: req.headers['x-session-id'],
    userAgent: req.headers['user-agent']
  });

  // Debug logs are buffered and only written if an error occurs
  requestLogger.debug({ step: 'parsing_body' });
  requestLogger.debug({ step: 'validating_input' });

  try {
    // Process the request
    const result = await processRequest(req);

    requestLogger.info({ action: 'user_action', details: result.action });

    // Log successful response
    res.writeHead(200, { 'Content-Type': 'application/json' });
    requestLogger.RESPONSE(200);

    res.end(JSON.stringify(result));
    requestLogger.RESPONSE_FINISHED();

  } catch (err) {
    if (err.expected) {
      // Expected errors (e.g., validation) - logged at INFO level, no stack trace
      res.writeHead(400);
      requestLogger.RESPONSE(400, err, true); // isExpectedError = true
    } else {
      // Unexpected errors - logged at ERROR level with stack trace and DEBUG logs
      requestLogger.error({ context: 'request_processing', error: err.message });
      res.writeHead(500);
      requestLogger.RESPONSE(500, err);
    }

    res.end(JSON.stringify({ error: err.message }));
    requestLogger.RESPONSE_FINISHED();
  }

  // Access the unique request ID (UUIDv4)
  console.log('Request completed:', requestLogger.requestId);
}

// Usage in HTTP server
const http = require('http');
const server = http.createServer((req, res) => {
  const requestLogger = workerLogger.newRequest();
  handleRequest(req, res, requestLogger);
});

```

--------------------------------

### Accessing Log Properties with LogEntry

Source: https://context7.com/wiselibs/super-server-logs/llms.txt

Iterate through log entries within a specified time range and access common properties like timestamp, nonce, level, type, and workerId. Use a switch statement to handle different log types and access type-specific data.

```javascript
const { LogReader, LogDirectorySource, LogType, LogLevel, Lifecycle } = require('super-server-logs');

const reader = new LogReader(new LogDirectorySource('./logs'));

const DAY = 1000 * 60 * 60 * 24;

for await (const log of reader.range(Date.now() - DAY, Date.now())) {
  // Common properties available on all logs
  const entry = {
    timestamp: log.timestamp,        // Unix timestamp in milliseconds
    nonce: log.nonce,                // 16-bit integer for uniqueness
    level: log.level,                // LogLevel enum value
    type: log.type,                  // LogType enum value
    workerId: log.workerId           // Worker ID or null for master
  };

  switch (log.type) {
    case LogType.REQUEST:
      console.log('Request:', {
        requestId: log.getRequestId(),      // UUIDv4 as string
        httpVersion: log.getHttpVersion(),  // e.g., "1.1" or "2.0"
        method: log.getHttpMethod(),        // e.g., "GET", "POST"
        url: log.url,                       // Request URL
        ipAddress: log.getIpAddress()       // IPv4 or IPv6 as string
      });
      break;

    case LogType.REQUEST_META:
      console.log('Request metadata:', {
        requestId: log.getRequestId(),
        data: JSON.parse(log.data)          // Application-specific metadata
      });
      break;

    case LogType.RESPONSE:
      console.log('Response:', {
        requestId: log.getRequestId(),
        statusCode: log.statusCode
      });
      if (log.error) {
        const err = log.getError();
        console.log('Error info:', {
          stack: err.stack,                 // Stack trace (if Error)
          value: err.value,                 // String value (if not Error)
          properties: err.properties,       // Additional error properties
          debugLogs: err.debug              // Retroactive debug logs
        });
      }
      break;

    case LogType.LOG:
      console.log('Ad-hoc log:', {
        requestId: log.getRequestId(),      // May be null
        data: JSON.parse(log.data)
      });
      break;

    case LogType.LIFECYCLE:
      console.log('Lifecycle event:', {
        event: Lifecycle[log.event]         // Event name from enum
      });
      if (log.event === Lifecycle.WORKER_EXITED) {
        console.log('Worker exit:', {
          exitCode: log.exitCode,
          signal: log.signal
        });
      }
      break;

    case LogType.UNCAUGHT_EXCEPTION:
      const error = log.getError();
      console.log('Uncaught exception:', error);
      break;
  }

  // Convert to JSON-compatible object
  const jsonRepresentation = log.toJSON();
}
```

--------------------------------

### Logger Control Methods

Source: https://github.com/wiselibs/super-server-logs/blob/master/docs/writers.md

Methods for manually flushing buffers, rotating log files, and closing the logger.

```APIDOC
## Logger Control Methods

### Description
Provides methods to control the logger's behavior, including flushing buffers, changing log files, and closing the logger.

### `workerLogger.flush()`

#### Description
Manually flushes the logger's internal buffer, writing any buffered logs to the filesystem. This operation is synchronous.

#### Method
`workerLogger.flush()`

#### Notes
- Can be used within `process.on('exit')` handlers.

### `workerLogger.rotate(filename)`

#### Description
Changes the logger's output file to the specified new filename. This operation is synchronous.

#### Method
`workerLogger.rotate(filename)`

#### Parameters
- **filename** (string) - Required - The new path for the log file.

### `workerLogger.close()`

#### Description
Closes the logger, flushing any remaining logs to the filesystem. This operation is synchronous.

#### Method
`workerLogger.close()`

#### Notes
- Can be used within `process.on('exit')` handlers.

### Request Example
```javascript
workerLogger.flush();
workerLogger.rotate('/var/log/new-worker.log');
workerLogger.close();
```

### Response
These methods do not return a value.
```

--------------------------------

### reader.bulkRange

Source: https://github.com/wiselibs/super-server-logs/blob/master/docs/readers.md

Yields chunks of raw binary logs within a specified timestamp range.

```APIDOC
## reader.bulkRange(minTimestamp, maxTimestamp)

### Description
Yields chunks of raw binary logs within the specified timestamp range (inclusive). Logs are yielded in ascending order (older logs first).

### Method
GET (conceptual)

### Endpoint
Not applicable (this is a method call on a reader object)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **minTimestamp** (number) - Required - The minimum timestamp (inclusive). This indicates where to start reading from.
- **maxTimestamp** (number) - Required - The maximum timestamp (inclusive). This indicates when to stop reading.

### Returns
- **AsyncIterable<Buffer>** - An asynchronous iterable yielding chunks of raw binary log data within the specified range.

### Request Example
```js
const DAY = 1000 * 60 * 60 * 24;

for await (const chunk of reader.bulkRange(Date.now() - DAY, Date.now())) {
	ssocket.write(chunk);
}
```

### Response
#### Success Response (200)
- **Buffer** (Buffer) - A chunk of raw binary log data.

#### Response Example
```json
// Raw binary data representing log chunks
```
```

--------------------------------

### Super Server Logs Enums Reference

Source: https://context7.com/wiselibs/super-server-logs/llms.txt

Reference for various enums used in Super Server Logs, including LogType for categorizing log entries, LogLevel for severity, Lifecycle for cluster events, and HttpMethod for HTTP request types. These enums help in understanding and filtering log data.

```javascript
const { LogType, LogLevel, Lifecycle, HttpMethod } = require('super-server-logs');

// LogType - Types of log entries
LogType.REQUEST           // HTTP request received
LogType.REQUEST_META      // Request metadata
LogType.RESPONSE          // HTTP response sent
LogType.RESPONSE_FINISHED // Response body completed
LogType.LOG               // Ad-hoc log entry
LogType.LIFECYCLE         // Cluster lifecycle event
LogType.UNCAUGHT_EXCEPTION // Uncaught exception

// LogLevel - Severity levels
LogLevel.CRITICAL // Critical error, application non-functional
LogLevel.ERROR    // Unexpected error affecting user
LogLevel.WARN     // Unexpected condition, may need investigation
LogLevel.INFO     // Normal application behavior with value
LogLevel.INTERNAL // Internal logging system use

// Lifecycle - Cluster lifecycle events
Lifecycle.STARTING_UP             // Master process starting
Lifecycle.STARTING_UP_COMPLETED   // All workers online
Lifecycle.SHUTTING_DOWN           // Shutdown initiated
Lifecycle.SHUTTING_DOWN_COMPLETED // All workers exited
Lifecycle.WORKER_SPAWNED          // Worker process spawned
Lifecycle.WORKER_STARTED          // Worker beginning setup
Lifecycle.WORKER_GOING_ONLINE     // Worker HTTP server started
Lifecycle.WORKER_ONLINE           // Worker HTTP server started
Lifecycle.WORKER_GOING_OFFLINE    // Worker shutting down
Lifecycle.WORKER_OFFLINE          // Worker HTTP server stopped
Lifecycle.WORKER_DONE             // Worker teardown complete
Lifecycle.WORKER_EXITED           // Worker process exited

// HttpMethod - Standard HTTP methods
HttpMethod.GET
HttpMethod.HEAD
HttpMethod.POST
HttpMethod.PUT
HttpMethod.PATCH
HttpMethod.DELETE
HttpMethod.OPTIONS
HttpMethod.TRACE
HttpMethod.CONNECT
```

--------------------------------

### Parse Reversed Bulk Log Streams

Source: https://context7.com/wiselibs/super-server-logs/llms.txt

Process bulk log streams in reverse order, parsing each block into LogEntry objects. This is useful for analyzing logs from most recent to oldest.

```javascript
// For reverse-order bulk streams
async function parseReverseBulkLogs(chunks) {
  for await (const block of BulkParser.readReversed(chunks)) {
    for (const log of BulkParser.parse(block)) {
      console.log(log.timestamp, log.type);
    }
  }
}
```

--------------------------------

### LogManager Class

Source: https://github.com/wiselibs/super-server-logs/blob/master/docs/writers.md

Facilitates log rotation by managing log files within a directory, enforcing size and age limits, and providing filenames for loggers.

```APIDOC
## LogManager Class

This class facilitates log rotation. It should be used within the master process of your server cluster. It keeps track of log files within a directory, detects when the log files get too big or too old, and deletes the oldest files when necessary. It also provides the filenames that your loggers should write to.

> Note that two (or more) server clusters must not write to the same log directory concurrently. Attempting to do so will likely lead to corrupted logs.

LogManager is a subclass of EventEmitter.

### new LogManager(dirname[, options])

- `dirname` (string) - The path of the log directory.
- `options` (Object) - Optional configuration for the LogManager.
  - `pollInterval` (number) - The delay, in milliseconds, between each poll to the filesystem. **Default:** `5000`.
  - `logSizeLimit` (number) - The total maximum size (in bytes) of all logs in the directory. **Default:** `2147483648` (2 GiB).
  - `logAgeLimit` (number) - The maximum age, in milliseconds, that logs are allowed to have. **Default:** `31536000000` (1 year).
  - `granularity` (number) - The granularity used to enforce `logSizeLimit` and `logAgeLimit`. **Default:** `20`.

If the given `dirname` does not yet exist, it is created.

### Event: 'rotate'

- `filename` (string) - The path of the new log file that should be used by all loggers.

This event is emitted when the LogManager wants you to change the file that all loggers are writing to. You should first call `.rotate(filename)` on the MasterLogger, and then call `.rotate(filename)` on each WorkerLogger. You'll need to utilize IPC to send this instruction from the master process to each worker process.

### Event: 'error'

- `error` (Error) - An error object indicating a filesystem operation failure.

This event indicates that an error occurred during some filesystem operation. Despite this, the LogManager will continue trying to function until explicitly closed.
```

--------------------------------

### Read Raw Log Chunks within a Range

Source: https://github.com/wiselibs/super-server-logs/blob/master/docs/readers.md

Utilize `reader.bulkRange` to fetch raw binary log chunks within a given timestamp range. This method is suitable for efficiently transferring logs to external systems, though it may include logs slightly outside the specified bounds.

```js
const DAY = 1000 * 60 * 60 * 24;

for await (const chunk of reader.bulkRange(Date.now() - DAY, Date.now())) {
	socket.write(chunk);
}
```
Tokens:
Raw