# @restorecommerce/logger

> Opinionated wrapper and configurator for the winston logging toolkit

Latest version **1.4.3** (published 2026-08-05) · MIT license · 0 weekly downloads

## Install

```sh
npm install @restorecommerce/logger
pnpm add @restorecommerce/logger
yarn add @restorecommerce/logger
bun add @restorecommerce/logger
```

## Health

**Score 65/100 (B)** — status: active.

Positive: has types; no vulnerabilities; recently updated; high maintenance score; high quality score.

Warnings: low downloads; no esm support.

## Facts

| | |
|---|---|
| Version | 1.4.3 |
| Published | 2026-08-05 |
| First published | 2017-10-11 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Node | >= 12.18.0 |
| Dependencies | 6 |
| Unpacked size | 80.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 7 |
| Author | n-fuse GmbH |
| Maintainers | vanthome, akumarnpm, dani723, vilsol, radu1990 |
| Keywords | restore, commerce, logger |

## Links

- npm: https://www.npmjs.com/package/@restorecommerce/logger
- Repository: https://github.com/restorecommerce/libs
- npm.io page: https://npm.io/package/@restorecommerce/logger

## Dependencies (6)

- [lodash](https://npm.io/package/lodash.md) 4.18.1
- [winston](https://npm.io/package/winston.md) 3.19.0
- [cls-hooked](https://npm.io/package/cls-hooked.md) 4.2.2
- [cls-rtracer](https://npm.io/package/cls-rtracer.md) 2.6.4
- [source-map-support](https://npm.io/package/source-map-support.md) 0.5.21
- [winston-elasticsearch](https://npm.io/package/winston-elasticsearch.md) 0.19.0

## Alternatives

- [cli-color](https://npm.io/package/cli-color.md) — 3.4M weekly downloads
- [log](https://npm.io/package/log.md) — 1.3M weekly downloads
- [logstash-client](https://npm.io/package/logstash-client.md) — 4.5K weekly downloads
- [@nocobase/plugin-logger](https://npm.io/package/@nocobase/plugin-logger.md) — 2.0K weekly downloads
- [child-process-debug](https://npm.io/package/child-process-debug.md) — 695 weekly downloads

## Recent versions

- 1.4.3 (latest) — 2026-08-05
- 1.4.2 — 2026-07-03
- 1.4.1 — 2026-06-16
- 1.4.0 — 2026-06-12
- 1.3.8 — 2025-10-06
- 1.3.7 — 2025-10-02
- 1.3.6 — 2025-09-17
- 1.3.5 — 2025-09-17
- 1.3.4 — 2025-05-27
- 1.3.3 — 2025-05-14
- 1.3.2 — 2024-11-04
- 1.3.1 — 2024-06-26
- 1.3.0 — 2024-06-26
- 1.2.11 — 2024-06-07
- 1.2.10 — 2024-03-05
- … 68 more at https://npm.io/package/@restorecommerce/logger/versions

## README

# @restorecommerce/logger

[![Version][version]](https://www.npmjs.com/package/@restorecommerce/logger)[![Build Status][build]](https://travis-ci.org/restorecommerce/logger?branch=master)[![Dependencies][depend]](https://david-dm.org/restorecommerce/logger)[![Coverage Status][cover]](https://coveralls.io/github/restorecommerce/logger?branch=master)

[version]: http://img.shields.io/npm/v/@restorecommerce/logger.svg?style=flat-square
[build]: http://img.shields.io/travis/restorecommerce/logger/master.svg?style=flat-square
[depend]: https://img.shields.io/david/restorecommerce/logger.svg?style=flat-square
[cover]: http://img.shields.io/coveralls/restorecommerce/logger/master.svg?style=flat-square

Opinionated wrapper and configurator for the
[winston](https://github.com/winstonjs/winston) logging toolkit.

The following transports are supported:

- [Elasticsearch transport](https://github.com/vanthome/winston-elasticsearch) using a local transformer function and ES data streams.
- [index template](elasticsearch-index-template.json) which is applied automatically.
- Console (Winston built-in transport).
- File (Winston built-in transport).

These transports can be added and configured with a corresponding property in
the options hash:

```json
{
  "loggerName": "somelogger",        // Optional name
  "sourcePointer": true,             // Whether the source file and line where the log statement was issued should be logged [default: `false`]
  "esTransformer": function(),       // Transformer function to transform the structured data (meta data) logged as JS object
  "console": {
    "handleExceptions": false,
    "level": "silly",
    "colorize": true,
    "prettyPrint": true
  },
  "file": {
    ...
  },
  "elasticsearch": {
    "stringifyMeta": true,           // Whether the structured data (meta data) logged as JS object should be stringified [default: `true`]
    ...
  }
}
```

The logger returns a Winston logger instance which has methods that correspond
to the following levels:

- silly
- verbose
- debug
- info
- warn
- error
- log (generic)

In addition there is a generic `log()` function.

## Features

- Source pointer logging -- show the source code file and line where the log statement was issued.
- Implicit Request ID logging based on [cls-rtracer](https://github.com/puzpuzpuz/cls-rtracer).
- Logger `AsyncLocalStorage` logger context to log implicit context information.
- Supports local transformer function for the `fields`.
- masking fields, omit fields and buffer fields removal from logging or unmarsahall buffer fields and then logging based on configuration.

An example how to use the `AsyncLocalStorage` logger context can be found [here](test/test.js#L4-L11).
An example how to use field options for masking fields or buffer fields can be found [here](test/test.js#L30-L35).

### Console logger

A custom format is defined that outputs the rid (request-id) if it is set
and the contents of the `AsyncLocalStorage` context.

### Elastichsearch logger

The following changes and transformations are applied to log messages:

- Adds a `@timestamp` field with the current date/ time
- Adds a `host` property with the current host name
- Adds a `rid` request-id
- Grabs all key/ values from the the current `AsyncLocalStorage` and merges them to the logged message

This module also comes with a suitable
[index pattern](kibana/Logs-Index-Pattern.ndjson) that can be imported in Kibana.

## Usage

### Instantiation

```js
let logger = createLogger(opts);
```

### Logging

Logging in general:

```js
logger.<level>('Textual message');

// or

logger.log(<level>, 'Textual message');
```

The parameters for the log statements are built like this:

```js
logger.info('Textual message');

// or

logger.info({ key: 'value' });

// or

logger.info('Textual message', { key: 'value' });
```

No other variants are supported.

See [test.ts](test/test.ts) and the
[Winston documentation](https://github.com/winstonjs/winston).

---
_Source: https://npm.io/package/@restorecommerce/logger · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._