Generated using TypeDoc
Generated using TypeDoc
Generated using TypeDoc
Creates a LogLevelStreamEntry stream that writes to a rolling file at or above the minimum level
Generated using TypeDoc
Generated using TypeDoc
Creates a LogLevelStreamEntry stream that writes to STDERR at or above the minimum level
const buildDestinationStderr = (level: LogLevel, options: Omit<StreamDestination, 'destination'> = {}): LogLevelStreamEntry => {
const opts = {...options, destination: destination({dest: 2, sync: true})};
return buildDestinationStream(level, opts);
}
+buildDestinationStream
+Generated using TypeDoc
Generated using TypeDoc
Creates a LogLevelStreamEntry stream that writes to STDOUT at or above the minimum level
const buildDestinationStdout = (level: LogLevel, options: Omit<StreamDestination, 'destination'> = {}): LogLevelStreamEntry => {
const opts = {...options, destination: destination({dest: 1, sync: true})}
return buildDestinationStream(level, opts);
}
+buildDestinationStream
+Generated using TypeDoc
Generated using TypeDoc
Creates a LogLevelStreamEntry stream that writes to a NodeJs.WriteableStream or Sonic Boom DestinationStream at or above the minimum level
DestinationStream
+Generated using TypeDoc
Generated using TypeDoc
Builds a Logger object for use in your application
+defaultLevel must the minimum level ANY stream can log from IE it should be the lowest level any of your streams will possibly log. Recommended to always use debug.
Logger
+Generated using TypeDoc
Generated using TypeDoc
Builds the opinionated @foxxmd/logging defaults for pino-pretty PrettyOptions and merges them with an optional user-provided PrettyOptions object
Generated using TypeDoc
Generated using TypeDoc
Returns a new logger with the given properties appended to all log objects created by it
+Logger Parent logger to inherit from
+(any | any[]) Labels to always apply to logs from this logger
+object Additional properties to always apply to logs from this logger
+object
+Generated using TypeDoc
Generated using TypeDoc
Generated using TypeDoc
Optional extras: LoggerAppExtrasGenerated using TypeDoc
A Logger that logs to console and a static file
+Optional extras: LoggerAppExtrasGenerated using TypeDoc
Optional extras: LoggerAppExtrasGenerated using TypeDoc
A Logger that logs to console and a rolling file
+Optional extras: LoggerAppExtrasGenerated using TypeDoc
Generated using TypeDoc
Takes an object and parses it into a fully-populated LogOptions object based on opinionated defaults
+Generated using TypeDoc
The package exports 4 top-level loggers.
These are the loggers that should be used for the majority of your application. They accept an optional configuration object for configuring log destinations.
loggerApp - Logs to console and a fixed file destinationloggerAppRolling - Logs to console and a rolling file destinationloggerApp - Logs to console and a fixed file destinationloggerAppRolling - Logs to console and a rolling file destinationThese loggers are pre-defined for specific use cases:
loggerDebug - Logs ONLY to console at minimum debug level. Can be used during application startup before a logger app configuration has been parsed.loggerTest - A noop logger (will not log anywhere) for use in tests/mockups.loggerDebug - Logs ONLY to console at minimum debug level. Can be used during application startup before a logger app configuration has been parsed.loggerTest - A noop logger (will not log anywhere) for use in tests/mockups.The App Loggers take an optional config object.
+The App Loggers take an optional config object LogOptions:
interface LogOptions {
/**
* Specify the minimum log level for all log outputs without their own level specified.
*
* Defaults to env `LOG_LEVEL` or `info` if not specified.
*
* @default 'info'
* */
level?: LogLevel
/**
* Specify the minimum log level streamed to the console (or docker container)
* */
console?: LogLevel
/**
* Specify the minimum log level to output for files or a log file options object. If `false` no log files will be created.
* */
file?: LogLevel | false | FileLogOptions
}
Available LogLevel levels, from lowest to highest:
Available LogLevel levels, from lowest to highest:
debugverboseconst infoLogger = loggerApp({
level: 'info' // console and file will log any levels `info` and above
});
const logger = loggerApp({
console: 'debug', // console will log `debug` and higher
file: 'warn' // file will log `warn` and higher
});
file in LogOptions may be an object that specifies more behavior log files.
file in LogOptions may be an object that specifies more behavior log files.
export interface FileOptions {
/**
* The path and filename to use for log files.
*
* If using rolling files the filename will be appended with `.N` (a number) BEFORE the extension based on rolling status.
*
* May also be specified using env LOG_PATH or a function that returns a string.
*
* If path is relative the absolute path will be derived from the current working directory.
*
* @default 'CWD/logs/app.log'
* */
path?: string | (() => string)
/**
* For rolling log files
*
* When
* * value passed to rolling destination is a string (`path` option) and
* * `frequency` is defined
*
* This determines the format of the datetime inserted into the log file name:
*
* * `unix` - unix epoch timestamp in milliseconds
* * `iso` - Full ISO8601 datetime IE '2024-03-07T20:11:34Z'
* * `auto`
* * When frequency is `daily` only inserts date IE YYYY-MM-DD
* * Otherwise inserts full ISO8601 datetime
*
* @default 'auto'
* */
timestamp?: 'unix' | 'iso' | 'auto'
/**
* The maximum size of a given rolling log file.
*
* Can be combined with frequency. Use k, m and g to express values in KB, MB or GB.
*
* Numerical values will be considered as MB.
* */
size?: number | string
/**
* The amount of time a given rolling log file is used. Can be combined with size.
*
* Use `daily` or `hourly` to rotate file every day (or every hour). Existing file within the current day (or hour) will be re-used.
*
* Numerical values will be considered as a number of milliseconds. Using a numerical value will always create a new file upon startup.
*
* @default 'daily'
* */
frequency?: 'daily' | 'hourly' | number
}
+export interface FileOptions {
/**
* The path and filename to use for log files.
*
* If using rolling files the filename will be appended with `.N` (a number) BEFORE the extension based on rolling status.
*
* May also be specified using env LOG_PATH or a function that returns a string.
*
* If path is relative the absolute path will be derived from the current working directory.
*
* @default 'CWD/logs/app.log'
* */
path?: string | (() => string)
/**
* For rolling log files
*
* When
* * value passed to rolling destination is a string (`path` option) and
* * `frequency` is defined
*
* This determines the format of the datetime inserted into the log file name:
*
* * `unix` - unix epoch timestamp in milliseconds
* * `iso` - Full ISO8601 datetime IE '2024-03-07T20:11:34-00:00'
* * `auto`
* * When frequency is `daily` only inserts date IE YYYY-MM-DD
* * Otherwise inserts full ISO8601 datetime
*
* @default 'auto'
* */
timestamp?: 'unix' | 'iso' | 'auto'
/**
* The maximum size of a given rolling log file.
*
* Can be combined with frequency. Use k, m and g to express values in KB, MB or GB.
*
* Numerical values will be considered as MB.
* */
size?: number | string
/**
* The amount of time a given rolling log file is used. Can be combined with size.
*
* Use `daily` or `hourly` to rotate file every day (or every hour). Existing file within the current day (or hour) will be re-used.
*
* Numerical values will be considered as a number of milliseconds. Using a numerical value will always create a new file upon startup.
*
* @default 'daily'
* */
frequency?: 'daily' | 'hourly' | number
}
loggerApp and loggerAppRolling accept an optional second parameter, LoggerAppExtras that allows adding additional log destinations or pino-pretty customization:
loggerApp and loggerAppRolling accept an optional second parameter, LoggerAppExtras that allows adding additional log destinations or pino-pretty customization:
export interface LoggerAppExtras {
/**
* Additional pino-pretty options that are applied to the built-in console/log streams
* */
pretty?: PrettyOptions
/**
* Additional logging destinations to use alongside the built-in console/log stream. These can be any created by buildDestination* functions or other Pino Transports
* */
destinations?: LogLevelStreamEntry[]
}
Some defaults and convenience variables for pino-pretty options are available in @foxxmd/logging/factory prefixed with PRETTY_. See factory variables docs for all options.
An example using the extras parameter:
-import { loggerApp } from '@foxxmd/logging';
import {
PRETTY_ISO8601, // replaces standard timestamp with ISO8601 format
buildDestinationFile
} from "@foxxmd/logging/factory";
const warnFileDestination = buildDestinationFile('warn', {path: './myLogs/warn.log'});
const logger = loggerApp({}, {
destinations: [warnFileDestination],
pretty: {
translateTime: PRETTY_ISO8601
}
});
logger.debug('Test');
// [2024-03-07T11:27:41-05:00] DEBUG: Test
+import { loggerApp } from '@foxxmd/logging';
import {
PRETTY_ISO8601, // replaces standard timestamp with ISO8601 format
buildDestinationFile
} from "@foxxmd/logging/factory";
const warnFileDestination = buildDestinationFile('warn', {path: './myLogs/warn.log'});
const logger = loggerApp({}, {
destinations: [warnFileDestination],
pretty: {
translateTime: PRETTY_ISO8601
}
});
logger.debug('Test');
// [2024-03-07T11:27:41-05:00] DEBUG: Test
See Building A Logger for more information.
-Usage
Child Loggers
Pino Child loggers can be created using the childLogger function with the added ability to inherit Labels from their parent loggers.
+Usage
Child Loggers
Pino Child loggers can be created using the childLogger function with the added ability to inherit Labels from their parent loggers.
Labels are inserted between the log level and message contents of a log. The child logger inherits all labels from all its parent loggers.
childLogger accepts a single string label or an array of string labels.
import {loggerApp, childLogger} from '@foxxmd/logging';
logger = loggerApp();
logger.debug('Test');
// [2024-03-07 11:27:41.944 -0500] DEBUG: Test
const nestedChild1 = childLogger(logger, 'First');
nestedChild1.debug('I am nested one level');
// [2024-03-07 11:27:41.945 -0500] DEBUG: [First] I am nested one level
const nestedChild2 = childLogger(nestedChild1, ['Second', 'Third']);
nestedChild2.warn('I am nested two levels but with more labels');
// [2024-03-07 11:27:41.945 -0500] WARN: [First] [Second] [Third] I am nested two levels but with more labels
const siblingLogger = childLogger(logger, ['1Sib','2Sib']);
siblingLogger.info('Test');
// [2024-03-07 11:27:41.945 -0500] INFO: [1Sib] [2Sib] Test
@@ -89,8 +89,8 @@
const er = new Error('This is the original error');
const causeErr = new ErrorWithCause('A top-level error', {cause: er});
logger.debug(causeErr, 'Test');
/*
[2024-03-07 11:43:27.453 -0500] DEBUG: Test
ErrorWithCause: A top-level error
at <anonymous> (/my/dir/src/index.ts:55:18)
caused by: Error: This is the original error
at <anonymous> (/my/dir/src/index.ts:54:12)
*/
Passing an Error without a second argument (message) will cause the top-level error's message to be printed instead of log message.
-Building A Logger
All the functionality required to build your own logger is exported by @foxxmd/logging/factory. You can customize almost every facet of logging.
-A logger is composed of a minimum default level and array of objects that implement StreamEntry, the same interface used by pino.multistream. The only constraint is that your streams must accept the same levels as @foxxmd/logging using the LogLevelStreamEntry interface that extends StreamEntry.
+Building A Logger
All the functionality required to build your own logger is exported by @foxxmd/logging/factory. You can customize almost every facet of logging.
+A logger is composed of a minimum default level and array of objects that implement StreamEntry, the same interface used by pino.multistream. The only constraint is that your streams must accept the same levels as @foxxmd/logging using the LogLevelStreamEntry interface that extends StreamEntry.
import {LogLevelStreamEntry} from '@foxxmd/logging';
import { buildLogger } from "@foxxmd/logging/factory";
const myStreams: LogLevelStreamEntry[] = [];
// build streams
const logger = buildLogger('debug', myStreams);
logger.debug('Test');
factory exports several "destination" LogLevelStreamEntry function creators with default configurations that can be overridden.
@@ -99,26 +99,26 @@
All buildDestination functions take args:
level (first arg) - minimum level to log atoptions (second arg) - an object extending pino-pretty optionsoptions (second arg) - an object extending pino-pretty options, PrettyOptions
-options inherits a default pino-pretty configuration that comprises @foxxmd/logging's opinionated logging format. The common default config can be generated using prettyOptsFactory which accepts an optional pino-pretty options object to override defaults:
+options inherits a default pino-pretty configuration that comprises @foxxmd/logging's opinionated logging format. The common default config can be generated using prettyOptsFactory which accepts an optional PrettyOptions object to override defaults:
import { prettyOptsFactory } from "@foxxmd/logging/factory";
const defaultConfig = prettyOptsFactory();
// override with your own config
const myCustomizedConfig = prettyOptsFactory({ colorize: false });
Pre-configured PrettyOptions are also provided for different destinations:
import {
prettyConsole, // default config
prettyFile // disables colorize
} from "@foxxmd/logging/factory";
Specific buildDestinations also require passing a stream or path:
-buildDestinationStream must pass a NodeJS.WriteableStream or SonicBoom DestinationStream to options as destination
+buildDestinationStream must pass a NodeJS.WriteableStream or SonicBoom DestinationStream to options as destination
import {buildDestinationStream} from "@foxxmd/logging/factory";
const myStream = new WritableStream();
const dest = buildDestinationStream('debug', {destination: myStream});
-buildDestinationStdout and buildDestinationStderr do not require a destination as they are fixed to STDOUT/STDERR
-buildDestinationFile and buildDestinationRollingFile must pass a path to options
+buildDestinationStdout and buildDestinationStderr do not require a destination as they are fixed to STDOUT/STDERR
+buildDestinationFile and buildDestinationRollingFile must pass a path to options
import {buildDestinationFile} from "@foxxmd/logging/factory";
const dest = buildDestinationFile('debug', {path: '/path/to/file.log'});
Example
Putting everything above together
import {
buildDestinationStream,
buildDestinationFile,
prettyOptsFactory,
buildDestinationStdout,
buildLogger
} from "@foxxmd/logging/factory";
import { PassThrough } from "node:stream";
const hookStream = new PassThrough();
const hookDestination = buildDestinationStream('debug', {
...prettyOptsFactory({sync: true, ignore: 'pid'}),
destination: hookStream
});
const debugFileDestination = buildDestinationFile('debug', {path: './myLogs/debug.log'});
const warnFileDestination = buildDestinationFile('warn', {path: './myLogs/warn.log'});
const logger = buildLogger('debug', [
hookDestination,
buildDestinationStdout('debug'),
debugFileDestination,
warnFileDestination
]);
hookStream.on('data', (log) => {console.log(log)});
logger.debug('Test')
// logs to hookStream
// logs to STDOUT
// logs to file ./myLogs/debug.log
// does NOT log to file ./myLogs/warn.log
-Parsing LogOptions
If you wish to use LogOptions to get default log levels for your destinations use parseLogOptions:
+Parsing LogOptions
If you wish to use LogOptions to get default log levels for your destinations use parseLogOptions:
import {parseLogOptions, LogOptions} from '@foxxmd/logging';
const parsedOptions: LogOptions = parseLogOptions(myConfig);
Generated using TypeDoc
Creates a
+LogLevelStreamEntrystream that writes to a static file at or above the minimumlevel