# @mcf/logger

> Exposes a logger based on Winston. It includes formats and plugins for integration with the Morgan request logging library, and xray request distributed tracing library.

Latest version **0.4.47** (published 2026-02-04) · MIT license · 0 weekly downloads

## Install

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

## Health

**Score 55/100 (C)** — status: stable.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.4.47 |
| Published | 2026-02-04 |
| First published | 2018-07-17 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 2 |
| Unpacked size | 32.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | vicheng.gt, npm-govtechsg-mcf-sh |

## Links

- npm: https://www.npmjs.com/package/@mcf/logger
- Repository: https://github.com/GovTechSG/mcf-boilerplate-js
- Homepage: https://github.com/GovTechSG/mcf-boilerplate-js#readme
- Issues: https://github.com/GovTechSG/mcf-boilerplate-js/issues
- npm.io page: https://npm.io/package/@mcf/logger

## Dependencies (2)

- [winston](https://npm.io/package/winston.md) 3.8.2
- [fluent-logger](https://npm.io/package/fluent-logger.md) 3.4.1

## Recent versions

- 0.4.47 (latest) — 2026-02-04
- 0.4.46 — 2025-10-30
- 0.4.45 — 2025-01-13
- 0.4.44 — 2024-09-11
- 0.4.43 — 2024-08-21
- 0.4.42 — 2023-07-17
- 0.4.40 — 2023-05-29
- 0.4.39 — 2023-03-08
- 0.4.38 — 2023-03-07
- 0.4.37 — 2022-11-29
- 0.4.36 — 2022-11-15
- 0.4.35 — 2022-09-20
- 0.4.34 — 2022-08-02
- 0.4.33 — 2022-07-12
- 0.4.32 — 2022-04-13
- … 43 more at https://npm.io/package/@mcf/logger/versions

## README

[![npm version](https://badge.fury.io/js/%40mcf%2Flogger.svg)](https://badge.fury.io/js/%40mcf%2Flogger)

# `@mcf/logger`
Exposes a logger based on Winston. It includes formats and plugins for integration with the Morgan request logging library, and Zipkin request distributed tracing library.

## Scope

- [x] Basic logging
- [x] Allows for formatter extensions
- [x] Allows for transport extensions
- [x] Console transport creator
- [x] File transport creator
- [x] FluentD transport creator
- [x] Fluent transport security configuration
- [x] Fluent transport ID tagger

## Installation
Install it via `npm` or `yarn`:

```sh
npm i @mcf/logger
# or
yarn add @mcf/logger
```

## Usage

### Requiring
```js
import {createConsoleTransport, createFluentTransport, createLogger} from '@mcf/logger';
// or
const {createConsoleTransport, createFluentTransport, createLogger} = require('@mcf/logger');
```

### Basic
By default, the logger already logs to the console and no configuration is needed. This should suffice for basic apps.

```js
const basicLogger = createLogger();
basicLogger.silly('a silly hi');
basicLogger.debug('a debug hi');
basicLogger.http('a http hi');
basicLogger.info('a info hi');
basicLogger.warn('a warn hi');
basicLogger.error('a error hi');
```

### FluentD
We use [fluent](https://www.fluentd.org/) for our centralised logs collector. To initialise the transport, create the logger as such:

```js
const fluentLogger = createLogger({
  additionalTransports: [
    createFluentTransport({
      host: 'localhost',
      port: 44224,
      timeout: 2.0,
      requireAckResponse: false,
    }),
  ],
  // optional message transformation, depends on your elasticsearch setup
  formatters: [
    (info) => {
      const messageIsObject = typeof info.message === 'object';
      return {
        ...info,
        message: messageIsObject ? 'meta' : info.message,
        meta: messageIsObject ? info.message : undefined,
      };
    },
  ],
});

fluentLogger.info('hello world!');
```

The following `fluent.conf` should get you up and running:

```xml
<source>
  @type forward
  bind 0.0.0.0
  port 24224
</source>

<match **.*>
  @type stdout
</match>
```

See the [usage example](./examples/usage) for more examples of creating plaintext/encrypted loggers.

## Documentation
The library exposes the following methods:

| Method | Description |
| --- | --- |
| `.createLogger` | Creates the logger object which can be used |
| `.createFluentTransport` | Creates a FluentD compatible transport |
| `.createConsoleTransport` | Creates a Console transport |
| `.createFileTransport` | Creates a File transport |
| `.createMorganStream` | Creates an object consumable by Morgan |

### `.createLogger(:options)`
This function accepts a configuration object as the parameter where the keys are documented as follows:

| Key | Description | Default |
| --- | --- | --- |
| `additionalTransports` | Winston transports to be added on (no overriding of the default Console transport) | `[]` |
| `formatters` | Winston formatters created via `winston.format(...)()` | `[]` |
| `level` | Default level (`ENUM { "error", "warn", "info", "http", "debug", "silly" }`) | `"silly"` |
| `namespace` | Give a name to your logger) | `give-me-a-name` |
| `silent` | Set to true to turn off logging | `false` |
| `transports` | Winston transports | `[winston.transports.Console()]` |

### `.createFluentTransport(:options)`
This function accepts a configuration object as the parameter where the keys are documented as follows:

| Key | Description | Default |
| --- | --- | --- |
| `host` | FluentD service hostname | `"localhost"` |
| `port` | FluentD service port | `24224` |
| `requireAckResponse` | Specifies whether we should connect via TCP (`true`) or UDP (`false`) | `false` |
| `security` | A security object with `.clientHostname` : `string` and `.sharedKey` : `string` properties | `undefined` |
| `tag` | Tag for the logs | `process.env.HOSTNAME || os.hostname() || 'unknown'` |
| `tls` | Specifies if we should use TLS | `true` |
| `tlsOptions` | Specifies an options object for the TLS connection which has a `.ca` property | `undefined` |
| `timeout` | Timeout for a push | `3.0` |

This is referenced from [the `fluent-logger` library](https://github.com/fluent/fluent-logger-node).

### `.createConsoleTransport(:options)`
This function accepts a configuration object as the parameter where the keys are documented as follows:


| Key | Description | Default |
| --- | --- | --- |
| `format` | Winston formatters created via `winston.format(...)()` | Combination of `colorize` and custom `printf` displaying `namespace`, `timestamp`, `level` and `message` |

### `.createFileTransport(:options)`
This function accepts a configuration object as the parameter where the keys are documented as follows:


| Key | Description | Default |
| --- | --- | --- |
| `format` | Winston formatters created via `winston.format(...)()` | Custom `printf` displaying `namespace`, `timestamp`, `level` and `message` |
| `filename` | Filename to output | undefined |

### `.createMorganStream(:options)`
This function returns an object that can be used by Morgan to specify a write stream.

The properties for the `:options` object are:

| Key | Description | Default |
| --- | --- | --- |
| `logLevel` | The desire level of logs to use for request logs by Morgan | `"silly"` |
| `logger` | The logger instance to be used | `undefined` |

## Examples
Confirm all dependencies have been installed:

```bash
yarn;
```

To run the `usage` example, set up FluentD first:

```bash
yarn svc:fluent;
```

In another terminal, run the usage application which will pipe to the FluentD instance:

```bash
yarn demo-usage;
```

To stop FluentD, run:

```bash
yarn svc:fluent:stop;
```

## Changelog

### 0.2.x
#### 0.2.1
Added in stream creator for Morgan (see `.createMorganStream`)
#### 0.2.0
Added more:
  - Fluent transport security configuration (`.security`)
  - Fluent transport ID tagger (`.tag`)
  - Fluent transport TLS support (`.tls` and `.tlsOptions`)
### 0.1.x
#### 0.1.0
Initial release with:
  - Basic logging
  - Allows for formatter extensions
  - Allows for transport extensions
  - FluentD transport creator
  - Console transport creator

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