@uswitch/koa-access

👌 Koa Access

A Koa middleware for creating consistent, per-request access logs for your requests.

Overview | Usage | Api | Contributors

Overview

This package is a Koa middleware inspired by Morgan, an access log middleware for Express.

It tries to address the following;

• 🖌 Custom formatting - Allow you to inject your own formatting
• 💰 Custom tokens - Allow you to add your own extra logging tokens
• 📓 JSON tokens - All of this is handled using JSON rather than strings

All of this allows you to create consistent access logs decoupled from the actual implementation of your code.

---

Usage

import Koa from 'koa'
import access from 'koa-access'

const app = new Koa()

app.use(access())           /* Default configuration */
app.use(access([ 'id' ]))   /* Add `id` from `ctx.state` to access log */

app.use(access(readContext)) /* Read extra poperties by calling `readContext` on `ctx` */

app.on('koa-access:access', Logger.log)

This package uses Event Emitters to decouple the handling of logging from the implementation of your code.

API

By default, the koa-access will bundle the following properties into an object and fire them on the the koa-access:access event.

{
  "res": {
    "responseTime": 23    // Response time in `ms`
    "length": 23232       // Content length of the response
    "status": 200         // Response status
    "statusBucket": "2XX" // Status as a bucket string
    "time": "2017-..."    // Timestamp of the response
  },
  "req": {
    "method": "GET"       // Method of request
    "path": "/foo/bar"    // Path being accessed
    "time": "2017-..."    // Timestamp of request start
    "host": "127.0.0.1"   // Host of the request
  }
}

The koa-access can be configured with extra parameters in one of two ways,

Array - access([ 'id', 'errors' ])

This will add the id and errors properties from the Koa ctx.state object onto the access log object.

Function - access((ctx) => ({ id: ctx.state.id, errors: ctx.state.errors }))

This will return an object by calling the function on Koa's ctx object, in this example, it'll just grab the id and errors properties from the state.

Events

Once a request access log has been built, the following event is fired with the access object

koa-access:access => (ctx, { req, res, ...extras })

The event can be imported from the koa-access module, as

import { eventAccess } from 'koa-access

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!