Generated using TypeDoc
Generated using TypeDoc
Generated using TypeDoc
Generated using TypeDoc
Generated using TypeDoc
Generated using TypeDoc
Generated using TypeDoc
Generated using TypeDoc
Generated using TypeDoc
Generated using TypeDoc
Generated using TypeDoc
A typed, opinionated, batteries-included, Pino-based logging solution for backend TS/JS projects.
+Features:
+npm install @foxxmd/logging
+
+import { loggerAppRolling, loggerApp } from "@foxxmd/logging";
const logger = loggerApp();
logger.info('Test');
/*
* Logs to -> console, colorized
* Logs to -> CWD/logs/app.log
*
* [2024-03-07 10:31:34.963 -0500] DEBUG: Test
* */
// or for rolling log files we need to scan logs dir before opening a file
// and need to await initial logger
const rollingLogger = await loggerAppRolling();
rollingLogger.info('Test');
/*
* Logs to -> console, colorized
* Logs to daily log file, max 10MB size -> CWD/logs/app.1.log
*
* [2024-03-07 10:31:34.963 -0500] DEBUG: Test
* */
+
+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 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.The App Loggers take an optional config object.
+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 to rotating files. If `false` no log files will be created.
* */
file?: LogLevel | false
/**
* The full 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
*
* @default 'CWD/logs/app.log
* */
filePath?: string | (() => string)
}
+
+Available LogLevel levels, from lowest to highest:
debugverboseloginfowarnerrorfatalsilentconst 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
});
+
+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
+
+Labels can also be added at "runtime" by passing an object with labels prop to the logger level function. These labels will be appended to any existing labels on the logger.
logger.debug({labels: ['MyLabel']}, 'My log message');
+
+Passing an object or array as the first argument to the logger will cause the object to be JSONified and pretty printed below the log message
+logger.debug({myProp: 'a string', nested: {anotherProps: ['val1', 'val2'], boolProp: true}}, 'Test');
/*
[2024-03-07 11:39:37.687 -0500] DEBUG: Test
myProp: "a string"
nested: {
"anotherProps": [
"val1",
"val2"
],
"boolProp": true
}
*/
+
+Passing an Error as the first argument will pretty print the error stack including any causes.
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.
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.
import {
buildLogger,
buildDestinationStream, // generic NodeJS.WriteableStream or SonicBoom DestinationStream
buildDestinationStdout, // stream to STDOUT
buildDestinationStderr, // stream to STDERR
buildDestinationFile, // write to static file
buildDestinationRollingFile // write to rolling
} from "@foxxmd/logging/factory";
+
+All buildDestination functions take args:
level (first arg) - minimum level to log atoptions (second arg) - an object extending pino-pretty optionsoptions inherits a default pino-pretty configuration that makes 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:
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
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
import {buildDestinationFile} from "@foxxmd/logging/factory";
const dest = buildDestinationFile('debug', {path: '/path/to/file.log'});
+
+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
+
+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
Optional levelOptional fileSpecify the minimum log level to output to rotating files. If false no log files will be created.
Optional consoleSpecify the minimum log level streamed to the console (or docker container)
+Generated using TypeDoc
Generated using TypeDoc
Generated using TypeDoc
Generated using TypeDoc
Generated using TypeDoc
Generated using TypeDoc
Generated using TypeDoc
Generated using TypeDoc
Generated using TypeDoc
Generated using TypeDoc
Generated using TypeDoc
Const Generated using TypeDoc
Const Generated using TypeDoc
Const Generated using TypeDoc
Const Generated using TypeDoc
Const Generated using TypeDoc
Const Generated using TypeDoc
Specify the minimum log level for all log outputs without their own level specified.
+- Preparing search index...
- The search index is not available
@foxxmd/logging DocsInterface LogOptions
    level?: "silent" | "fatal" | "error" | "warn" | "info" | "log" | "verbose" | "debug";
    file?: false | "silent" | "fatal" | "error" | "warn" | "info" | "log" | "verbose" | "debug";
    console?: "silent" | "fatal" | "error" | "warn" | "info" | "log" | "verbose" | "debug";
}
Index
Properties
Properties
OptionallevelSpecify the minimum log level for all log outputs without their own level specified.
Defaults to env
-LOG_LEVELorinfoif not specified.Default
Default
-OptionalfileSpecify the minimum log level to output to rotating files. If
-falseno log files will be created.OptionalconsoleSpecify the minimum log level streamed to the console (or docker container)
-Settings
Member Visibility
Theme
On This Page
Generated using TypeDoc