# pino-roll

> A Pino transport that automatically rolls your log files

Latest version **4.0.0** (published 2025-10-06) · MIT license · 0 weekly downloads

## Install

```sh
npm install pino-roll
pnpm add pino-roll
yarn add pino-roll
bun add pino-roll
```

## Health

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

Positive: no vulnerabilities; high maintenance score.

Warnings: low downloads; no types; no esm support.

## Facts

| | |
|---|---|
| Version | 4.0.0 |
| Published | 2025-10-06 |
| First published | 2022-05-06 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 2 |
| Unpacked size | 89.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 116 |
| Author | Damien Simonin Feugas |
| Maintainers | feugy, matteo.collina |
| Keywords | pino, transport |

## Links

- npm: https://www.npmjs.com/package/pino-roll
- Repository: https://github.com/mcollina/pino-roll
- Homepage: https://github.com/mcollina/pino-roll#readme
- Issues: https://github.com/mcollina/pino-roll/issues
- npm.io page: https://npm.io/package/pino-roll

## Dependencies (2)

- [date-fns](https://npm.io/package/date-fns.md) ^4.1.0
- [sonic-boom](https://npm.io/package/sonic-boom.md) ^4.0.1

## 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

- 4.0.0 (latest) — 2025-10-06
- 3.1.0 — 2025-03-27
- 3.0.0 — 2025-02-03
- 2.2.0 — 2024-10-28
- 2.1.0 — 2024-09-27
- 2.0.0 — 2024-09-21
- 1.3.0 — 2024-08-30
- 1.2.0 — 2024-08-02
- 1.1.0 — 2024-04-08
- 1.0.1 — 2024-03-19
- 1.0.0 — 2024-03-19
- 1.0.0-rc.1 — 2022-05-06

## README

# pino-roll

A Pino transport that automatically rolls your log files.

## Install

```
npm i pino-roll
```

## Usage

```js
import { join } from 'path'
import pino from 'pino'

const transport = pino.transport({
  target: 'pino-roll',
  options: { file: join('logs', 'log'), frequency: 'daily', mkdir: true }
})

const logger = pino(transport)
```

(Also works in CommonJS)


## API

### build(options) => SonicBoom

Creates a Pino transport (a Sonic-boom stream) to writing into files.
Automatically rolls your files based on a given frequency, size, or both.

#### Options

You can specify any of [Sonic-Boom options](https://github.com/pinojs/sonic-boom#sonicboomopts) _except `dest`_

* **`file`**: `string | () => string`

  - Absolute or relative path to the log file.
  - Your application must have write access to the parent folder.
  - A rotation number will be appended to this filename.
  - When the parent folder already contains numbered files, numbering will continue based on the highest number.
  - If this path does not exist, the logger will throw an error unless you set `mkdir` to `true`.
  - `file` may also be a function that returns a string.

  - To ensure consistency, rotated filenames now always follow the **Extension Last Format** convention:
    ```
    filename.date.count.extension
    (e.g., prod.2025-08-19.1.log)
    ```
    > The date segment is optional.

    - When no filename (e.g., `logs/`) or if a directory is passed, a default filename `app.log` will be used.

      Resulting file: `logs/app.2025-08-19.1.log`.

    - If a filename is provided without an extension (e.g., `logs/app`), the default extension `.log` will be used.
    - If a filename with an extension is provided (e.g., `logs/app.log`) and an explicit extension is set (e.g., `.json`), the explicit extension takes precedence → `logs/app.json`.

  - **Filename validation:**
    - Filenames are validated against Windows path restrictions.
    - Disallowed characters: `< > : " | ? *` (to ensure cross-platform safety).

* **`size?`**: `number | string`

  - Maximum size of a single log file before rotation.
  - Can be combined with frequency.
  - Accepts units:
    - `k` -> kilobytes (KB)
    - `m` -> megabytes (MB)
    - `g` -> gigabytes (GB)
  - If no unit is provided:
    - **Numbers** are interpreted as MB.
    - Strings without units (e.g., "100") are also treated as MB.
  - Rotation occurs as soon as the file size reaches or exceeds the specified limit.

* **`frequency?`**: `number | string` 
  - The amount of time a given log file is used.
  - Can be combined with size.
  - Accepted values:
    - `daily` -> rotates the file once per day.
    - `hourly` -> rotates the file once per hour.
    - Number -> interpreted as milliseconds.
  - When using `daily` or `hourly`, any existing file for the current period will be reused.
  - When using a *numeric value*, rotation happens at the start/end of each specified interval.

* **`extension?`**: `string`
  - The file extension to use for rotated log files.
  - Default: `.log`
  - Default extension only applied if the provided filename does not already contain an extension.

* **`symlink?`**: `boolean` 
  - If enabled, creates a symbolic link (`current.log`) pointing to the active log file.
  - On each rotation, the symlink is updated to reference the newly created log file.
  - Default: `false`

* **`limit?`**: `object` 
  - Defines the strategy for removing old log files during rotation.
  - Supports two optional properties: `count` and `removeOtherLogFiles`.

  * **`limit.count?`**: `number`
    - Maximum number of log files to retain in addition to the active file.
    - For example, if count is 3, a total of 4 files will be kept (3 rotated + 1 active).

  * **`limit.removeOtherLogFiles?`**: `boolean`
    - When `true`, will remove files not created by the current process. 
    - When `false` or `undefined`, the `count` limit only applies to files generated by the current process.

* **`dateFormat?`**: `string` 
  - Defines the format for appending the current date/time to the log file name.
  - When specified, appends the date/time in the provided format to the log file name.
  - Supports date formats from `date-fns` (see: [date-fns format documentation](https://date-fns.org/v4.1.0/docs/format)).
  - For example:
    - Daily: `'yyyy-MM-dd'` -> `error.2024-09-24.log`
    - Hourly: `'yyyy-MM-dd-hh'` -> `error.2024-09-24-05.log`

## License

MIT

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