@developer-at/logger

A reusable Winston logger package with context support for Node.js services. Provides structured logging with trace ID, user ID, and request source tracking.

Installation

npm install @developer-at/logger

Features

• Winston-based logging with console transport
• Context-aware logging (trace ID, user ID, request source)
• Structured log output with timestamps
• Service name labeling
• TypeScript support

Usage

Basic Setup

import { logger } from '@developer-at/logger';

// Set environment variable for service name (optional)
process.env.SERVICE_NAME = 'my-service';

// Basic logging
logger.info('Application started');
logger.warn('This is a warning');
logger.error('An error occurred');

With Context Information

import { logger } from '@developer-at/logger';

// Set context information
logger.setTraceId('trace-123-456');
logger.setUserId('user-789');
logger.setRequestFrom('API');

// Log with context
logger.info('User logged in', { userId: 'user-789' });
logger.error('Failed to process request', { error: 'Database connection failed' });

Express.js Integration Example

import express from 'express';
import { logger } from '@developer-at/logger';

const app = express();

// Middleware to set trace context
app.use((req, res, next) => {
  const traceId = req.headers['x-trace-id'] as string || `trace-${Date.now()}`;
  const userId = req.headers['x-user-id'] as string;
  
  logger.setTraceId(traceId);
  if (userId) logger.setUserId(userId);
  logger.setRequestFrom('API');
  
  next();
});

app.get('/users', (req, res) => {
  logger.info('Fetching users');
  // ... your logic
  logger.info('Users fetched successfully');
  res.json({ users: [] });
});

Using LoggerUtils Class Directly

import { LoggerUtils } from '@developer-at/logger';

// Create a custom logger instance
const customLogger = new LoggerUtils();
customLogger.setTraceId('custom-trace');
customLogger.setUserId('custom-user');
customLogger.setRequestFrom('Worker');

customLogger.info('Processing job');
customLogger.error('Job failed', { error: 'Timeout' });

API Reference

logger (Singleton Instance)

Pre-configured logger instance ready to use.

LoggerUtils Class

Main logger utility class.

constructor()

Initializes a new LoggerUtils instance with Winston logger.

setTraceId(traceId: string)

Sets the trace ID for request tracking.

Parameters:

• traceId (string): Unique trace identifier

setUserId(userId: string)

Sets the user ID for logging context.

Parameters:

• userId (string): User identifier

setRequestFrom(requestFrom: string)

Sets the request source for logging context.

Parameters:

• requestFrom (string): Source of the request (e.g., 'API', 'Worker', 'Cron')

info(...logs: any[])

Logs an informational message.

Parameters:

• ...logs (any[]): One or more log messages or objects

Example:

logger.info('User created', { userId: '123', email: '[email protected]' });

warn(...logs: any[])

Logs a warning message.

Parameters:

• ...logs (any[]): One or more log messages or objects

Example:

logger.warn('Rate limit approaching', { current: 90, limit: 100 });

error(...logs: any[])

Logs an error message.

Parameters:

• ...logs (any[]): One or more log messages or objects

Example:

logger.error('Database connection failed', { error: error.message, stack: error.stack });

Configuration

Environment Variables

• SERVICE_NAME: Service name to include in log labels (optional, defaults to empty string)

Log Format

Logs are output in the following format:

• Label: Service name (from SERVICE_NAME env var)
• Timestamp: MMM-DD-YYYY HH:mm:ss format
• Level: Log level (info, warn, error)
• Trace: Object containing traceId, userId, and requestFrom
• Logs: Array of log messages/objects

Example Log Output

{
  "level": "info",
  "message": "",
  "label": "my-service",
  "timestamp": "Jan-15-2024 10:30:45",
  "trace": {
    "traceId": "trace-123-456",
    "userId": "user-789",
    "requestFrom": "API"
  },
  "logs": [
    "User logged in",
    {
      "userId": "user-789",
      "action": "login"
    }
  ]
}

TypeScript Support

The package includes full TypeScript definitions and is written in TypeScript.

Dependencies

• winston: ^3.19.0

License

ISC