Class AsyncLogger

High-performance asynchronous logger using worker threads.

Offloads CPU-intensive operations like serialization and I/O to worker threads, keeping the main event loop responsive. Ideal for high-throughput applications that cannot afford blocking operations.

AsyncLogger

Since

1.0.0

Example: Basic usage

const logger = new AsyncLogger({
  transports: [new ConsoleTransport()],
  worker: { poolSize: 2 }
});

// Non-blocking log operations
logger.info('Server started');
logger.error('Connection failed', { host: 'db.example.com' });

// Graceful shutdown
await logger.close();

Example: With metrics monitoring

const logger = new AsyncLogger({
  enableMetrics: true,
  worker: {
    poolSize: 4,
    batchSize: 1000
  }
});

// Monitor performance
logger.on('metrics', (metrics) => {
  console.log(`Processed: ${metrics.totalLogs}`);
  console.log(`Worker utilization: ${metrics.workerUtilization}%`);
});

Hierarchy

EventEmitter
- AsyncLogger

Index

Constructors

constructor

new AsyncLogger(options?: AsyncLoggerOptions): AsyncLogger
Creates a new AsyncLogger instance.
Parameters
- Optionaloptions: AsyncLoggerOptions = {}
  Configuration options
Returns AsyncLogger
Throws
If worker thread creation fails
Overrides EventEmitter.constructor
- Defined in async/AsyncLogger.ts:436

Accessors

fmt

get fmt(): TemplateFormatter
Template literal formatter for inline styling. Uses the same TemplateParser as Logger for consistency.

Returns TemplateFormatter
Template formatter function
Example
```
const user = 'john';
logger.info(logger.fmt`@green.bold{User ${user}} logged in`);
logger.error(logger.fmt`@red{Error:} @yellow{${errorMessage}}`);
```
- Defined in async/AsyncLogger.ts:1313

s

get s(): IStyleBuilder
Style chain for creating styled messages (matches Logger API). Provides chainable style methods for text formatting.

Returns IStyleBuilder
Chainable style builder
Example
```
logger.info(logger.s.red.bold('Error:') + ' Connection failed');
```
- Defined in async/AsyncLogger.ts:1283

style

get style(): IStyleBuilder
Alias for the style builder (s). Provides a more descriptive name for the chainable style API.

Returns IStyleBuilder
Chainable style builder
- Defined in async/AsyncLogger.ts:1295

Methods

addTransport

addTransport(transport: Transport): void
Adds a transport to the logger.
Parameters
- transport: Transport
  Transport to add
Returns void
- Defined in async/AsyncLogger.ts:1239

close

close(): Promise<void>
Closes the logger and terminates worker threads.

Returns Promise<void>
Resolves when closed
Example
```
// Graceful shutdown
process.on('SIGTERM', async () => {
  await logger.close();
  process.exit(0);
});
```
- Defined in async/AsyncLogger.ts:1407

debug

debug(message: string, meta?: Record<string, unknown>): { success: boolean }
Logs a debug-level message.
Parameters
- message: string
  Debug message
- Optionalmeta: Record<string, unknown>
  Optional metadata
Returns { success: boolean }
Result of the log operation
- Defined in async/AsyncLogger.ts:1131

error

error(
message: string,
error?: Error | Record<string, unknown>,
): { success: boolean }
Logs an error-level message.
Parameters
- message: string
  Error message
- Optionalerror: Error | Record<string, unknown>
  Error or metadata
Returns { success: boolean }
Result of the log operation
Example
```
try {
  await database.connect();
} catch (error) {
  logger.error('Database connection failed', error);
}
```
- Defined in async/AsyncLogger.ts:1103

flush

flush(): Promise<void>
Flushes the current batch to workers or transports.

Returns Promise<void>
Promise that resolves when flush is complete
- Defined in async/AsyncLogger.ts:928

flushAndWait

flushAndWait(): Promise<void>
Flushes all pending logs and waits for completion.

Returns Promise<void>
Promise that resolves when flush is complete
- Defined in async/AsyncLogger.ts:1227

