Logger

The Orion.js Logger is a powerful, flexible logging utility built on top of Winston. It provides structured logging capabilities with customizable formats, transports, and context tracking.

​

Installation

pnpm add @orion-js/logger

​

Basic Usage

import {logger} from '@orion-js/logger'

// Basic logging with different levels
logger.debug('Debug message', {customData: 'value'})
logger.info('Info message', {userId: 123})
logger.warn('Warning message', {attemptCount: 3})
logger.error('Error occurred', new Error('Something went wrong'))

// Add metadata to all subsequent logs from this logger instance
const userLogger = logger.addMetadata({userId: 'user-123'})
userLogger.info('User action', {action: 'login'})

// Add context based on the current module
const contextLogger = logger.addContext(module)
contextLogger.info('Operation completed', {result: 'success'})

​

Features

​

Log Levels

The logger supports the standard log levels:

• error: For error conditions
• warn: For warning conditions
• info: For informational messages
• debug: For debugging information

​

Automatic Contextual Information

Each log message automatically includes:

• Timestamp
• Log level
• File name where the log was triggered (automatically detected)
• OpenTelemetry trace and span IDs (when available)

​

Formatting

The logger supports two main output formats:

1. Text Format (for development):

   • Colorized output
   • Human-readable formatting
   • Activated when ORION_DEV=1 environment variable is set

2. JSON Format (for production):

   • Structured JSON logs
   • Ideal for log aggregation and analysis
   • Default in production environments

​

Error Handling

The logger has special handling for errors:

• When an Error object is passed as the value, the stack trace is properly captured
• Error messages are preserved for easy debugging

​

OpenTelemetry Integration

The logger automatically detects and includes OpenTelemetry trace and span IDs when available, enabling correlation between logs and traces.

​

Advanced Configuration

​

Setting Log Level

import {setLogLevel} from '@orion-js/logger'

// Set the minimum log level to display
setLogLevel('info') // Will show info, warn, and error logs, but not debug

​

Adding Custom Transports

import {addTransport} from '@orion-js/logger'
import {transports} from 'winston'

// Add a file transport
const fileTransport = new transports.File({
  filename: 'application.log',
  level: 'info'
})

addTransport(fileTransport)

​

Complete Logger Configuration

import {configureLogger} from '@orion-js/logger'
import {format, transports} from 'winston'

configureLogger({
  level: 'debug',
  format: format.combine(
    format.timestamp(),
    format.json()
  ),
  transports: [
    new transports.Console(),
    new transports.File({filename: 'combined.log'})
  ]
})

​

Best Practices

1. Add Context: Use logger.addContext(module) at the top of your files to automatically include file information.

2. Structured Data: Pass structured objects instead of concatenating strings:

   // Good
   logger.info('User created', {userId: '123', email: 'user@example.com'})
   
   // Avoid
   logger.info(`User created: userId=123, email=user@example.com`)
   

3. Error Handling: Pass error objects directly instead of just their messages:

   try {
     // some operation
   } catch (error) {
     // Good - preserves stack trace
     logger.error('Operation failed', error)
     
     // Avoid - loses stack trace
     logger.error('Operation failed', {message: error.message})
   }
   

4. Log Appropriate Levels: Use the right log level for each message:

   • debug: Detailed information useful during development
   • info: Normal application behavior, milestones
   • warn: Unexpected but handled issues
   • error: Errors that prevent proper operation