@usageflow/logger

UsageFlow logger with pino and silent mode support.

Installation

npm install @usageflow/logger

Usage

Basic Usage

import { usLogger } from '@usageflow/logger';

const logger = usLogger();
logger.info('Hello, world!');
logger.error('An error occurred');

Note: By default, logs are formatted with colors for better readability. You can disable this by setting pretty: false.

Initialize with Service Name

You can initialize the logger with a service name that will be automatically included in all logs:

import { usLogger } from '@usageflow/logger';

// Pass service name in the config object
const logger = usLogger({ service: 'USAGEFLOW_BASE' });
logger.info('Service started');
// Logs will include: { service: 'USAGEFLOW_BASE', msg: 'Service started' }

// With additional options
const logger2 = usLogger({
  service: 'MY_SERVICE',
  silent: false,
});
logger2.info('Another service');
// Logs will include: { service: 'MY_SERVICE', msg: 'Another service' }

Silent Mode

When silent: true is set, the logger will not output any logs:

import { usLogger } from '@usageflow/logger';

const logger = usLogger({ silent: true });
logger.info('This will not be printed');
logger.error('This will not be printed either');

Colored Logs (Pretty Printing)

By default, the logger uses pino-pretty to format logs with colors for better readability. You can control this behavior:

import { usLogger } from '@usageflow/logger';

// Default: colored, formatted logs
const logger = usLogger({ service: 'MY_SERVICE' });
logger.info('This will be colored and formatted');

// Disable pretty printing (use raw JSON logs)
const logger2 = usLogger({
  service: 'MY_SERVICE',
  pretty: false,
});
logger2.info('This will be raw JSON');

With Pino Options

You can pass pino configuration options. Note: if pretty: true (default), the transport option will be used for pretty printing:

import { usLogger } from '@usageflow/logger';

const logger = usLogger({
  service: 'MY_SERVICE',
  silent: false,
  pretty: false, // Disable pretty to use custom pino options
  pinoOptions: {
    level: 'debug',
  },
});

logger.debug('Debug message');

Context Support

You can set context that will be included in all log messages:

import { usLogger } from '@usageflow/logger';

const logger = usLogger();

// Set context that will be included in all logs
logger.setContext({
  component: 'api',
  requestId: 'req-123',
  userId: 'user-456',
});

logger.info('Processing request');
// Logs will include: { component: 'api', requestId: 'req-123', userId: 'user-456', msg: 'Processing request' }

// Update context
logger.setContext({ requestId: 'req-789' }); // Merges with existing context

// Get current context
const context = logger.getContext();

// Remove a specific context key
logger.removeContext('userId');

// Clear all context
logger.clearContext();

Available Methods

• log(message, ...args) - Logs an info message
• info(message, ...args) - Logs an info message
• warn(message, ...args) - Logs a warning message
• error(message, ...args) - Logs an error message
• debug(message, ...args) - Logs a debug message
• trace(message, ...args) - Logs a trace message
• fatal(message, ...args) - Logs a fatal message
• child(bindings) - Creates a child logger with additional bindings
• setSilent(silent) - Sets the silent mode
• isSilent() - Returns whether the logger is in silent mode
• setContext(context) - Set context that will be included in all log messages
• getContext() - Get current context
• clearContext() - Clear all context
• removeContext(key) - Remove a specific context key

Example

import { usLogger } from '@usageflow/logger';

const logger = usLogger({ silent: false });

logger.info('Application started');
logger.warn('This is a warning');
logger.error('This is an error');

// Create a child logger
const childLogger = logger.child({ component: 'api' });
childLogger.info('API request received');

// Toggle silent mode
logger.setSilent(true);
logger.info('This will not be logged');

logger.setSilent(false);
logger.info('This will be logged again');