mag

My name is Eugeny and I want to introduce my logging module called mag (GitHub: mahnunchik/mag, License: MIT). There are lots of full-featured logging frameworks such as bunyan (GitHub: trentm/node-bunyan, License: MIT) node-bunyan (GitHub: flatiron/winston, License: MIT) or log4js (GitHub: nomiddlename/log4js-node, License: MIT). Why write another one? Personally, I subscribe to the twelve-factor app methodology and more specifically the part about logs. Another cool thing about mag is that it’s fully built on Streams3.

 

Installation

?
1
npm install mag

Twelve-factor app logging

  • Logs are the stream of time-ordered events.
  • App never concerns itself with routing or storage of its output stream.
  • App should not attempt to write to or manage logfiles.
  • App should write its event stream, unbuffered, to stdout.

Here’s how to use Mag

Step 1

When you start developing an application you do not want to spend time configuring the logger, you just want be building features. You can just require mag (one line more than console usage =) and use it:

?
1
2
3
4
var logger = require('mag')();
logger.info('my great application is running!');
// 01:27:36.427 <INFORMATIONAL> my great application is running!

You get a well formatted message with a timestamp. Done!

Step 2

When your application begins to grow and you want to visually separate messages from different parts of application, you can start using the namespaces feature of mag.

?
1
2
3
4
5
6
7
8
9
10
var mag = require('mag');
var logger = mag('my-app');
var libLogger = mag('my-lib');
logger.info('my great application is running');
libLogger.debug('my library is running too');
// 22:36:24.245 [my-app] <INFORMATIONAL> my great application is running
// 22:36:24.246 [my-lib] <DEBUG> my library is running too

Step 3

When your application is finally ready for production, it is time to think about the logging format. Should it be text line by line? Maybe JSON?. Should entire error stack be printed or only a few lines? At this time you can require mag-hub module and configure the message format once in your application:

?
1
2
3
4
5
6
7
8
9
10
11
12
13
14
var hub = require('mag-hub');
// Formatters
var info = require('mag-process-info');
var format = require('mag-format-message');
var colored = require('mag-colored-output');
var myCustomFormatter = require('./my-custom-formatter.js');
hub.pipe(info())
  .pipe(format())
  .pipe(myCustomFormatter())
  .pipe(colored())
  .pipe(process.stdout);

How it works

  1. mag requires mag-stream module as a output for its log objects
  2. mag-stream tries to require top level mag-hub module
  3. if it fails then mag-stream requires mag-fallback
  4. mag-fallback is the fallback formatter which is essentially the same as using a console with a timestamp.

Mag does not come bundled with any transports, even formatters are in separate modules. You could potentially make log management based on mag, but I recommend sticking with the twelve-factor app methodology again and keep it simple. Use a log collector from Splunk or Loggly to drain the syslog instead.