@x/log v0.7.14

@x/log

Simple, fast, object based logging for the @x platform.

Installation

yarn add @x/log

Usage

import logger from '@x/log'

const log = logger()
log.error(new Error('An error occurred'))

This creates a logger object that will use the default console log writer and only log entries with a level of info or higher.

Log Functions

The created object exposes a function for each log level:

Each of these functions accepts a variable number of parameters that will be merged in to the final log entry. A level property will also be set based on the function called. String arguments will be assigned to the message property.

Additionally, the following utility functions are exposed:

log(...args)

Log a new entry using the provided arguments without a level property.

child(scope)

Create a child logger that will merge the provided object into each log entry.

Options

The following options can be passed to the logger constructor:

Static Module Properties

For convenience, the top level module exposes the following additional properties:

Built In Writers

The following writers are available on the writers static property:

console

The console writer will attempt to make use of native console logging features such as colorization and accepts the following options:

file

The file writer simply outputs log entries to a specified file, one per line. It accepts the following options:

Implementing Custom Writers

A writer implementation that can be passed to the writers collection should be a constructor function that is passed the global options object and returns the actual writer function that is passed each log entry.

A typical implementation would look something like:

const httpLogWriter = userOptions => globalOptions => {
  // providing userOptions introduces a new top level constructor - this is optional but used here to configure the URL
  // the entry has already been passed through relevant serializers, there is no need to deal with error objects
  return entry => fetch(userOptions.url, { method: 'POST', body: JSON.stringify(entry) })
}

This would be consumed like follows:

const log = logger({
  writers: [httpLogWriter({ url: 'https://some.logging.domain/my/logging/endpoint' })]
})

License

The MIT License (MIT)

Copyright © 2022 Dale Anderson

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.