thomsonreuters / cta-logger

cta-logger

Logger Modules for Compass Test Automation, One of Libraries in CTA-OSS Framework

General Overview

Overview

• The loggers, which are provided in this module, implementing winston.

• Multiple loggers are necessary and can instantiated with different configurations using winston.Container features.

• Each logger has two transports: Console and File:

  Console Transport Example:

  2017-09-09T13:10:25.904Z - debug - HOSTNAME - APP - AUTHOR - "Log file set to: C:\\Users\\Panit.Tuangsuwan\\AppData\\Local\\Temp\\cta-logger-silly"
  2017-09-09T13:10:25.905Z - error - HOSTNAME - APP - AUTHOR - "silly error message"
  2017-09-09T13:10:25.906Z - warn - HOSTNAME - APP - AUTHOR - "silly warn message"
  2017-09-09T13:10:25.907Z - info - HOSTNAME - APP - AUTHOR - "silly info message"
  2017-09-09T13:10:25.908Z - verbose - HOSTNAME - APP - AUTHOR - "silly verbose message"
  2017-09-09T13:10:25.909Z - debug - HOSTNAME - APP - AUTHOR - "silly debug message"
  2017-09-09T13:10:25.910Z - silly - HOSTNAME - APP - AUTHOR - "silly silly message"

  File Transport Example:

  {"timestamp":"2017-09-09T13:10:25.904Z", "level":"debug", "hostname":"HOSTNAME", "application":"APP", "author":"AUTHOR", "message":"Log file set to: C:\\Users\\Panit.Tuangsuwan\\AppData\\Local\\Temp\\cta-logger-silly"}
  {"timestamp":"2017-09-09T13:10:25.905Z", "level":"error", "hostname":"HOSTNAME", "application":"APP", "author":"AUTHOR", "message":"silly error message"}
  {"timestamp":"2017-09-09T13:10:25.906Z", "level":"warn", "hostname":"HOSTNAME", "application":"APP", "author":"AUTHOR", "message":"silly warn message"}
  {"timestamp":"2017-09-09T13:10:25.907Z", "level":"info", "hostname":"HOSTNAME", "application":"APP", "author":"AUTHOR", "message":"silly info message"}
  {"timestamp":"2017-09-09T13:10:25.908Z", "level":"verbose", "hostname":"HOSTNAME", "application":"APP", "author":"AUTHOR", "message":"silly verbose message"}
  {"timestamp":"2017-09-09T13:10:25.909Z", "level":"debug", "hostname":"HOSTNAME", "application":"APP", "author":"AUTHOR", "message":"silly debug message"}
  {"timestamp":"2017-09-09T13:10:25.910Z", "level":"silly", "hostname":"HOSTNAME", "application":"APP", "author":"AUTHOR", "message":"silly silly message"}

Guidelines

We aim to give you brief guidelines here.

1. Instantiation
2. Logger Configuration
3. Log Levels
4. Log Format
5. Author Name in Log Output
6. Application Name in Log Output

1. Instantiation

A logger can be instantiated in two different ways:

• Inside Brick
• Outside Brick (anywhere)

Inside Brick

Inside Brick, the logger is instantiated by Cement using the configuration entry and provided to the Brick via CementHelper. It's usually available in the Brick level as a dependency of cementHelper : cementHelper.dependencies.

'use strict';

const Brick = require('cta-brick');

class MyBrick extends Brick {
  constructor(cementHelper, config) {
    // By calling Brick constructor (super) and providing the config, the 'Brick-level' logger is instantiated.
    super(cementHelper, config);

    // At this point, the logger instance is avaliable and can be accessed.
    this.logger.info('Initializing a new instance of Brick with config: ', config);
    ...
  }
}

In the Brick, this.logger is a reference to cementHelper.dependencies.logger (see cta-brick).

Outside Brick (anywhere)

Outside Brick or anywhere, the logger can be instantiated with default or custom options.

default options

'use strict';

const Logger = require('cta-logger');

const logger = new Logger();

logger.info('Initialized a new instance of Logger with default config');

custom options

'use strict';

const Logger = require('cta-logger');

const logger = new Logger(null, {
  name: 'logger',
  properties: {
    filename: __dirname + '/default.log',
    level: 'silly',
  },
});

logger.info('Initialized a new instance of Logger with custom config');

back to top

2. Logger Configuration

Logger Configuration is provided when a logger is being instantiated.

const logger = new Logger(null, LoggerConfiguration);

Logger Configuration Structure

const LoggerConfiguration = {
  name: string,
  properties: {
    level: string,
    author: string,
    console: boolean,
    file: boolean,
    filename: string
  }
};

• name defines the name of logger
• properties defines how a logger is setup
  • level defines the log level to be used (see Log Levels)
  • author defines author name in log output
  • console defines whether a console transport log is enabled
  • file defines whether a console transport log is enabled
  • filename defines a full path of logs file to be used

back to top

3. Log Levels

We aim to support these log levels : [error, warn, info, verbose, debug, silly], ordered in priorty.

If the logger set its level as info, any message logging with levels: error, warn, info will be logged.

If the logger set its level as debug, any message logging with levels: error, warn, info, verbose, debug will be logged.

Level: info = [error, warn, info, verbose, debug, silly]

Level: debug = [error, warn, info, verbose, debug, silly]

back to top

4. Log Format

When it's logging, Log Level and a message are needed as log format. There are two log formats.

• logger.log(log_level, message) method

logger.log('info', 'message');
logger.log('debug', 'message');
logger.log('error', 'message');

• logger.loglevel(message) method

logger.info('message');
logger.debug('message');
logger.error('message');

Both logger.log('info', 'message') and logger.info('message') effect the same. Either is your preference.

back to top

5. Author Name in Log Output

The Logger has Author Name as a part of log output.

By default, the author of the log output is set to "UNKNOWN".

Author Name can be set by either parameter in instantiating or logger.author().

• parameter in instantiating

'use strict';

const Logger = require('cta-logger');

const logger = new Logger(null, {
    properties: {
        author: 'cta-agent',
    },
});

logger.info('info message');
// LOG OUTPUT: 2017-09-09T13:10:25.909Z - info - HOSTNAME - UNKNOWN - CTA-AGENT - "info message"

• logger.author('author_name')

'use strict';

const Logger = require('cta-logger');

const logger = new Logger();

const cta_agent = logger.author('cta-agent');
const cta_api = logger.author('cta-api');

cta_agent.info('info message');
cta_api.info('info message');
// LOG OUTPUT: 2017-09-09T13:10:25.910Z - info - HOSTNAME - UNKNOWN - CTA-AGENT - "info message"
// LOG OUTPUT: 2017-09-09T13:10:25.911Z - info - HOSTNAME - UNKNOWN - CTA-API - "info message"

back to top

6. Application Name in Log Output

The Logger has Application Name as a part of log output.

By default, the application of the log output is set to "UNKNOWN".

Application Name can be set by application configuration via cement dependency.

'use strict';

const Logger = require('cta-logger');

const logger = new Logger({
  cement: {
    configuration: {
      name: 'cta-oss',
    },
  },
}, null);

const cta_agent = logger.author('cta-agent');
const cta_api = logger.author('cta-api');

cta_agent.info('info message');
cta_api.info('info message');
// LOG OUTPUT: 2017-09-09T13:10:25.918Z - info - HOSTNAME - CTA-OSS - CTA-AGENT - "info message"
// LOG OUTPUT: 2017-09-09T13:10:25.919Z - info - HOSTNAME - CTA-OSS - CTA-API - "info message"

back to top

---

To Do

• decoupling cta-logger and winston