🐨

Take some logs and put 'em where we want 'em.

Koala is a small-but-opinonated logger for use in Wedgies apps. Koala was purpose built for two reasons:

1. standardize the logging interface and usage across Wedgies apps
2. format those logs according to specifc Wedgies needs.

Koala's features include:

• Multiple transports
  • Console and Logstash included
• Express middleware
  • Log requests in JSON
• Full test suite
  • 100% coverage

Installation

$ npm install @wedgies/koala

Usage

• Logging
  • Default config
  • Logstash config
  • Multi-transport config
  • Express middleware
  • Log levels
• Development
  • Continuous integration
  • Publishing to npm

Logging

Koala's api is simple yet powerful.

Default config

By default Koala uses the console transport. This makes it extremely easy to start using without having to deal with any configuration.

var koala = require('@wedgies/koala')

koala.log('Eucalyptus is yummy!')

In this example, 'Eucalyptus is yummy!' will be written to STDOUT.

Logstash config

Writing logs to a Logstash server is also easy with Koala.

var koala = require('@wedgies/koala').config({
  transport: ['logstash'],
  logstash: {
    host: 'koala.logs',
    port: 28777,
    constants: {
      tags: ['koala-app']
    }
  }
})

koala.log('Eucalyptus is yummy')

In this example, the logstash server will receive the followinng JSON object:

{
  "message": "Eucalyptus is yummy",
  "level": "info",
  "tags": ["koala-app"]
}

Multi-transport config

It's also possible to write logs to multiple transports at once.

var koala = require('@wedgies/koala').config({
  transport: ['console', 'logstash'],
  logstash: {
    host: 'koala.logs',
    port: 28777,
    constants: {
      tags: ['koala-app']
    }
  }
})

koala.log('Eucalyptus is yummy')

In this example, 'Eucalyptus is yummy!' will written to STDOUT and the logstash server will receive the followinng JSON object:

{
  "message": "Eucalyptus is yummy",
  "level": "info",
  "tags": ["koala-app"]
}

Express middleware

Koala includes an Express middleware logger. The middleware gathers information on each application request, bundles it up as JSON and ships it to the configured transports.

var express = require('express')
var koala = require('@wedgies/koala')

var app = express()

app.use(koala.middleware())

Now on each request, the following object will be logged:

{
  path: '/wendell',
  method: 'GET',
  statusCode: 200,
  responseTime: '0ms',
  remoteAddr: '1.1.1.1',
  userAgent: 'Chrome',
  referrer: 'dinos.com'
}

When Logstash is set as a transport, the log object will include the level field, as well as the configured constant fields.

Log levels

Koala currently includes conviences methods for two log levels, INFO and ERROR.

var koala = require('@wedgies/koala')

koala.info('Eucalyptus is yummy')
koala.error('Out of Eucalyptus! :(')

When using the console transport, these methods map to the corresponding console method. When using the Logstash transport, these methods set the "level" field to the corresponding value.

It is also possible to use custom levels:

var koala = require('@wedgies/koala')

koala.log('debug', 'Where is the Eucalyptus?')

When using the console transport, the level must be one of the console methods:

• log
• info
• warn
• error
• dir
• time
• timeEnd
• trace
• assert

The Express middleware automatically calculates the log level based on the status code of the response. For a status code under 300, the level will be 'INFO'. Between 300 and 400, the level will be 'WARN', and over 400 the level will be 'ERROR'.

Development

Koala is written using ES2015 syntax. The source is compiled to ES5 standards during testing and distribution. The npm package contains only the compiled source for easy integration into all apps.

When working on Koala, it is recommended to run the npm run watch script. This script will look for changes and automaticaly compile the source and run tests.

When submitting a PR please follow the existing code style and add or improve tests covering the new code.

Continuous integration

Koala uses CircleCI to automatically run the test suite on new commits and PRs. The build history can be viewed at: wediges/koala.

In the future it may be useful to leverage CircleCI to automatically build and publish npm versions.

Publishing to npm

To publish a new version of Koala to npm, simply run npm version [major|minor|patch|premajor|preminor|prepatch|prerelease]. This will kick off the following tasks:

• run npm test to verify everything is passing.
  • if any tests fail, the versioning/publishing will exit.
• update the package.json version field.
• create a git commit and tag with the new version.
• run npm run build to compile the source.
• push the version commit and tag to github
• publish the new version to npm