@goodware/log
Advanced tools
Batteries-included Winston3-based loggger with console, file, and AWS CloudWatch Logs transports
npm i --save @goodware/log
The following transports can be utilized. They are all optional.
The ability to add additional transports
The Loggers class is a container that manages logger instances that have unique category names. Each logger has its own settings, such as logging levels and transports.
Any number of Loggers instances can exist at any given time. This is useful if, say, independent libraries use this package with different logging levels and other settings. The only caveat is Winston's design flaw that prevents assigning different colors to the same level.
Log messages via the log(), default(), and methods that are named after logging levels (aka <level>()), such as info(). The list of available logging levels and the console color for each level can be provided via options.
Log entries are created via four optional components: 'tags', 'message', 'context', and 'category.' This information can be passed as traditional ordered parameters or by passing a single object (for named parameters). tags() and context() merge two objects into a single object. When named parameters are used, extra provided properties are logged as part of the message; for example, the following object can be logged: { tags: 'disk', message: 'A message', error: new Error('An error') }.
Winston's splat formatter is not enabled. However, any type of data can be logged, such as strings, objects, arrays, and Errors (including their stack traces and related errors).
The concept of tags was borrowed from the @hapi project. Tags are a superset of logging levels. Log entries have only one level; however, tags are logged as an array in order to facilitate searches. For example, when the tags are (info, web) the log entry is logged at the 'info' level. When tags contain multiple level names, predecence rules apply (see logLevel below; otherwise, the tag in the smallest array index wins.
<level>() (e.g. info()), optionally accept an array of tags as the first parameter. log()'s tag parameter can be a string, array, or an object whose properties are tag names and their values are evaluated for truthiness that indicates whether the tag is enabled. When named parameters are used, the 'tags' argument can be an object, array, or string.
The values for 'message' and 'context' can have any type. Error objects are treated specially: their stacks and dependency graphs are also logged. In most cases, 'message' is a string that is used as the log entry's message and 'context' is an object that appears in the log entry's 'data' property.
log() and <level>() optionally accept an Error object as the first parameter, followed by message, context, and category.
When an Error instance is provided to log() and <level>(), 'error' is automatically added to the tags; however, 'level' for <level>() methods takes precdence. For example, info(new Error('An error')) is logged at the info level.
The logger() and child() methods create Logger objects that track the following: tags, context, and category. The Loggers and Logger classes have identical public interfaces but Logger is not meant to be instantiated.
Loggers are flushed via the asynchronous flush() and stop() methods. Because of Winston's limitations, only CloudWatch Logs transports can be flushed without stopping them. stop() is a heavyweight operation that can be reversed via the asynchronous start() method.
Neither Loggers nor Logger objects are Winston loggers and are therefore lightweight. Use winstonLogger() to retrieve a Winston logger for unusual use cases that require the Winston logger API.
Loggers and Logger instances have the methods loggers(), logger(), child(), parent(), winstonLogger(), isLevelEnabled() (aka levelEnabled), log(), and default().
Methods such as log() and info() that log messages accept four optional parameters: tags, message, context, and category. They are described below.
Logger instances (aka child loggers) have read/write properties: tags, context, and category.
child() and isLevelEnabled() optionally accept a single object with the following optional properties: tags, context, and category.
While a Loggers instance is active, uncaught exceptions and unhandled Promise rejections are logged using the category @log/unhandled. The process is not terminated after logging uncaught exceptions.
When a log entry's level is one of the values specified in the 'logStackLevels' options setting, the 'stack' meta key is set to the sjtack trace of the caller. This behavior is manually enabled and disabled via the 'logStack' meta tag.
An object provided to Loggers' constructor. Options are described by optionsObject.
A logger sends log entries to transports. Two classes, Loggers and Logger, implement the logger interface that includes:
The name of a logger. The default category is specified via the 'defaultCategory' options setting and defaults to 'general.' Transport filtering (based on tags) is specified on a per-category basis.
An object that is sent to a transport. A log entry consists of meta and data.
The top-level keys of a log entry. Meta keys contain scalar values except for tags and logTransports which are arrays. Meta keys are: timestamp, ms (elpased time between log entries), level, message, tags, category, logGroupId, logDepth, hostId, stage, version, service, stack, and logTransports. Certain properties in 'both' can be copied to meta keys, optionally renaming them, via the 'metaKeys' options setting.
The keys remaining in 'both' after meta keys are removed (see 'both' below)
Levels are associated with natural numbers. Per Winston's convention, a lower value indicates greater severity. Therefore, 0 means "most severe."
Levels and their colors can be specified via the second argument provided to the constructor using the same object that is provided when creating a Winston logger.
By default, Loggers uses Winston's default levels (aka npm log levels with the addition of two levels:
A custom set of levels can be provided to the Loggers class's constructor; however, the Loggers class assumes there is an 'error' level and the options model (via the defaults) assumes the following levels exist: error, warn, debug.
When a level is not found in the provided tags, the default level, 'debug', is assumed. The default level is specified via the 'defaultLevel' options setting.
Methods that are named after logging levels, such as error(). log(tags, message, context, category) is an alternative to the level methods. Level methods accept variant parameters. If the first parameter to a level method is an array, the parameter list is (tags, message, context, category). Otherwise, it's (message, context, category).
A log entry is sent to a transport only when its severity level is equal to or greater than the transport's level.
Tags are logged as an array of strings. Tags are specified via a single string, an array of strings, or an object in which each key value is evaluated for truthiness. Tags are combined via the static method tags(a, b) where b's tags override a's tags.
Tags are a superset of levels. A log entry's level is, by default, set to the tag with the highest severity. Level methods override this behavior such that the level associated with the method is chosen. The level can be specified via the logLevel meta tag. The level can also be modified via tag configuration.
Some tags alter logging behavior. A tag's value (tags can be specified as an object) enables and disables the feature, based on their truthiness. Meta tags are not logged. Meta tag names start with 'log' and 'noLog.' Meta tags tags that start with noLog negate their corresponding meta tags. For example, {logStack: true} is identical to 'logStack'. {logStack: false} is identical to 'noLogStack.' Meta tag names are:
Use the meta tag's value as a log entry's logging level
Whether to add the current stack to meta. When true, populates the 'stack' meta key. This is the default behavior when the log entry's level is 'error.'
Tags can be used for additional filtering on a per-transport basis. Tags that are named after severity levels do not participate in tag filtering. All tags are enabled by default. When a log entry's level is 'warn' or 'error', tags are enabled. This behavior can be overidden by the 'allowLevel' setting. Tags are enabled and disabled on a per-category basis. The 'default' category specifies the default behavior for unlisted categories.
The following example enables the tag 'sql' for only two categories: one and two. Category 'one' changes the level to 'more' and sends log entries only to the file and console transports. Category 'two' sends log entries to all transports.
categories: {
default: {
tags: {
sql: 'off', // Disable for all transports for all categories. Log entries with warn and error levels are logged.
},
},
one: {
tags: {
sql: {
// Fine-tune filtering for category 'one.' All of these keys are optional.
allowLevel: 'off', // Enable tag filtering for all log entries regardless of their levels. 'off' is needed
// because the default is 'warn' which causes all log entries with warn and error levels to be logged.
level: 'more', // Set the log entry's level to 'more'
// Log entries are sent to all transports by default (console, file, errorFile, cloudWatch). Each transport
// can be overridden:
file: 'verbose', // Send a log entry with the 'sql' tag to the file transport if the log entry's severity
// level is equal to or greater than 'verbose'
console: 'on', // Send a log entry with the 'sql' tag to the console transport
other: 'off', // Do not send a log entry with the 'sql' tag to CloudWatch
},
},
},
two: {
tags: {
sql: 'on', // Send all log entries with the 'sql' tag to all transports for category two
},
},
}
Uniquely identifies the system that is running node
Identifies the environment in which node is running, such as 'dev' or 'prod'
An optional string, array, or object to log with message. Two 'context' objects are combined via the static method context(a, b) in which b's keys override a's keys if they overlap.
A scalar, array, or object to log. If an object is provided, its 'message' property is moved to meta and other properties can be copied to meta. The list of keys to copy to meta is altered via the 'metaKeys' options setting. Properties are copied to meta if their values are scalar and their names are specified in metaKeys.
message and 'context' are shallow copied and combined into a new object called 'both.' If message's keys overlap with those in 'context,' 'context' is logged separately; both log entries will have the same logGroupId meta value.
If both.error is truthy and both.message is falsey, both.message is set to both.error.asString().
Error objects that are discovered in the top-level keys of both are logged separately, in a parent-child fashion, and recursively. This allows the stack trace and other details of every Error in a chain to be logged using applicable redaction rules. Each log entry contains the same logGroupId meta value. The data properties of parent entries contain the result of converting Error strings. For example, if both.error is an Error object, data.error will contain the Error object converted to a string. This process is performed recursively. Circular references are handled gracefully. The logDepth meta key contains a number, starting from 0, that indicates the recursion depth from both. The maximum recursion depth is specified via the 'maxErrorDepth' options setting. The maximum number of errors to log is specified via the 'maxErrors' options setting.
The following example produces three three log entries. error3 will be logged first, followed by error2, followed by error1. error1's corresponding log entry contains a data.cause key with a string value of 'Error: error2.'
const error = new Error('error1');
const error2 = new Error('error2');
const error3 = new Error('error3');
error1.cause = error2;
error2.error = error3;
logger.log('error', error);
A transport sends log entries to one of the following destinations:
file
Writes log entries with level equal to or higher than a specified level (defaults to 'info') to a file named category-timestamp.log.
errorFile
Writes log entries with level equal to or higher than a specified level (defaults to 'error') to a file named category-error-timestamp.log. Log entries are also sent to the file transport.
cloudWatch
Sends log entries to CloudWatch AWS service
console
Writes log entries to the process's STDOUT filehandle
Use the 'categories' options setting to configure transports. It is not necessary to specify every category that is actually used. The 'default' category specifies the base configuration for all categories. For example:
categories: {
default: { console: 'on', cloudWatch: 'info',
file: 'default' },
api: { console: 'off' },
}
Level filtering for each transport is configured via a level name, 'default,' 'on,' or 'off.' 'off' is the default. Each transport type treats 'on' slightly differently:
The behavior of console transports is altered via the 'console' options setting.
When 'colors' is true, log entries sent to the console are colorized. To override the provided value, set the
CONSOLE_COLORS
environment variable such that blank, 0, and 'false' are false and all other values are true.
When 'data' is true, the maximum amount of information is sent to the console, including meta, data, embedded errors, overridden 'context' properties objects, and stack traces. When it is false, a subset of meta keys are sent to the console with a log entry's message. To override the value for 'data', set the
CONSOLE_DATA
environment variable such that blank, 0, and 'false' are false and all other values are true.
Inside the categories: property, the console propery can contain a string or an object containing the data and colors keys that override the 'console' options settings.
Log entries are written to files as JSON strings to a directory specified via the 'file' options setting. If no directory in the provided array does not exist and can be created, the file-related transports are disabled. File names contain the category and the date and hour of the local time when this object was instantiated. Category names may contain operating-system directory separators and must conform to the filesystem rules of the operating system. For error log files, '-error' is appended to the category. Files have the extension .log. An example file name is: general-error-2020-07-18-18.log. Files are rotated and zipped on an hourly basis. The maximum number of archived log files defaults to 14 days and can be specified via the 'file' options setting.
CloudWatch transports are configured with a log group name and an optional AWS region. Log entries are sent to CloudWatch as JSON strings. One Loggers instance uses the same stream name for all cloudWatch transports. The log group, on the other hand, can be specified on a per-category basis. The log stream name contains the date and time (including the millisecond) when Loggers was instantiated followed by the host id. Any errors that occur while sending log entries to CloudWatch are written to the console and to files named cloudwatch-error*.log if a file directory is specified.
If an AWS region is not specified, the environment variables are used in the following order:
Utility functions are provided for logging begin and end messages for common operations (database, http, etc.). Begin log entries are tagged with 'begin.' End log entries are tagged with 'end.' The operationId property is added to both log entries with the same uuid generated for the operation. If an exception is thrown, an error is logged. These functions are implemented as static methods.
The following classes are available:
The following example sets result to 'Some data.'
TaskLogger = require('@goodware/log/TaskLogger');
Loggers = require('@goodware/log');
const logger = new Loggers({ defaultLevel: 'info' });
let result;
TaskLogger.execute(logger, async () => 'Some data', 'Doing it').then((value) => {
result = value;
});
First, push to git.
npm run prepubnpm run pub2FAQs
Batteries-included Winston3-based loggger with console, file, and AWS CloudWatch Logs transports
The npm package @goodware/log receives a total of 143 weekly downloads. As such, @goodware/log popularity was classified as not popular.
We found that @goodware/log demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.
Security News
The Ultralytics' PyPI Package was compromised four times in one weekend through GitHub Actions cache poisoning and failure to rotate previously compromised API tokens.