or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

container-management.mddefault-logger.mdexception-rejection-handling.mdformats.mdindex.mdlogger-management.mdprofiling.mdtransports.md
tile.json

tessl/npm-winston

A comprehensive, multi-transport logging library for Node.js applications providing flexible and extensible logging capabilities.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/winston@3.17.x

To install, run

npx @tessl/cli install tessl/npm-winston@3.17.0

index.mddocs/

Winston

Winston is a comprehensive, multi-transport logging library for Node.js applications that provides flexible and extensible logging capabilities. It supports multiple storage destinations (transports) like console output, files, databases, and remote services, with configurable log levels and custom formatting options.

Package Information

  • Package Name: winston
  • Package Type: npm
  • Language: JavaScript with TypeScript definitions
  • Installation: npm install winston

Core Imports

const winston = require('winston');

ES Modules:

import winston from 'winston';

Named imports:

import { createLogger, format, transports } from 'winston';

Basic Usage

const winston = require('winston');

// Create a logger
const logger = winston.createLogger({
  level: 'info',
  format: winston.format.json(),
  defaultMeta: { service: 'user-service' },
  transports: [
    new winston.transports.File({ filename: 'error.log', level: 'error' }),
    new winston.transports.File({ filename: 'combined.log' })
  ]
});

// Add console transport for development
if (process.env.NODE_ENV !== 'production') {
  logger.add(new winston.transports.Console({
    format: winston.format.simple()
  }));
}

// Log messages
logger.error('Something went wrong');
logger.warn('This is a warning');
logger.info('Hello distributed log files!');
logger.debug('Debugging info');

// Use default logger directly
winston.info('Using default logger');

Architecture

Winston is built around several key components:

  • Logger: Core logging class that manages transports and formats log messages
  • Transports: Storage destinations for log messages (Console, File, HTTP, Stream)
  • Formats: Log message formatting system with composable formatters
  • Container: Management system for multiple named logger instances
  • Exception/Rejection Handling: Automatic handling of uncaught exceptions and unhandled promise rejections
  • Profiling: Built-in performance timing utilities

Capabilities

Logger Creation and Management

Core functionality for creating and configuring logger instances with custom transports, formats, and levels.

function createLogger(options?: LoggerOptions): Logger;

interface LoggerOptions {
  levels?: object;
  silent?: boolean;
  format?: Format;
  level?: string;
  exitOnError?: Function | boolean;
  defaultMeta?: any;
  transports?: Transport[] | Transport;
  handleExceptions?: boolean;
  handleRejections?: boolean;
  exceptionHandlers?: any;
  rejectionHandlers?: any;
}

Logger Management

Built-in Transports

Transport classes for outputting logs to various destinations including console, files, HTTP endpoints, and arbitrary streams.

class Console extends TransportStream {
  constructor(options?: ConsoleTransportOptions);
}

class File extends TransportStream {
  constructor(options: FileTransportOptions);
}

class Http extends TransportStream {
  constructor(options?: HttpTransportOptions);
}

class Stream extends TransportStream {
  constructor(options: StreamTransportOptions);
}

Transports

Default Logger Interface

Direct logging methods available on the winston module for quick access without creating logger instances.

function log(level: string, message: string, ...meta: any[]): Logger;
function error(message: string, ...meta: any[]): Logger;
function warn(message: string, ...meta: any[]): Logger;
function info(message: string, ...meta: any[]): Logger;
function http(message: string, ...meta: any[]): Logger;
function verbose(message: string, ...meta: any[]): Logger;
function debug(message: string, ...meta: any[]): Logger;
function silly(message: string, ...meta: any[]): Logger;

// CLI-specific methods (when using CLI levels)
function help(message: string, ...meta: any[]): Logger;
function data(message: string, ...meta: any[]): Logger;
function prompt(message: string, ...meta: any[]): Logger;
function input(message: string, ...meta: any[]): Logger;

// Syslog-specific methods (when using syslog levels)
function emerg(message: string, ...meta: any[]): Logger;
function alert(message: string, ...meta: any[]): Logger;
function crit(message: string, ...meta: any[]): Logger;
function warning(message: string, ...meta: any[]): Logger;
function notice(message: string, ...meta: any[]): Logger;

// Transport and configuration management
function add(transport: Transport): Logger;
function remove(transport: Transport): Logger;
function clear(): Logger;
function configure(options: LoggerOptions): void;
function child(options: object): Logger;

