denoland-deno/log/README.md

Log

Usage

import * as log from "https://deno.land/x/std/log/mod.ts";

// simple default logger, you can customize it
// by overriding logger and handler named "default"
log.debug("Hello world");
log.info("Hello world");
log.warning("Hello world");
log.error("Hello world");
log.critical("500 Internal server error");

// custom configuration
await log.setup({
  handlers: {
    console: new log.handlers.ConsoleHandler("DEBUG"),

    file: new log.handlers.FileHandler("WARNING", {
      filename: "./log.txt",
      // you can change format of output message
      formatter: "{levelName} {msg}"
    })
  },

  loggers: {
    // configure default logger available via short-hand methods above
    default: {
      level: "DEBUG",
      handlers: ["console", "file"]
    },

    tasks: {
      level: "ERROR",
      handlers: ["console"]
    }
  }
});

let logger;

// get default logger
logger = log.getLogger();
logger.debug("fizz"); // logs to `console`, because `file` handler requires "WARNING" level
logger.warning("buzz"); // logs to both `console` and `file` handlers

// get custom logger
logger = log.getLogger("tasks");
logger.debug("fizz"); // won't get output becase this logger has "ERROR" level
logger.error("buzz"); // log to `console`

// if you try to use a logger that hasn't been configured
// you're good to go, it gets created automatically with level set to 0
// so no message is logged
unknownLogger = log.getLogger("mystery");
unknownLogger.info("foobar"); // no-op

Advanced usage

Loggers

Loggers are objects that you interact with. When you use logger method it constructs a LogRecord and passes it down to its handlers for output. To create custom loggers speficify them in loggers when calling log.setup.

LogRecord

LogRecord is an object that encapsulates provided message and arguments as well some meta data that can be later used when formatting a message.

interface LogRecord {
  msg: string;
  args: any[];
  datetime: Date;
  level: number;
  levelName: string;
}

Handlers

Handlers are responsible for actual output of log messages. When handler is called by logger it firstly checks that LogRecord's level is not lower than level of the handler. If level check passes, handlers formats log record into string and outputs it to target.

log module comes with two built-in handlers:

• ConsoleHandler - (default)
• FileHandler

Custom message format

If you want to override default format of message you can define formatter option for handler. It can be either simple string-based format that uses LogRecord fields or more complicated function-based one that takes LogRecord as argument and outputs string.

Eg.

await log.setup({
  handlers: {
    stringFmt: new log.handlers.ConsoleHandler("DEBUG", {
      formatter: "[{levelName}] {msg}"
    }),

    functionFmt: new log.handlers.ConsoleHandler("DEBUG", {
      formatter: logRecord => {
        let msg = `{logRecord.level} {logRecord.msg}`;

        logRecord.args.forEach((arg, index) => {
          msg += `, arg{index}: {arg}`;
        });

        return msg;
      }
    }),
  },

  loggers: {
     default: {
         level: "DEBUG",
         handlers: ["stringFmt", "functionFmt"],
     },
  }
})

// calling
log.debug("Hello, world!", 1, "two", [3, 4, 5]);
// results in:
[DEBUG] Hello, world! // output from "stringFmt" handler
10 Hello, world!, arg0: 1, arg1: two, arg3: [3, 4, 5] // output from "functionFmt" formatter

Custom handlers

Custom handlers can be implemented by subclassing BaseHandler or WriterHandler.

BaseHandler is bare-bones handler that has no output logic at all,

WriterHandler is an abstract class that supports any target with Writer interface.

During setup async hooks setup and destroy are called, you can use them to open and close file/HTTP connection or any other action you might need.

For examples check source code of FileHandler and TestHandler.