Introduction

This logging helpers make it easy to implement the logging required when developing concert software.
The main features are express middleware which generates transactionID, and customized(our flavor) winston transports, and alias functions to use it.

please use exact fixed version before we release v1.0 to prevent unwanted upgrade by npm up command

How to Use (Basic)

installation

# prerequisites
npm install config-extra --save
npm install winston --save
  
# install rocon_logging_tools
npm install rocon-logging-tools --save

Prepare to use

Configuration

Your configuration file should have following fields

# CWD/default.yaml
log:
  file_level: info
  file_options: {} # see options in https://github.com/winstonjs/winston-daily-rotate-file#options
  file_path: ./log

Import into your project

// setting up config-extra may needs
// see www.npmjs.com/package/config-extra
const config = require('config-extra');
const winston = require('winston');
  
const rocon_logging_tools = require('rocon_logging_tools')(winston, config);

functions for logging

Functions for logging

log(level:string, message: string, ?extra: object)
alias(message: string, ?extra: object)
?extra means it's optional field

quick example

const l = rocon_logging_tools.logger;
  
// You can use log() function for 
l.log('debug', 'debug logging message');
  
// If you want, put extra JSON data as third parameter
l.log('error', 'error logging message', {foo: 'bar'});
  
// You can also use alias functions
l.error('failed something', {details: 'i do not know why'});
l.warning('it is a warning message');
  
// In more shorter form
l.w('warning message', {foo: 'bar'});
l.i('informational message');

Log Levels

we are using syslog severity levels
see : RFC 5424

• debug - for debug
  • alias: d()
• info - informational
  • alias: i()
• notice - notification
  • alias: n()
• warning - warning
  • alias: w()
• error - error
  • alias: e()
• crit - critical
  • alias: c()
• alert - alert
  • alias: a()
• emerg - emergency
  • alias: em()

Log File Sample

{"level":"info","message":"debug test","timestamp":"2018-02-27T00:52:56.128Z"}
{"foo":"bar","level":"warning","message":"debug test","timestamp":"2018-02-27T00:52:56.126Z"}

express middleware

Warning: Test was poorly done.

1. parse txid from req header and req.rocon (if not exist, generate)
2. put txid to res header and res.rocon (if not exist, generate)

const app = require('express');
app.use(rocon_logging_tools.express.gtxid);
app.use(rocon_logging_tools.express.customTxid('mytxid'));

gtxid will saved on req.rocon.gtxid and http header named X-ROCON-gtxid
ltxid will saved on req.rocon.gtxid and http header named X-ROCON-ltxid
blabla will saved on req.rocon.gtxid and http header named X-ROCON-blabla

Utilities

objectId()

create objectId like a MongoDB's

let id = rocon_logging_tools.helper.objectId();

For Advanced User

using options to override configurations

When initialize rocon_logging_tools, there is optional 3rd field

const rocon_logging_tools = require('rocon_logging_tools')(winston, config, options);

options contains following field

• consoleLevel - overwrite logging.console_level, default is 'debug'
• fileLevel - overwrite logging.file_level, default is 'info'
• filePath - overwrite logging.file_path, there is no default, Program will crash
• transports - overwrite winston transports

Guide For Contributors

How to build

npm run build