A Pino transport that automatically rolls your log files
npm install pino-rollA Pino transport that automatically rolls your log files.
``
npm i pino-roll
`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)
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 _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.logs/app.log
- If a filename with an extension is provided (e.g., ) 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 daily
- The amount of time a given log file is used.
- Can be combined with size.
- Accepted values:
- -> rotates the file once per day.hourly
- -> rotates the file once per hour.daily
- Number -> interpreted as milliseconds.
- When using 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:
- Default extension only applied if the provided filename does not already contain an extension.
* symlink?: boolean current.log
- If enabled, creates a symbolic link () pointing to the active log file.false
- On each rotation, the symlink is updated to reference the newly created log file.
- Default:
* limit?: object count
- Defines the strategy for removing old log files during rotation.
- Supports two optional properties: 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 , will remove files not created by the current process. false
- When or undefined, the count limit only applies to files generated by the current process.
* dateFormat?: string date-fns
- 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 (see: date-fns format documentation).'yyyy-MM-dd'
- For example:
- Daily: -> error.2024-09-24.log
- Hourly: -> error.2024-09-24-05.log`
MIT