getMetrics

getMetrics(): AsyncLoggerMetrics
Gets current performance metrics.

Returns AsyncLoggerMetrics
Current metrics
- Defined in async/AsyncLogger.ts:1184

getStats

getStats(): {
    buffer: {
        capacity: number;
        current: number;
        dropped: number;
        size: number;
        utilization: number;
    };
    metrics: AsyncLoggerMetrics;
}
Gets current logger statistics including buffer information.

Returns {
    buffer: {
        capacity: number;
        current: number;
        dropped: number;
        size: number;
        utilization: number;
    };
    metrics: AsyncLoggerMetrics;
}
Statistics object with buffer and performance info
- Defined in async/AsyncLogger.ts:1194

getUtilization

getUtilization(): number
Gets the current buffer utilization percentage.

Returns number
Utilization percentage (0-100)
- Defined in async/AsyncLogger.ts:1162

info

info(message: string, meta?: Record<string, unknown>): { success: boolean }
Logs an info-level message.
Parameters
- message: string
  Message to log
- Optionalmeta: Record<string, unknown>
  Optional metadata
Returns { success: boolean }
Result of the log operation
Example
```
logger.info('User logged in', { userId: 123, ip: '192.168.1.1' });
```
- Defined in async/AsyncLogger.ts:1082

isBackpressured

isBackpressured(): boolean
Checks if the logger is experiencing backpressure.

Returns boolean
True if backpressured
- Defined in async/AsyncLogger.ts:1173

listTransports

listTransports(): string[]
Lists all transport names.

Returns string[]
Array of transport names
- Defined in async/AsyncLogger.ts:1267

logCritical

logCritical(
    level: string,
    message: string,
    meta?: Record<string, unknown>,
): Promise<void>
Logs a critical message with retry on failure.
Parameters
- level: string
  Log level
- message: string
  Log message
- Optionalmeta: Record<string, unknown>
  Optional metadata
Returns Promise<void>
Promise that resolves when logged
- Defined in async/AsyncLogger.ts:1144

removeTransport

removeTransport(name: string): void
Removes a transport from the logger.
Parameters
- name: string
  Name of transport to remove
Returns void
- Defined in async/AsyncLogger.ts:1253

waitForReady

waitForReady(): Promise<void>
Waits for logger initialization to complete.

Returns Promise<void>
Resolves when ready
- Defined in async/AsyncLogger.ts:1388

warn

warn(message: string, meta?: Record<string, unknown>): { success: boolean }
Logs a warning-level message.
Parameters
- message: string
  Warning message
- Optionalmeta: Record<string, unknown>
  Optional metadata
Returns { success: boolean }
Result of the log operation
- Defined in async/AsyncLogger.ts:1119

Class AsyncLogger

Since

Example: Basic usage

Example: With metrics monitoring

Hierarchy

Index

Constructors

Accessors

Methods

Constructors

constructor

Parameters

Returns AsyncLogger

Throws

Accessors

fmt

Returns TemplateFormatter

Example

s

Returns IStyleBuilder

Example

style

Returns IStyleBuilder

Methods

addTransport

Parameters

Returns void

close

Returns Promise<void>

Example

debug

Parameters

Returns { success: boolean }

error

Parameters

Returns { success: boolean }

Example

flush

Returns Promise<void>

flushAndWait

Returns Promise<void>

getMetrics

Returns AsyncLoggerMetrics

getStats

Returns { buffer: { capacity: number; current: number; dropped: number; size: number; utilization: number; }; metrics: AsyncLoggerMetrics;}

getUtilization

Returns number

info

Parameters

Returns { success: boolean }

Example

isBackpressured

Returns boolean

listTransports

Returns string[]

logCritical

Parameters

Returns Promise<void>

removeTransport

Parameters

Returns void

waitForReady

Returns Promise<void>

warn

Parameters

Returns { success: boolean }

Settings

On This Page

Returns {
buffer: {
capacity: number;
current: number;
dropped: number;
size: number;
utilization: number;
};
metrics: AsyncLoggerMetrics;
}