โคNagging Penguin Matriarchs

    @uswitch/koa-signal

    1.7.0ย โ€ขย Publicย โ€ขย Published

    ๐Ÿšฆ Koa Signal

    A hackable & configurable console logger designed to integrate perfectly with @uswitch/koa libraries

    Overview | Usage | Api | Configuration | Contributors

    Contributors License type language test style

    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))

    N.B. See koa-core

    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' ] }
      }
    })

    N.B. See koa-core

    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!

    Keywords

    none

    Install

    npm i @uswitch/koa-signal

    DownloadsWeekly Downloads

    735

    Version

    1.7.0

    License

    MIT

    Unpacked Size

    53.3 kB

    Total Files

    34

    Last publish

    Collaborators

    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar