Skip to content

A Lightweight logger that combines debug namespacing capabilities with winston levels and multioutput

License

Notifications You must be signed in to change notification settings

tduyng/node-logger

This branch is 62 commits ahead of ekino/node-logger:master.

Folders and files

NameName
Last commit message
Last commit date

Latest commit

ef6856e · Feb 18, 2025
Feb 6, 2025
Feb 18, 2025
Oct 29, 2024
Oct 28, 2024
Oct 26, 2024
Feb 17, 2025
Feb 17, 2025
Mar 25, 2020
Nov 10, 2022
Jan 5, 2023
Oct 28, 2024
Jun 2, 2017
Feb 17, 2025
Feb 6, 2025
Nov 27, 2024
Feb 18, 2025
Feb 18, 2025
Feb 6, 2025
Oct 26, 2024
Oct 26, 2024

Repository files navigation

@ekino/logger

A lightweight, flexible logger that merges debug-style namespace management, Winston-inspired log levels, and customizable multi-output functionality.

NPM version Coverage Status

Table of Contents

Features

  • Set log levels globally or per namespace for detailed control.
  • Supports JSON, Pretty-print, and custom output adapters.
  • Optionally track logs across function calls by assigning a unique context ID.
  • Fully written in TypeScript for improved safety and ease of use.
  • Supports both ESM and CommonJS imports.
  • Works with Node.js, Deno, and Bun environments.

Installation

Install via npm, yarn or pnpm:

npm  add @ekino/logger
yarn add @ekino/logger
pnpm add @ekino/logger

Usage

By default, @ekino/logger outputs warn and error levels for all namespaces, with logs written to stdout in JSON format.

Adjust the log level globally or per namespace using the LOG_LEVEL environment variable or programmatically with setLevel and setNamespaces.

Basic logging

@ekino/logger provides five log levels: trace, debug, info, warn, and error. Setting a specific level enables it and all higher-priority levels.

By default, setting info will enable info, warn, and error, but not debug or trace. The log levels are defined as:

Log level priorities:

{ trace: 0, debug: 1, info: 2, warn: 3, error: 4 }

Example:

import { setNamespaces, setLevel, createLogger } from '@ekino/logger'

setNamespaces('root:*')
setLevel('debug')

const logger = createLogger('root:testing')
logger.debug('Sample debug message', { foo: 'bar' })

Output example:

Example

Context ID

For traceability, the logger supports a contextId, helping to link logs across calls. You can either provide a custom contextId or let the logger auto-generate one.

const logger = createLogger('app:example')
logger.debug('ctxId', 'Log with predefined context ID', { foo: 'bar' })
// Or logger.debug('Log with predefined context ID', { foo: 'bar' })

Output example:

Example

Namespaces and levels

Namespaces offer flexibility for selectively enabling logs. Set a default global log level and configure specific namespaces with unique levels, including none to disable.

To configure namespaces:

const { setLevel, setNamespaces } = require('@ekino/logger')

setLevel('info')
setNamespaces('*,database*=debug,database:redis*=none')

Example of using namespace-specific logging:

const loggerA = createLogger('namespace:subNamespace')
const loggerB = createLogger('namespace:mute')

loggerA.debug('This will be logged')
loggerB.info('This will not be logged')

Output formats

@ekino/logger supports multiple output formats with default JSON logging to stdout. You can enable pretty output or create custom adapters.

JSON format

The JSON output adapter logs structured data, ideal for integration with log collectors.

setOutput(outputs.json)
const logger = createLogger('namespace:subNamespace')
logger.debug('ctxId', 'Log message', { someData: 'value' })

Output example:

Example

Pretty format

The Pretty format outputs logs in a YAML-like style for enhanced readability in local development.

setOutput(outputs.pretty)
const logger = createLogger('namespace:subNamespace')
logger.debug('ctxId', 'Log message', { someData: 'value' })

Output example:

Example

Custom output functions

Custom output functions allow flexible handling of log data. Pass an array of adapters for multiple outputs.

const consoleAdapter = (log) => {
    console.log(outputUtils.stringify(log))
}

setOutput([outputs.pretty, consoleAdapter])
const logger = createLogger('namespace:subNamespace')
logger.debug('ctxId', 'Log message', { someData: 'value' })

Log data and metadata

Adding metadata to logs enhances context and helps filter data in log collectors. Add custom data directly or globally to each log instance.

const logger = createLogger('namespace:subNamespace')
logger.warn('Log message', { additionalData: 'value' })

Output example:

Example

Adding global metadata

Use setGlobalContext to add metadata, such as app version or environment, to all log entries.

setGlobalContext({ version: '2.0.0', env: 'dev' })
const logger = createLogger('namespace')
logger.warn('Log message', { additionalData: 'value' })

Output example:

Example

Force logging

Override the log level for critical messages by forcing them to be logged:

logger.debug('Will be logged regardless of level', { forceLogging: true })

Benchmark

Below is a performance comparison of several popular Node.js logging libraries, including @ekino/logger. Benchmarks were conducted using Node.js v23.13.0, with results measured in operations per second (higher values indicate better performance).

┌─────────┬──────────────────────┬───────────┐
│ (index) │ library              │ ops/sec   │
├─────────┼──────────────────────┼───────────┤
│ 0       │ '@ekino/logger v3.x''129,082' │
│ 1       │ 'Pino''112,727' │
│ 2       │ '@ekino/logger v2.x''112,423' │
│ 3       │ 'Winston''55,411'  │
└─────────┴──────────────────────┴───────────┘

Note: Benchmark results may vary depending on environment and configuration. This table provides a general reference for relative performance between libraries.

For more detailed benchmark results, please refer to the benchmarks folder.

Contributing

Contributions are welcome! Please refer to our CONTRIBUTING.md for guidelines on submitting issues, improvements, and more.

About

A Lightweight logger that combines debug namespacing capabilities with winston levels and multioutput

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages

  • TypeScript 82.3%
  • JavaScript 17.5%
  • Shell 0.2%