@grund/logging v0.0.85

@grund/logging

The package exposes the following things:

• LoggingService
  • The class that contains pretty much all logic. More about this further down.
• Logging
  • A singleton instance of the LoggingService.
• trace, debug, info, warn, error, fatal
  • All logging functions available in @grund/logging.
  • Originates from Logging.

LoggingService

This class contains pretty much all logic in the package. It has a few different purposes:

1. Store logging configuration - which controls some aspects of the logging actions.
2. Instantiate and store the logging functions
3. Expose some utility functions (e.g. identify and groupArguments)
4. Extend the EventService class in order to enable listener and hook functionality. This enables us to listen/hook into every logging function that is fired. Read more about this in the @grund/events documentation.

Logging functions

The logging function are listed above. All of them takes in an arbitrary number of arguments and prints them with the console.log function - prefixed with a uppercase title depending on what logging level (trace, debug, etc) is used.

All logging function also exposes a silent property. This is a function that acts the exact same way as the original function, but doesn't print anything. In other words it only fires the listeners and hooks.

Internally, all log functions are wrappers around the same functions. These wrapping functions only purpose is to create a data interface called LogOptions which is then passed to the internal functions and guides their behaviors. This interface might be good to know exists and it looks like:

interface LogOptions {
	level: LOG_LEVEL;
	isSilent: boolean;
}

Usage

import { debug, warn, error } from '@grund/logging';

debug('Hello'); // Prints "[DEBUG] Hello"
warn.silent('Foo'); // Prints nothing but fires the listeners.
error('Yolo'); // Prints "[ERROR] Yolo"

Events

As mentioned above, LoggingService implements the EventService. The event schema is the following:

namespace LoggingEventSchema {
	interface Listeners {
		log: (options: LogOptions, loggingArgs: LoggingArgs) => any;

		trace: (...args: LoggingArgs) => any;
		debug: (...args: LoggingArgs) => any;
		info: (...args: LoggingArgs) => any;
		warn: (...args: LoggingArgs) => any;
		error: (...args: LoggingArgs) => any;
		fatal: (...args: LoggingArgs) => any;

		identify: (...args: IdentifyArgs) => any;
	}

	interface Hooks {
		beforeLog: (options: LogOptions, args: LoggingArgs) => any;
		beforeIdentify: (...args: IdentifyArgs) => any;
	}
}

Worth noting is that the log listener is always fired before any of the specific log function listeners.

Usage

import { Logging } from '@grund/logging';

Logging.listeners.on('debug', () => {
	console.log('Debug fired');
});
Logging.listeners.on('log', (options, loggingArgs) => {
	console.log(`Log fired! Level: ${options.log}`);
});
Logging.hooks.on('beforeLog', (options, loggingArgs) => {
	console.log('Before log');
});

debug('Hello');

// First prints "Before log"
// Prints "Log fired! Level: debug"
// Prints "Debug fired"

Identification

In order to implement some sort of production logging or error tracking one needs to be able to identify what user is generating the logs. For this we have the identify function which is exposed by LoggingService (and, in turn, the Logging singleton). The function itself doesn't do much, but acts more as a relay and common interface to other solutions.

For instance, this is used beautifully in collaboration with the @grund/logging-sentry. This package listens to whenever you call identify and forwards it to the Sentry library. In this way you don't need to interact with the Sentry library by yourself. This functionality can of course be extended to any third party logging package.

Usage

import { Logging } from '@grund/logging';

Logging.listeners.on('identify', (userId) => console.log({ userId }));

Logging.identify(1); // Prints "{ userId: 1 }" through the listener

Configuration

The LoggingService contains a "global" property called config that determines some of the logging behavior. The current configurations are:

• Logging.config.print.isEnabled
  • Determines if the logs should be printed with console.log.
  • Defaults to IS_DEV.
• Logging.config.print.isGrouped
  • If true, the arguments are grouped by the types string, Error and plain object.
  • Used by other libraries (e.g. @grund/logging-sentry).
  • Defaults to false.
• Logging.errors.shouldObjectify
  • Used when grouping the arguments (by the function Logging.groupArguments)
  • If true and any error argument contains the function toObject, call it and use the return value instead of the error itself.
  • Defaults to true
• Logging.errors.shouldIncludeStack
  • Determines if to include the stacks when objectifying the errors.
  • Defaults to true

Usage

import { debug, Logging } from '@grund/logging';

Logging.config.print.isEnabled = false;

debug('Hello'); // Prints nothing