@supscale/logger — TypeScript

TypeScript implementation of the @supscale/logger library. Ships structured logs to Grafana Loki with batching, retry, and zero runtime dependencies.

Requires Node.js 20+ (uses native fetch).

Installation

npm install @supscale/logger

Usage

import { Logger } from '@supscale/logger';

const logger = new Logger({
    url: 'https://loki.example.com',
    apiKey: 'your-api-key',
    app: 'my-app',
});

logger.info('User signed in');
logger.warn('Disk usage above 80%');
logger.error('Payment processing failed');

Logs are buffered and sent in batches automatically. To flush manually:

await logger.flush();

Graceful Shutdown

Always call shutdown() before your process exits to ensure all buffered logs are sent:

process.on('SIGTERM', async () => {
    await logger.shutdown();
    process.exit(0);
});

Configuration

const logger = new Logger({
    url: 'https://loki.example.com',  // Loki base URL (required)
    apiKey: 'your-api-key',           // Sent via X-Api-Key header (required)
    app: 'my-app',                    // App label in Loki (required)
    batchInterval: 5000,              // Flush interval in ms (default: 5000)
    batchSize: 100,                   // Max entries before auto-flush (default: 100)
    requestTimeout: 30000,            // HTTP request timeout in ms (default: 30000)
});

API

new Logger(config: LoggerConfig)

Creates a new logger instance. Starts a background timer that flushes buffered logs at the configured interval.

logger.debug(message: string): void

logger.info(message: string): void

logger.warn(message: string): void

logger.error(message: string): void

logger.fatal(message: string): void

Append a log entry to the buffer. Returns immediately (non-blocking). If the buffer reaches batchSize, a flush is triggered automatically.

logger.flush(): Promise<void>

Sends all buffered logs to Loki. Retries up to 3 times with exponential backoff on transient errors (5xx, 429, network failures).

logger.shutdown(): Promise<void>

Flushes remaining logs and clears the background timer. Call this before process exit.

Types

type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'fatal';

interface LoggerConfig {
    url: string;
    apiKey: string;
    app: string;
    batchInterval?: number;
    batchSize?: number;
    requestTimeout?: number;
}

Behavior

| Concern | Detail | |---------|--------| | Batching | Logs accumulate in memory, flushed every batchInterval ms or when batchSize is reached | | Retry | Up to 3 retries with exponential backoff (1s, 2s, 4s) on 5xx, 429, or network errors | | No retry | 4xx client errors (except 429) are not retried | | Non-blocking | Log methods return immediately; flushes run async in the background | | Timeout | Each HTTP request is aborted after requestTimeout ms (default: 30s) | | Timer | Uses unref() so the flush timer doesn't prevent process exit |

Development

# Install dependencies
npm install

# Build (ESM + CJS + type declarations)
npm run build

# Run tests
npm test

# Watch mode (rebuild on change)
npm run dev

License

MIT