Overview

This package is a library inspired by Signale, to provide customisable and consistent logging for Node* services.

It tries to address the following;

• 🍽 Comletely Customisable - Control everything with a single JSON file
• 📏 Extensible - Add your own signals and components

This allows you to create consistent logs decoupled from the actual implementation of your code.

Usage

koa-signal was designed to work seamlessly with @uswitch/koa-access & @uswitch/koa-tracer. If you use either of these, you can just plug it in like so;

import Koa from 'koa'

import Signal from '@uswitch/koa-signal'
import access, { eventAccess } from '@uswitch/koa-access'
import tracer, { eventTrace, eventError } from '@uswitch/koa-tracer'

const app = new Koa()
const signal = Signal({ /* Config overrides */ })

app.use(tracer())
app.use(access())

app.on(eventAccess, signal.access)
app.on(eventTrace, ({ ctx,key,trace }) => signal.trace({ ...ctx, ...trace, scope: key }))
app.on(eventError, ({ ctx, error }) => signal.error(ctx, error.original))


app.listen(3000, () => signal.start(Listening on port 3000))

However, you can use it entirely independently of these two libraries as a log formatter. Creating an instance of koa-signal will provide you with a bunch of different logging functions, e.g.

import Signal from '@uswitch/koa-signal'
const signal = Signal({ /* config overrides */ })

signal.info('My really useful info message')

Production vs Development

koa-signal's formatting is useful for logging in Development to give a good understanding of what's happening in your application, however, in Production you probably want your output to be machine readable.

To change the formatting for Production, you can just provide a new config file, e.g.

import Signal from '@uswitch/koa-signal'
const signal = Signal({
  levels: {
    info: { format: [] },
    trace: { format: [] },
    warn: { format: [] },
    error: { format: [] },
    access: { format: [ 'json' ] }
  },
  components: {
    json: { properties: [ 'id', 'errors', 'errorsCount', 'traces' ] }
  }
})

In Production it's a common practice to save the logs to a file as well. koa-signal supports both console and file outputs which can be used independently or together e.g.

outputs

import Signal from '@uswitch/koa-signal'
const signal = Signal({
  levels: {
    info: { format: [] },
    trace: { format: [] },
    warn: { format: [] },
    error: { format: [] },
    access: { format: [ 'json' ] }
  },
  components: {
    json: { properties: [ 'id', 'errors', 'errorsCount', 'traces' ] }
  },
  outputs: [
    { type: 'console' },
    { type: 'file', file: './path/to/file.json' }
  ]
})

API

Each Signal function is defined with a format property (See configuration) which dictates how the log output is built. For example, let's take the trace function with the following output;

🤦 Doh!   [9ee...498] | +2546ms | |  +123ms | [SCOPE] >  First scoped traced message

The whole output is a LEVEL, but is made up of multiple COMPONENTS;

                                  TRACE LEVEL FUNCTION
╭──────────────────────────────────────────┴────────────────────────────────────────╮
🤦 Doh!   [9ee...498] | +2546ms | |  +123ms | [SCOPE] >  First scoped traced message
╰───┬───╯ ╰────┬────╯ ╰────┬────╯ ╰────┬────╯ ╰────┬────╯╰─────────────┬────────────╯
COMPONENT  COMPONENT   COMPONENT   COMPONENT   COMPONENT           COMPONENT

This is defined in config as the following;

{
  "levels": {
    "trace": {
      "badge": "🤦",
      "label": "Doh!",
      "format": [ "level", "id", "time-diff-init", "time-diff-scope", "scope", "message" ]
    }
  }
}

Where [ "level", ..., "message" ] is the list of Components being used. Components also have their own configuration defined separately.

API Functions

These functions are available by default and require the following properties when called.

| Function | API | |-----------|-------------------------------------------------------------------------------------------------| | success | ({ state: { id: STRING }, msg: STRING }) | | info | ({ state: { id: STRING }, msg: STRING }) | | warn | ({ state: { id: STRING }, msg: STRING }) | | access | ({ state: { id: STRING }, req: OBJECT, res: OBJECT }, extras: OBJECT) | | trace | ({ state: { id: STRING }, initDiff: INT, timeDiff: INT, scope: STRING, msg: STRING }) | | zipkin | ({ kind: CLIENT/SERVER, state: { parent: STRING, trace: STRING }, req: OBJECT, res: OBJECT }) | | error | ({ state: { id: STRING }, msg: STRING }, ERROR) | | start | ({ msg: SRTING }) | | end | ({ msg: STRING }) |

Configuration

You can see the default configuration of koa-signal here

Contributors

Thanks goes to these wonderful people (emoji key):

| Dom Charlesworth📖 💻 🤔 🔌 | David Annez💻 🤔 🔌 | | :---: | :---: |

This project follows the all-contributors specification. Contributions of any kind welcome!