pot-logger v0.6.0

pot-logger

A powerful log system for node.js, with zero configuration. Built on top of log4js

Table of Contents

• Table of Contents
• Features
• Getting Started
• Daemon
• Installation
• API
  • logger
  • createLogger(category[, appenderDescription])
  • hasLogger(category)
  • getLogger(category)
  • ensureLogger(category[, appenderDescription])
  • setConfig(keyOrConfig[, value])
  • flush([options])
  • overrideConsole([logger])
  • resetConsole()
  • overrideConsoleInRuntime(startRun[, logger])
• Creating Custom Logger
• Default Appenders
  • defaultDaemonAppender
  • defaultConsoleAppender
• Related Projects
• License

Features

• Easy to get started with zero configuration
• Log files with configurable log rolling based on file size or date
• Different log levels
• Different log categories
• Easy to create custom logger
• All log4js appenders are supported
• Replace native console (disabled by default)

Getting Started

logger

import logger from "pot-logger";
logger.info("pot-logger");

createLogger with custom color

import { createLogger } from "pot-logger";
const foodLogger = createLogger("food", "yellow");
foodLogger.info("虾饺");

All chalk.js colors are available. You can even use dot-notation to define colors. i.e. red.bold.

createLogger with custom appender

import { createLogger } from "pot-logger";
const appender = {
  type: "console",
  layout: { type: "pattern", pattern: "\n 🦄 %m 🦄 \n" }
};
const unicornLogger = createLogger("unicorn", appender);
unicornLogger.info("Agnes");

All log4js appenders are available.

Daemon

By default, logger messages will finaly output by calling console.log to terminal, but if daemon mode enabled, logger messages will write to *.log files.

By default, there are three logs files:

• out.log: Default log file. Only valid log level messages will write to this file.
• err.log: All ERROR or FATAL log level messages will write to this file.
• all.log: All log level messages will write to this file.

To enable daemon mode, call setConfig('daemon', true).

Installation

npm i pot-logger

API

logger

Default logger. A logger is a little bit like console, it has these methods:

• all (grey)
• trace (blue)
• debug (cyan)
• info (green) alias log
• warn (yellow)
• error (red)
• fatal (magenta)
• mark (grey)

Ways to import logger module

import { logger } from "pot-logger";
import logger from "pot-logger"; /* or */
var logger = require("pot-logger").logger; /* or */
var logger = require("pot-logger").default; /* or */

createLogger(category, appenderDescription)

Create a custom logger.

Arguments

1. category (String): Logger category.
2. appenderDescription (String|Object|Function): Please see creating-custom-logger for detail.

Returns

Returns a new logger.

Example

import { createLogger } from "pot-logger";
const logger = createLogger("test", ref => {
  return ref.daemon ? ref.defaultDaemonAppender : ref.defaultConsoleAppender;
});

hasLogger(category)

Returns a boolean indicating whether a logger with the specified category exists or not.

Arguments

1. category (String): Logger category.

Returns

Returns true or false.

getLogger(category)

Get logger by category. If not found, it would return the default logger.

Arguments

1. category (String): Logger category.

Returns

Returns a logger.

ensureLogger(category, appenderDescription)

Get logger by category. If not found, create one.

Arguments

1. category (String): Logger category.
2. appenderDescription (String|Object|Function): Please see creating-custom-logger for detail.

Returns

Returns a logger.

setConfig(keyOrConfig, value)

Alias: `setLoggers`

Initialize configure.

Arguments

1. keyOrConfig (String|Object): Config key or config k/v object.
2. value (Any): Only work if the first argument is a String.

Props

• enable (Boolean)
• daemon (Boolean)
• logLevel (String|Object)
• logsDir (String)
• overrideConsole (Boolean)

Props.enable

If enable is false, no log messages would show, and nothing would write to log files. Defaults to true.

Example

setConfig("enable", false);

Props.daemon

If daemon is true, loggers will use *.log files instead of console. Defaults to false.

Example

setConfig("daemon", true);

Props.logLevel

Defining custom log levels. You could set all categories by passing a level string. Or you could to set some individual categories by passing a key/value object. Defaults to "INFO".

Valid levels: ALL < TRACE < DEBUG < INFO < WARN < ERROR < FATAL < MARK < OFF.

Example

Apply to all categories:

setConfig("logLevel", "DEBUG");

Apply to individual category:

setConfig("logLevel", { myLogger: "DEBUG" });

Props.logDir

Defining log files dir. By default, log files will work only when daemon mode enabled. Defaults to ${cwd}/.logs/.

Example

setConfig("logsDir", "/my/logs/path/");

Props.overrideConsole

Override native console to logger. Defaults to false.

Example

setConfig("overrideConsole", true);

flush(options)

Flush log files.

Arguments

1. options (Object)

• removeDir (Boolean): Remove whole directory. Defaults to false
• logsDir (String): Customize logs directory. Defaults to config.logsDir
• mode (Number): File mode (permission and sticky bits) when renewing log file. Defaults to 0o666 (readable and writable)

Returns

Returns a promise.

overrideConsole(logger)

Override native console. Notice that console.log() will be equal with logger.info().

Arguments

1. logger (Object): Defining a logger to override console.

resetConsole()

Reset console to the native one. Only work after overrideConsole() run.

overrideConsoleInRuntime(startRun, logger)

Override native console in startRun function runtime.

Arguments

1. startRun (Function): Defining an async function to start to override native console. When this function ends, console will reset to the native one.
2. logger (Object): Defining a logger to override console.

Example

import { overrideConsoleInRuntime } from "pot-logger";

(async function() {
  console.log("native"); /* => native */

  await overrideConsoleInRuntime(async () => {
    console.log("not native"); /* => INFO not native */
  });

  console.log("native again"); /* => native again */
})();

Creating Custom Logger

You could create a custom logger by calling createLogger(category, appenderDescription) or ensureLogger(category, appenderDescription). The appenderDescription argument is the description of appender.

If appenderDescription is an \<Object>, these options are available:

• color (String) optional: The category text color. Support all chalk.js colors. Support dot notation (i.e. red.bold). Only work for non-daemon (terminal) mode.
• level (String) optional: Custom log level.
• maxLevel (String) optional: Custom max log level.
• file (Boolean) optional: Use new log file or not. If true, the log file name will be the category name. Defaults to false. Only work for daemon mode.
• maxLogSize (Integer) optional: The maximum size (in bytes) for the log file. If not specified, then no log rolling will happen. Only work for daemon mode.
• backups (Integer) optional: The number of old log files to keep during log rolling. Defaults to 5. Only work for daemon mode.
• compress (Boolean) optional - Compress the backup files during rolling (backup files will have .gz extension). Defaults to true. Only work for daemon mode.

Example

import { createLogger } from "pot-logger";
const logger = createLogger("test", {
  color: "yellow",
  file: true
});

If appenderDescription is a \<String>, it's short for { color: <string\> }.

If appenderDescription is a \<Function>, there's an argument object which includes:

• category (String)
• daemon (Boolean)
• defaultDaemonAppender (Object)
• defaultConsoleAppender (Object)

Example

import { createLogger } from "pot-logger";
const logger = createLogger("test", ref => {
  return ref.daemon ? ref.defaultDaemonAppender : ref.defaultConsoleAppender;
});

What't more, you could also pass log4js appender configure to appenderDescription.

Default Appenders

defaultDaemonAppender

{
  type: 'file',
  filename: defaultCategory,
  maxLogSize: 10485760, // 10MB
  backups: 5,
  compress: true,
}

defaultConsoleAppender

{
  type: 'console',
  layout: {
    type: 'pattern',
    pattern: '%[%p%] %m',
  },
}

Related Projects

• log4js-node
• chalk

License

MIT