The PrettyOptions interface provides comprehensive configuration for all aspects of log prettification, from display formatting to filtering and custom extensions.
interface PrettyOptions {
// Display Options
colorize?: boolean;
colorizeObjects?: boolean;
crlf?: boolean;
hideObject?: boolean;
singleLine?: boolean;
levelFirst?: boolean;
// Key Mapping Options
messageKey?: string;
levelKey?: string;
levelLabel?: string;
timestampKey?: string;
errorLikeObjectKeys?: string[];
// Filtering Options
minimumLevel?: string | number;
ignore?: string;
include?: string;
// Formatting Options
translateTime?: boolean | string;
messageFormat?: false | string | MessageFormatFunc;
errorProps?: string;
// Custom Levels and Colors
customLevels?: string | object;
customColors?: string | object;
useOnlyCustomProps?: boolean;
customPrettifiers?: Record<string, Prettifier> & { level?: Prettifier };
// Output Options (for build() function)
destination?: string | number | DestinationStream | NodeJS.WritableStream;
sync?: boolean;
append?: boolean;
mkdir?: boolean;
}Controls whether terminal color codes are added to output.
/**
* Enable or disable terminal colors
* @default Based on terminal capability (isColorSupported)
*/
colorize?: boolean;Usage Examples:
// Enable colors
pinoPretty({ colorize: true });
// Disable colors
pinoPretty({ colorize: false });
// Auto-detect (default)
pinoPretty({ colorize: undefined });Controls colorization of object values in log output.
/**
* Apply coloring to rendered objects when colorize is enabled
* @default true
*/
colorizeObjects?: boolean;Usage Example:
// Colorize objects (default when colorize: true)
pinoPretty({
colorize: true,
colorizeObjects: true
});
// Disable object colorization but keep level colors
pinoPretty({
colorize: true,
colorizeObjects: false
});Controls line ending style.
/**
* End lines with \r\n instead of \n
* @default false
*/
crlf?: boolean;Usage Example:
// Unix line endings (default)
pinoPretty({ crlf: false });
// Windows line endings
pinoPretty({ crlf: true });Controls whether objects are displayed in output.
/**
* Hide objects from output (error objects are still shown)
* @default false
*/
hideObject?: boolean;Usage Example:
// Show all objects (default)
pinoPretty({ hideObject: false });
// Hide objects, only show structured fields
pinoPretty({ hideObject: true });
// Input: { level: 30, msg: 'hello', user: { id: 1, name: 'Alice' } }
// Output: [10:30:45] INFO: helloControls single-line vs multi-line output.
/**
* Print each log on a single line (errors still multi-line)
* @default false
*/
singleLine?: boolean;Usage Example:
// Multi-line output (default)
pinoPretty({ singleLine: false });
// Output:
// [10:30:45] INFO: hello
// userId: 123
// action: "login"
// Single-line output
pinoPretty({ singleLine: true });
// Output: [10:30:45] INFO: hello userId: 123 action: "login"Controls position of level in output.
/**
* Display log level before timestamp
* @default false
*/
levelFirst?: boolean;Usage Example:
// Time first (default)
pinoPretty({ levelFirst: false });
// Output: [10:30:45] INFO: hello
// Level first
pinoPretty({ levelFirst: true });
// Output: INFO [10:30:45]: helloSpecifies the key containing the log message.
/**
* The key in log object containing the message
* @default "msg"
* @note Not required with Pino >= 8.21.0 (auto-detected via PINO_CONFIG)
*/
messageKey?: string;Usage Example:
// Default message key
pinoPretty({ messageKey: 'msg' });
// Custom message key
pinoPretty({ messageKey: 'message' });
// Input: { level: 30, message: 'hello' }
// Output: [10:30:45] INFO: helloSpecifies the key containing the log level.
/**
* The key in log object containing the level
* Supports nested keys with dot notation and escaping
* @default "level"
*/
levelKey?: string;Usage Example:
// Default level key
pinoPretty({ levelKey: 'level' });
// Custom level key
pinoPretty({ levelKey: 'severity' });
// Nested level key
pinoPretty({ levelKey: 'meta.level' });
// Escaped dots in key name
pinoPretty({ levelKey: 'tags\\.level' });
// Matches property named "tags.level" (literal dot)Token name for level label in messageFormat.
/**
* Token name to use in messageFormat for level label
* @default "levelLabel"
*/
levelLabel?: string;Usage Example:
pinoPretty({
levelLabel: 'severity',
messageFormat: '{severity}: {msg}'
});Specifies the key containing the timestamp.
/**
* The key in log object containing the timestamp
* @default "time"
*/
timestampKey?: string;Usage Example:
// Default timestamp key
pinoPretty({ timestampKey: 'time' });
// Custom timestamp key
pinoPretty({ timestampKey: 'timestamp' });
pinoPretty({ timestampKey: 'ts' });Specifies keys that contain error objects.
/**
* Keys associated with error-like objects
* @default ["err", "error"]
* @note Not required with Pino >= 8.21.0 (auto-detected via PINO_CONFIG)
*/
errorLikeObjectKeys?: string[];Usage Example:
// Default error keys
pinoPretty({ errorLikeObjectKeys: ['err', 'error'] });
// Custom error keys
pinoPretty({ errorLikeObjectKeys: ['exception', 'failure'] });
// Multiple error keys
pinoPretty({ errorLikeObjectKeys: ['err', 'error', 'exception', 'e'] });Sets minimum log level to display.
/**
* Minimum log level to include in output
* Can be level name or number
* @default undefined (show all)
*/
minimumLevel?: string | number;Usage Example:
// Filter by level name
pinoPretty({ minimumLevel: 'info' });
// Shows: info, warn, error, fatal
// Hides: trace, debug
// Filter by level number
pinoPretty({ minimumLevel: 30 });
// Shows: 30 and above
// Hides: 10, 20
// Show all levels (default)
pinoPretty({ minimumLevel: undefined });Specifies keys to exclude from output.
/**
* Comma-separated list of keys to ignore in output
* Supports nested keys with dot notation and escaping
* Overridden by include option if both are set
* @default "hostname"
*/
ignore?: string;Usage Example:
// Ignore single key
pinoPretty({ ignore: 'hostname' });
// Ignore multiple keys
pinoPretty({ ignore: 'pid,hostname' });
// Ignore nested keys
pinoPretty({ ignore: 'pid,req.headers' });
// Ignore keys with literal dots
pinoPretty({ ignore: 'log\\.domain\\.corp/foo' });Specifies keys to include in output (whitelist mode).
/**
* Comma-separated list of keys to include in output
* When set, only these keys are shown (overrides ignore)
* @default undefined (show all except ignored)
*/
include?: string;Usage Example:
// Include only specific keys
pinoPretty({ include: 'level,time,msg' });
// Include with nested keys
pinoPretty({ include: 'level,time,msg,user.id' });
// Note: include overrides ignore
pinoPretty({
ignore: 'hostname,pid',
include: 'level,time,msg,hostname'
});
// Result: hostname IS shown (include wins)Controls timestamp formatting.
/**
* Translate epoch time to human-readable format
* - false: no translation
* - true: default format "HH:MM:ss.l" in local time
* - string: custom format (see dateformat package)
* - "UTC:" prefix: format in UTC
* - "SYS:" prefix: format in system timezone
* - "SYS:standard": shortcut for "yyyy-mm-dd HH:MM:ss.l o"
* @default false
*/
translateTime?: boolean | string;Usage Examples:
// No translation (show epoch)
pinoPretty({ translateTime: false });
// Default format
pinoPretty({ translateTime: true });
// Output: [10:30:45.123]
// Custom format
pinoPretty({ translateTime: 'HH:MM:ss' });
// Output: [10:30:45]
// Full date and time
pinoPretty({ translateTime: 'yyyy-mm-dd HH:MM:ss' });
// Output: [2023-12-09 10:30:45]
// UTC time
pinoPretty({ translateTime: 'UTC:yyyy-mm-dd HH:MM:ss.l o' });
// Output: [2023-12-09 15:30:45.123 +00:00]
// System timezone
pinoPretty({ translateTime: 'SYS:HH:MM:ss' });
// System timezone standard format
pinoPretty({ translateTime: 'SYS:standard' });
// Output: [2023-12-09 10:30:45.123 -05:00]Custom message formatting template or function.
/**
* Custom message format
* - false: default format
* - string: template with {tokens} and {if condition}{end} blocks
* - function: custom formatter function
* @default false
*/
messageFormat?: false | string | MessageFormatFunc;
type MessageFormatFunc = (
log: Record<string, unknown>,
messageKey: string,
levelLabel: string,
extras: { colors: Colorette }
) => string;Usage Examples:
// Template string
pinoPretty({
messageFormat: '{levelLabel} - {pid} - {msg}'
});
// Output: INFO - 1234 - hello world
// With conditionals
pinoPretty({
messageFormat: '{levelLabel} - {if pid}{pid} - {end}{msg}'
});
// Output: INFO - 1234 - hello world (if pid exists)
// Output: INFO - hello world (if pid doesn't exist)
// Nested properties
pinoPretty({
messageFormat: '{levelLabel} - url:{req.url} - {msg}'
});
// Function format
pinoPretty({
messageFormat: (log, messageKey, levelLabel, { colors }) => {
const msg = log[messageKey];
if (log.requestId) {
return colors.bold(`[${log.requestId}] ${msg}`);
}
return msg;
}
});Specifies error properties to display.
/**
* Comma-separated list of error properties to display
* @default ""
* @deprecated Use with caution, support may be removed in future
*/
errorProps?: string;Usage Example:
// Show specific error properties
pinoPretty({ errorProps: 'stack,code,message' });
// Show all common error properties
pinoPretty({ errorProps: 'name,message,stack,code,signal' });Define custom log levels.
/**
* Custom level names and values
* - string: CSV format "name:value,name:value"
* - object: { name: value, name: value }
* @default undefined
* @note Not required with Pino >= 8.21.0 (auto-detected via PINO_CONFIG)
*/
customLevels?: string | object;Usage Examples:
// CSV format
pinoPretty({
customLevels: 'verbose:5,info:10,warning:40,severe:99'
});
// Object format
pinoPretty({
customLevels: {
verbose: 5,
info: 10,
warning: 40,
severe: 99
}
});Define custom level colors.
/**
* Custom colors for log levels
* - string: CSV format "level:color,level:color"
* - object: { level: color, level: color }
* Supports "default" as fallback color
* @default undefined
*/
customColors?: string | object;Usage Examples:
// CSV format
pinoPretty({
customColors: 'info:blue,warn:yellow,error:bgRed,default:gray'
});
// Object format
pinoPretty({
customColors: {
info: 'blue',
warn: 'yellow',
error: 'bgRed',
default: 'gray'
}
});Controls fallback to default levels/colors.
/**
* Only use custom levels and colors without fallback to defaults
* @default true
*/
useOnlyCustomProps?: boolean;Usage Example:
// Only use custom (default)
pinoPretty({
customLevels: 'severe:99',
customColors: 'severe:red',
useOnlyCustomProps: true
});
// Level 30 (INFO) will use default "USERLVL" label
// Use custom + defaults
pinoPretty({
customLevels: 'severe:99',
customColors: 'severe:red',
useOnlyCustomProps: false
});
// Level 30 (INFO) will use default "INFO" labelCustom formatter functions for specific properties.
/**
* Custom prettifier functions for log properties
* Key = property name, Value = prettifier function
* Special keys: time, level, hostname, pid, name, caller
* @default {}
*/
customPrettifiers?: Record<string, Prettifier> & {
level?: Prettifier;
};
type Prettifier = (
inputData: string | object,
key: string,
log: object,
extras: PrettifierExtras
) => string;
interface PrettifierExtras {
colors: Colorette;
label: string; // For level prettifier
labelColorized: string; // For level prettifier
}Usage Example:
pinoPretty({
customPrettifiers: {
time: (timestamp) => new Date(timestamp).toISOString(),
level: (logLevel, key, log, { label, labelColorized }) => {
return `[${labelColorized}]`;
},
hostname: (hostname) => hostname.toUpperCase(),
userId: (id, key, log, { colors }) => {
return colors.bold(`USER:${id}`);
}
}
});Output destination for prettified logs.
/**
* Output destination
* - number: file descriptor (1=stdout, 2=stderr)
* - string: file path
* - WritableStream: Node.js stream
* - object: SonicBoom instance
* @default 1 (stdout)
*/
destination?: string | number | DestinationStream | NodeJS.WritableStream;Usage Examples:
// Stdout (default)
pinoPretty({ destination: 1 });
// Stderr
pinoPretty({ destination: 2 });
// File path
pinoPretty({ destination: './logs/pretty.log' });
// Custom stream
const fs = require('fs');
pinoPretty({ destination: fs.createWriteStream('./app.log') });
// SonicBoom instance
const SonicBoom = require('sonic-boom');
pinoPretty({
destination: new SonicBoom({
dest: './app.log',
mkdir: true
})
});Controls synchronous vs asynchronous writing.
/**
* Make output synchronous (useful for testing)
* @default false
*/
sync?: boolean;Usage Example:
// Async writing (default)
pinoPretty({ sync: false });
// Sync writing (for tests)
pinoPretty({ sync: true });Controls file opening mode.
/**
* Open destination file with 'a' (append) flag
* @default true
*/
append?: boolean;Usage Example:
// Append to file (default)
pinoPretty({
destination: './app.log',
append: true
});
// Overwrite file
pinoPretty({
destination: './app.log',
append: false
});Controls directory creation.
/**
* Create destination directory if it doesn't exist
* @default false
*/
mkdir?: boolean;Usage Example:
// Don't create directories (default)
pinoPretty({
destination: './logs/app.log',
mkdir: false
});
// Create directories as needed
pinoPretty({
destination: './logs/sub/app.log',
mkdir: true
});