Skip to content

api-reference.md

Latest commit

 

History

History
159 lines (115 loc) · 6.2 KB

api-reference.md

File metadata and controls

159 lines (115 loc) · 6.2 KB
Raw

API Reference

This page provides a detailed reference for the core classes and methods in Zario.

Logger Class

The primary class for creating loggers. Provides error event notification via the 'error' event for transport, aggregator, and enricher failures.

Constructor

new Logger(options?: LoggerOptions)

Static Properties

Logger.defaultTransportsFactory

(isProd: boolean) => TransportConfig[] | null

Overrides environment-based default transport selection.

Logger.retryTransportFactory

(options: RetryTransportOptions) => Transport | null

Factory used when retryOptions is provided on LoggerOptions. Root zario import configures this automatically.

Events

'error'

Emitted when an error occurs in the logging pipeline (transports, aggregators, or enrichers).

  • Payload: { type: string, error: unknown }
  • Types: 'transport', 'aggregator', 'enricher'
logger.on('error', ({ type, error }) => {
  console.error(`Error in ${type}:`, error);
});

Logging Methods

All logging methods accept a message string and an optional metadata object.

  • debug(message, metadata?)
  • info(message, metadata?)
  • warn(message, metadata?)
  • error(message, metadata?)
  • fatal(message, metadata?)
  • boring(message, metadata?)
  • silent(message, metadata?)
  • logWithLevel(level: string, message: string, metadata?: object): Log using a custom level name.

Instance Methods

createChild(options: LoggerOptions): Logger

Creates a new logger instance that inherits the configuration of the current logger. The new options are merged with the parent's.

  • Prefixes are appended (e.g., [Parent][Child]).
  • Context is merged.
  • Transports, Filters, and Enrichers are inherited.

startTimer(name: string): Timer

Starts a performance timer. Returns a Timer object.

  • timer.end(): Ends the timer and logs the duration (e.g., Database query took 150ms).

addFilter(filter: Filter) / removeFilter(filter: Filter)

Dynamically adds or removes a filter from the logger.

addAggregator(aggregator: LogAggregator) / removeAggregator(aggregator: LogAggregator)

Dynamically adds or removes an aggregator.

addEnricher(enricher: LogEnricher)

Adds an enrichment function or object to the structured logging pipeline.

setAsyncMode(enabled: boolean)

Toggles asynchronous logging mode at runtime.

flushAggregators(): Promise<void>

Manually flushes all registered aggregators. Useful before application shutdown.

Timer Object

Returned by logger.startTimer().

  • end(): Calculates elapsed time since startTimer was called and logs it using logger.info(). It is idempotent; subsequent calls do nothing.

Constants & Types

LogLevel

An union type of built-in levels: 'silent' | 'boring' | 'debug' | 'info' | 'warn' | 'error' | 'fatal'.

LoggerRetryOptions

Equivalent to RetryTransportOptions without wrappedTransport. Used in LoggerOptions.retryOptions.

Transport

Interface for log transports. See Transports for implementations.

FileTransportOptions

  • path: string - Target file path.
  • maxSize?: number - Maximum file size before rotation.
  • maxFiles?: number - Maximum number of rotated files to keep.
  • compression?: 'gzip' | 'deflate' | 'none' - Compression type.
  • compressOldFiles?: boolean - Whether to compress old files.

MemoryQueueOptions

  • maxQueueSize?: number - Maximum size of the queue before invoking the overflow strategy. Default: 10000.
  • flushInterval?: number - Interval in milliseconds to flush buffered logs (0 to flush on the next tick via setImmediate). Default: 0.
  • batchSize?: number - Maximum size of the batch to write to transports. Default: 100.
  • overflowStrategy?: 'drop-oldest' | 'drop-newest' | 'sync' - Strategy to use when the queue is full. Default: 'drop-oldest'.

HttpTransportOptions

  • url: string - Remote endpoint.
  • method?: string - HTTP method (default: 'POST').
  • headers?: object - HTTP headers.
  • timeout?: number - Request timeout in ms.
  • retries?: number - Number of retries on failure.
  • forceAsync?: boolean - Force asynchronous behavior even when calling synchronous write() method.

CircuitBreakerTransportOptions

  • threshold?: number - Failure count before tripping circuit breaker (default: 5).
  • timeout?: number - Time in ms to wait in half-open state (default: 60000).
  • resetTimeout?: number - Auto-reset timer in ms.
  • onStateChange?: function - Callback for state changes: (fromState: string, toState: string) => void.
  • onTrip?: function - Callback when circuit trips: (failureCount: number) => void.
  • onReset?: function - Callback when circuit resets: () => void.

DeadLetterQueueOptions

  • transport: Transport - Required. Transport to wrap.
  • maxRetries?: number - Maximum retry attempts (default: 3).
  • retryableErrorCodes?: string[] - Error codes worth retrying (default: network errors).
  • deadLetterFile?: string - File path to store failed logs.
  • onDeadLetter?: function - Callback for captured dead letters: (deadLetter: DeadLetterLog) => void.

DeadLetterLog

Extends LogData with additional dead letter metadata:

  • deadLetterReason: string - Human-readable error message.
  • originalError?: string - Error code from original failure.
  • retryCount: number - Number of retry attempts made.
  • failedAt: Date - When the log failed permanently.

Aggregators

See Advanced Usage for aggregator details.

BatchAggregator(maxSize, flushCallback, maxQueueSize?)

  • maxSize: number - Number of logs to collect before flushing.
  • flushCallback: function - Callback to handle the batch of logs.
  • maxQueueSize?: number - Maximum number of logs to keep in memory queue. Default: 10000.

TimeBasedAggregator(flushInterval, flushCallback, maxQueueSize?)

  • flushInterval: number - Time interval in ms between flushes.
  • flushCallback: function - Callback to handle the batch of logs.
  • maxQueueSize?: number - Maximum number of logs to keep in memory queue. Default: 10000.

← Configuration | Transports →