Skip to content

mfdlabs/node-logging

Repository files navigation

@mfdlabs/logging

Logger implementation that follows the MFDLABS LOGDEV Standards.

Example

TypeScript

// The logger can be imported like this:
import logger from "@mfdlabs/logging";
// Or this:
import { logger } from "@mfdlabs/logging";

// You can use the following member if you do not require another logger:
logger.singleton.log("Example message");
logger.singleton.log("Example message with formatting: %d", 123);

// If you require a custom name, or just a seperate logger:
const newLogger = new logger("custom-logger");

newLogger.log("Hello from custom logger!!!!");

Exports

The package exports the following:

/* An enum containing log levels that can be input into the logger class constructor or logger.logLevel method. */
enum LogLevel { /* ... */ };

/* The main implementation for the logger class. */
class logger { /* ... */ };

Constructor

You can either use logger.singleton or logger.noopSingleton to access the logger. If you require something different use the following constructor parameters:

Argument Name Argument Type Default Value Description
name string Required The name of this new logger. It cannot be the same as an already existing logger or it will throw.
logLevel LogLevel LogLevel.Info The log level for this new logger. It must be a string if you are not using the LogLevel enum and must be a valid member of that enum.
logToFileSystem boolean true Should the logger create log files? If this is true and EACCES or EPERM is emitted it is auto disabled. You an override the default log directory via DEFAULT_LOG_FILE_DIRECTORY.
logToConsole boolean true Should the logger log to the console? This will automatically be disabled if there is no TTY found. Advised to not be used if you are running as a daemon.
cutLogPrefix boolean true Should the logging prefix be cut? It is advised that this is used in production environments as it reduces the resources used by loggers.
logWithColor boolean true Should the ouput be colorful? It is advised that this is disabled in production as it creates larger strings in order to make them colorful.

Properties

The following properties are available for the logger class:

Property Name Property Type Has Setter? Is Static? Description
singleton logger No Yes A static instance of the logger, it is advised you use this over creating new loggers if you don't require logs to be seperated by category.
noopSingleton logger No Yes Essentially the same as logger.singleton except this will do nothing, i.e the logLevel is None, and it doesn't log the the console or log files.
name string Yes No The name of the logger, you can change this at runtime if you wish, but it must be a unique name.
logLevel LogLevel Yes No The level of the logger, you can change this at runtime but it must be a valid LogLevel enum.
logToFileSystem boolean Yes No Is this logger writing to log files? This can be changed at runtime and will setup log files when the value is set or will teardown it's current file stream if unset.
logToConsole boolean Yes No Is this logger writing to the console? This can be changed at runtime.
cutLogPrefix boolean Yes No Is the logger's prefix being cut? This can be changed at runtime and is advised for production environments as log prefixes can get lengthy.
logWithColor boolean Yes No Is the logger's console output colorful? This can be changed at runtime and is advised to be disabled in production environments as it extends the log string with invisible characters.
fileName string No No The name of the file that the file system logger is writing to. This is only set if logger.logToFileSystem is enabled and didn't fail to create the log file.
fullyQualifiedLogFileName string No No The fully qualified name of the file that the file system logger is writing to. Essentially the same as logger.fileName except this includes the full path.
globalPrefixEntries (() => string)[]? Yes Yes A list of getters that will be prepended before the log level in the logger message for all loggers.
customPrefixEntries (() => string)[]? Yes No A list of getters that will be prepended before the log level in the logger message for the specific logger.

Methods

The following methods are made available for you to use. All "log" methods use the same set of arguments, the first being the format string, or a method that returns a string and then the next being a vararray of "any". All of the log methods are also asynchronous and be called without blocking the main thread.

logger.{logMethod}(string|() => string, ...any[]);

Method Name Return Type Is Asynchronous? Is Static? Description
tryClearLocalLog void No Yes A static method that tries to clear out the log file directory and reset all registered loggers. This is not advised as there could potentially be a logger that is writing the the directory from a non-managed app and this doesn't filter those out (TBD FUTURE). There is an environment variable that controls whether or not this method actually clears the folder or not, and this method has an argument to override that environment variable.
tryClearAllLoggers void No Yes A static method that tries to remove all tracked loggers from the current environment. This needs to set a property on loggers that determines if they're disposed or not, please PPEC when this idea becomes true. Does not dispose of the singleton and noopSingleton loggers.
log void Yes No The log method invokes an asynchronous log with the log level of Info.
warning void Yes No The warning method invokes an asynchronous log with the log level of Warning.
trace void Yes No The trace method invokes an asynchronous log with the log level of Trace.
debug void Yes No The debug method invokes an asynchronous log with the log level of Debug.
information void Yes No The information method invokes an asynchronous log with the log level of Info.
error void Yes No The error method invokes an asynchronous log with the log level of Error.

Environment variables

This logging utility utilizes @mfdlabs/environment to setup it's default singleton logger. The following environment variables are available to you to modify the default behavior:

Environment Variable Name Environment Variable Type Default Value Description
PERSIST_LOCAL_LOGS boolean false If you set this environment variable, the logger will persist it's log files even if a clearance is requested. This can be overridden in the logger.clearLocalLog method with the 'override' parameter.
DEFAULT_LOGGER_CUT_PREFIX boolean true If true, then the logger will cut the prefix of the log message in order to read the log message more easily. This is advised to always be set in production if you use the singleton logger.
DEFAULT_LOGGER_NAME string "singleton-logger" The default name of the singleton logger. When changing this you need to make sure it is a valid name or the getter for logger.singleton and logger.noopSingleton will throw!
DEFAULT_LOGGER_LOG_TO_FILE_SYSTEM boolean true If true, the singleton logger will log to the file system by default.
DEFAULT_LOGGER_LOG_TO_CONSOLE boolean true If true, the singleton logger will log to the console by default.
DEFAULT_LOG_LEVEL LogLevel Info The default log level for the singleton logger. This is advised to be set to something low in production environments.
DEFAULT_LOG_FILE_DIRECTORY string null The default log file directory, if this is unset it will place all log files in inside a folder called "logs" on your project root, or if you installed it globally it will write to a folder called "logs" in your global npm folder.