// Exception and rejection handling
function handleExceptions(...transports: Transport[]): void;
function unhandleExceptions(...transports: Transport[]): void;
function handleRejections(...transports: Transport[]): void;
function unhandleRejections(...transports: Transport[]): void;

// Query and streaming
function query(options?: QueryOptions, callback?: (err: Error, results: any) => void): any;
function stream(options?: any): ReadableStream;

// Profiling
function startTimer(): Profiler;
function profile(id: string | number, meta?: Record<string, any>): Logger;

Default Logger

Container and Multi-Logger Management

Container class for managing multiple named logger instances with shared configurations and lifecycle management.

class Container {
  constructor(options?: LoggerOptions);
  add(id: string, options?: LoggerOptions): Logger;
  get(id: string, options?: LoggerOptions): Logger;
  has(id: string): boolean;
  close(id?: string): void;
}

// Default container instance
const loggers: Container;

Container Management

Exception and Rejection Handling

Automatic handling of uncaught exceptions and unhandled promise rejections with configurable transports and exit behavior.

class ExceptionHandler {
  constructor(logger: Logger);
  handle(...transports: Transport[]): void;
  unhandle(...transports: Transport[]): void;
  getAllInfo(err: string | Error): object;
}

class RejectionHandler {
  constructor(logger: Logger);
  handle(...transports: Transport[]): void;
  unhandle(...transports: Transport[]): void;
  getAllInfo(err: string | Error): object;
}

Exception and Rejection Handling

Profiling and Performance

Built-in profiling utilities for measuring operation performance and logging execution times.

class Profiler {
  constructor(logger: Logger);
  done(info?: any): boolean;
}

function startTimer(): Profiler;
function profile(id: string | number, meta?: Record<string, any>): Logger;

Profiling

Format System

Comprehensive log message formatting system with built-in formatters and composable format transformations.

const format: {
  json: () => Format;
  simple: () => Format;
  combine: (...formats: Format[]) => Format;
  timestamp: (options?: TimestampOptions) => Format;
  colorize: (options?: ColorizeOptions) => Format;
  printf: (templateFunction: (info: any) => string) => Format;
  errors: (options?: ErrorsOptions) => Format;
  label: (options?: LabelOptions) => Format;
  logstash: () => Format;
  prettyPrint: (options?: PrettyPrintOptions) => Format;
  splat: () => Format;
  uncolorize: () => Format;
  align: () => Format;
  cli: (options?: CliOptions) => Format;
  ms: () => Format;
};

interface Format {
  transform: (info: TransformableInfo, options?: any) => TransformableInfo | boolean;
}

Format System

Configuration and Utilities

// Version information
const version: string;

// Configuration utilities
const config: {
  npm: object;
  cli: object;
  syslog: object;
  addColors: (colors: object) => any;
};

// Format system (from logform)
const format: {
  json: () => Format;
  simple: () => Format;
  combine: (...formats: Format[]) => Format;
  timestamp: (options?: object) => Format;
  colorize: (options?: object) => Format;
  printf: (templateFunction: (info: any) => string) => Format;
  // ... and many more formatting options
};

// Transport base class
class Transport {
  constructor(options?: object);
}

// Utility functions
function addColors(colors: object): any;

Global Properties

// Properties available on winston module
let level: string;
let exceptions: ExceptionHandler;
let rejections: RejectionHandler;
let exitOnError: Function | boolean;

Type Definitions

interface TransformableInfo {
  level: string;
  message: string;
  [key: string]: any;
}

interface QueryOptions {
  rows?: number;
  limit?: number;
  start?: number;
  from?: Date;
  until?: Date;
  order?: 'asc' | 'desc';
  fields?: any;
}

interface TimestampOptions {
  format?: string;
  alias?: string;
}

interface ColorizeOptions {
  level?: boolean;
  all?: boolean;
  message?: boolean;
  colors?: object;
}

interface ErrorsOptions {
  stack?: boolean;
}

interface LabelOptions {
  label?: string;
  message?: boolean;
}

interface PrettyPrintOptions {
  depth?: number;
  colorize?: boolean;
}

interface CliOptions {
  levels?: object;
  colors?: object;
}

abstract class TransportStream {
  constructor(options?: object);
  silent: boolean;
  level: string;
  format?: Format;
  log(info: TransformableInfo, callback: () => void): void;
}