Skip to content

A powerful log system for node.js, with zero configuration

License

Notifications You must be signed in to change notification settings

cantonjs/pot-logger

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

73 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

pot-logger

Build Status CircleCI Dependencies License

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

screenshot

Table of Contents

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");

logger

createLogger with custom color

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

createLogger with custom color

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");

createLogger with custom appender

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:

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

License

MIT