Hex Logging Library

Hex Core logging library.

Installation

npm i @hex-insights/log
Copy

Overview

The main class in this module is the Logger type. A Logger has a formatter (Formatter) member that is used to format messages, an out (Writer) member to which the logger will write logs, and produces Entry objects that are formatted and written.

Logging can be done via either the top-level functions, the same methods defined on the Logger class, or those same methods defined on the Entry type. The top-level functions mirror those on the Logger type and refer to a global logger instance. The methods on the Entry type are similar to those defined on the Logger type, but lack certain customization that only applies to the logger (e.g. formatting and output destination).

Guide

Basic Logging

This module provides top-level logging functions for simple usage. The top-level functions work similarly to those in the built-in log module but with level distinctions. Here is a sample:

import * as Log from "@hex-insights/log";

Log.info("Log message");
Copy

The following logging functions are built-in (in increasing order) and each supports a format style as well:

• Log (generic)
• Debug
• Info
• Warn
• Error
• Fatal (unlike the Go version of this library, will not cause the program to exit)

Customization

Logger Customization

A specific logger or the global logger can be customized with the following modifier methods and functions:

• setOutput
• setLevel
• setFormatter
• setField
• setFields

Entry Customization

An individual log entry can be customized with the setField or setFields methods or a customized entry can be created by using the withField or withFields top-level functions/Logger methods, which create a new Entry object with the specified fields set.

Custom Log Levels

The underlying type of the Level enum type is number. The built-in levels are defined in order and separated by steps of 100. Custom log levels can be defined by casting an integer to a Level and adding a name for the level to this module. Level names should be short and in all caps.

For example:

const logLevelCustom = (Log.Level.Info + 1) as Log.Level

function customizeLogging() {
  Log.Level.addCustom(logLevelCustom, "CUSTOM");
}
Copy

Usage:

Log.log(logLevelCustom, "Custom message");
Copy

Examples

Global Configuration

These options will be set on all global logging usage and all loggers and entries derived from the global logger.

import * as Log from "@hex-insights/log";

function configureLogging() {
  // Write to an external logging server
  const networkWriter = {
    write(s: string) {
      fetch(process.env.LOGGING_SERVER_ADDR, {
        method: "POST",
        body: s,
      });
    }
  }
  
  // Write to standard console and network
  const writer = Log.MultiWriter(Log.ConsoleWriter, networkWriter);
  Log.setOutput(writer);
  
  // Use the JSON formatter
  Log.setFormatter(new Log.JSONFormatter());
  
  // Set some fields
  Log.setField("appName", "My Application");
}
Copy

Customized Logger

import * as Log from "@hex-insights/log";

function myFunc() {
  const logger = Log.copyLogger();
  logger.setField("fnName", "myFunc");
  
  logger.info("Starting");
  // do something
  logger.info("Done");
}
Copy

Customized Entry

import * as Log from "@hex-insights/log";

function myFunc() {
  Log.withField("fnName", "myFunc").Info("Starting processing...");
  // ...
  const entry = Log.newEntry();
  const someCondition = true;
  if (someCondition) {
    entry.setField("condition", "someCondition");
  }
  entry.info("Message");
}
Copy