tteok v1.0.2

Tteok

Tteok a traditional Korean rice cake, made from glutinous rice flour, often rolled into thin log shapes, notable for their uniformity.

Tteok is a configuration-less logger for NodeJS that takes a perscriptive approach to constructing log messages for microservices. The only supported configuration is logging JSON to STDOUT, and this library will not offer any alternatives.

npm install tteok --save

Features

• Uniform JSON logging to STD-OUT
• Default log enrichment on all log messages (process title, log level, ISO timestamp, calling code location)
• Simple API for adding additioning logging info (errors, strings, json ect)
• Automatic POSIX signal logging (with default enrichment)
• Automatic uncaughtException logging (with default enrichment)

Usage

const logger = require('tteok')

logger.info('simple message here')
logger.debug('debug message here', { data: 123 }, err)
logger.warn({ importantInfo: 'important', veryImportantNumber: 456 })
logger.error(new Error('something went very wrong'))
logger.panic('something catastrophic happened, logging then exiting')

Tteok creates uniform JSON log messages that are output via STD-OUT. In the microservices world, uniformity is a very powerful thing, and by using Tteok, you can be sure your logging strategy will be identical between services. In addition, Tteok automatically logs all incoming signals with a 'signal' property, as well as any uncaught exceptions.

logger.info('simple message here')

{
  process: 'my app',
  level: 'INFO',
  timestamp: '2016-11-23T09:36:26.960Z',
  at: 'app.js:14:14',
  message: 'simple message here'
}

logger.info({ importantInfo: 'important', veryImportantNumber: 456 })

{
  process: 'my app',
  level: 'INFO',
  timestamp: '2016-11-23T09:36:26.960Z',
  at: 'app.js:14:14',
  importantInfo: 'important',
  veryImportantNumber: 456
}

Default Enrichment

Each log is automatically enriched with a process name, a log level, an ISO Timestamp and the location of the calling code (filename:line:column), as well as the contents of the parameters you provide. All of the log methods use the ...rest parameter syntax so any number of inputs in any order are supported.

logger.warn()

{
  process: 'my app',
  level: 'WARN',
  timestamp: '2016-11-23T09:36:26.960Z',
  at: 'app.js:14:14'
}

Process

Log namespacing is achieved via setting the process title of your application, and that title is appended to all log messages. This is important for differentiating apps if logs are streamed into a shared index/location. More finegrained namespacing is not supported, and is potentially not advisable for single responsibility services.

process.title = 'process name here'
logger.warn()

{
  process: 'process name here',
  level: 'WARN',
  timestamp: '2016-11-23T09:36:26.960Z',
  at: 'app.js:14:14'
}

Log Levels

INFO, DEBUG, WARN and ERROR The 'level' property is just the function name transformed to uppercase. The 'panic' level also causes the process to exit with a non-zero exit status.

Timestamp

The 'timestamp' property is an ISO timestamp, and there is no option to reconfigure the output type of this timestamp. During logging, any other Date objects provided to the logger must be provided as the value of a json property; any standalone Date objects will be ignored to avoid confusion.

At (Calling code location)

The 'at' property gives a rough approximation of where the log method was called from. This is primarily useful for debugging purposes, any log analytics derived from this property can not be considered accurate due to the constant changing of filename/line locations during the average software lifecycle.

Enrichment

Objects

The most common usecase for Tteok logging is to provide some JSON into the log method so each of the individual elements are appended to the log message.

logger.warn({ method: 'GET', url: 'localhost/v1/customers', statusCode: 401 })

{
  process: 'my app',
  level: 'WARN',
  timestamp: '2016-11-23T09:36:26.960Z',
  at: 'app.js:14:14',
  method: 'GET', 
  url: 'localhost/v1/customers',
  statusCode: 401
}

Errors

Any error passed to the log method will have it's error message and the stack trace appended to the log message.

logger.error(new Error('something went really wrong'))

{
  process: 'my app',
  level: 'ERROR',
  timestamp: '2016-11-23T09:36:26.960Z',
  at: 'app.js:14:14',
  error: 'something went really wrong',
  stack: `Error: something went really wrong
    at Module.func myapp.js:93:18
    at AnotherModule.func module.js:3:81
    at etc etc etc`
}

Strings

Any provided strings are outputted to a 'message' or 'messages' property, depending on the number of strings provided.

logger.info('one string')

{
  process: 'my app',
  level: 'INFO',
  timestamp: '2016-11-23T09:36:26.960Z',
  at: 'app.js:14:14',
  message: 'one string'
}

logger.info('two strings', 'another string')

{
  process: 'my app',
  level: 'INFO',
  timestamp: '2016-11-23T09:36:26.960Z',
  at: 'app.js:14:14',
  messages: ['two strings', 'another string']
}

Arrays

Any arrays are just iterated over again and the elements individually evaluated as per the rules of the element type.

logger.info(['a string', new Error('an error')])

{
  process: 'my app',
  level: 'INFO',
  timestamp: '2016-11-23T09:36:26.960Z',
  at: 'app.js:14:14',
  message: 'a string',
  error: 'an error', 
  stack: `Error: an error
    at Module.func myapp.js:93:18
    at AnotherModule.func module.js:3:81
    at etc etc etc`
}

Functions

Any functions provided will have their respective names appended to the log message in the 'function' property.

logger.info(myModule.myFunc)

{
  process: 'my app',
  level: 'INFO',
  timestamp: '2016-11-23T09:36:26.960Z',
  at: 'app.js:14:14',
  function: 'myFunc'
}

undefined, null, Number, Date, NaN, Infinity

All of these properties are ignored if they are provided to the log function unless they are attached to a key as part of an object. Otherwise, they would only serve to confuse the logs.

logger.info(null, 123, undefined)

{
  process: 'my app',
  level: 'INFO',
  timestamp: '2016-11-23T09:36:26.960Z',
  at: 'app.js:14:14'
}

Signals

By default, Tteok will also log all incoming signals. You can still add custom handlers to these events. The 'at' property is ommitted for this case as it will display Tteok internals.

process.emit('SIGHUP')

{
  process: 'my app',
  level: 'INFO',
  timestamp: '2016-11-23T09:36:26.960Z',
  signal: 'SIGHUP'
}

Uncaught Exceptions

By default, Tteok will also log all uncaught exceptions. You can still add custom handlers to these events. The 'at' property is ommitted for this case as it will display Tteok internals.

process.emit('uncaughtException')

{
  process: 'my app',
  level: 'INFO',
  timestamp: '2016-11-23T09:36:26.960Z',
  error: 'an error', 
  stack: `Error: an error
    at Module.func myapp.js:93:18
    at AnotherModule.func module.js:3:81
    at etc etc etc`
}

Alternatives

This project is a very simple and very 'dumb' logging solution, prioritising simplicity and uniformity over customization or configuration. If this does not serve your requirements, check out some of the following projects below.

• winston More complete logging solution
• bunyan Very similar in design principle, but offers customization via serializers and streaming