Updates for Winston 3.0

README.md

@@ -1,18 +1,25 @@
-# winston-loggly
+# winston-loggly-bulk
 
 A [Loggly][0] transport for [winston][1].
 
+[![Version npm](https://img.shields.io/npm/v/winston-loggly-bulk.svg?style=flat-square)](https://www.npmjs.com/package/winston-loggly-bulk)[![npm Downloads](https://img.shields.io/npm/dm/winston-loggly-bulk.svg?style=flat-square)](https://www.npmjs.com/package/winston-loggly-bulk)
+
+[![NPM](https://nodei.co/npm/winston-loggly-bulk.png?downloads=true&downloadRank=true)](https://nodei.co/npm/winston-loggly-bulk/)
+
+A client implementation for Loggly in node.js. Check out Loggly's [Node logging documentation](https://www.loggly.com/docs/nodejs-logs/) for more.
+
+
 ## Usage
 ``` js
   var winston = require('winston');
 
   //
-  // Requiring `winston-loggly` will expose
+  // Requiring `winston-loggly-bulk` will expose
   // `winston.transports.Loggly`
   //
-  require('winston-loggly');
+  var {Loggly} = require('winston-loggly-bulk');
 
-  winston.add(winston.transports.Loggly, options);
+  winston.add(new Loggly({options}));
 ```
 
 The Loggly transport is based on [Nodejitsu's][2] [node-loggly][3] implementation of the [Loggly][0] API. If you haven't heard of Loggly before, you should probably read their [value proposition][4]. The Loggly transport takes the following options. Either 'inputToken' or 'inputName' is required:
@@ -26,10 +33,58 @@ The Loggly transport is based on [Nodejitsu's][2] [node-loggly][3] implementatio
 * __tags:__ An array of tags to send to loggly.
 * __isBulk:__ If true, sends messages using bulk url
 * __stripColors:__ Strip color codes from the logs before sending
-
+* __bufferOptions:__ Buffer options has two configurations.
+  - __size:__ Number of logs to be buffered.
+  - __retriesInMilliSeconds:__ Time in milliseconds to retry sending buffered logs. 
+* __timestamp:__ If false, library will not include timestamp in log events. 
+  - __Note:__ Library includes timestamp by default when we do not set timestamp option.
 
 *Metadata:* Logged in suggested [Loggly format][5]
 
+## Sample Working Code Snippet
+
+``` js
+var winston  = require('winston');
+var {Loggly} = require('winston-loggly-bulk');
+
+winston.add(new Loggly({
+    token: "TOKEN",
+    subdomain: "SUBDOMAIN",
+    tags: ["Winston-NodeJS"],
+    json: true
+}));
+
+winston.log('info', "Hello World from Node.js!");
+```
+
+## Buffer Support
+
+This library has buffer support during temporary network outage. User can configure size of buffer (no. of logs to be stored during network outage).
+
+Add these below configuration in code snippet to override the default values of buffer option  __size__ and __retriesInMilliSeconds__.
+``` js
+bufferOptions: {
+    size: 1000,
+    retriesInMilliSeconds: 60 * 1000
+}  
+```
+* __Note:__ The default value of buffer size and retries in milliseconds are 500 and 30000 (30 seconds) respectively.
+
+## Flush logs and exit
+
+Our library uses ajax requests to send logs to Loggly, and as ajax requests take time to complete, logs can be lost when process.exit() is called because it forces an immediate exit. To exit gracefully and ensure that the last logs get to Loggly, we created a function called flushLogsAndExit(). It waits for 10 seconds and then calls process.exit() itself. This allows enough time for the logs to be sent to Loggly.
+
+Here is an example of how to use the method:
+
+``` js
+var winston = require('winston');
+var {flushLogsAndExit} = require('winston-loggly-bulk');
+
+winston.log("info", "Hello World from Node.js!");
+flushLogsAndExit();
+
+```
+
 ## Motivation
 `tldr;?`: To break the [winston][1] codebase into small modules that work together.
 
@@ -43,11 +98,23 @@ The [winston][1] codebase has been growing significantly with contributions and
   $ curl http://npmjs.org/install.sh | sh
 ```
 
-### Installing winston-loggly
+### Installing winston-loggly-bulk
+
+If you are running npm version 3 or higher then run the below command to setup the logging-
+
+``` bash
+  $ npm install winston-loggly-bulk
+```
+
+If you are running npm version 2 or lower then run the below command to setup the logging-
+
+``` bash
+  $ npm install winston-loggly-bulk winston
+```
+* __Note:__ To check the currrent npm version run the below command-
 
 ``` bash
-  $ npm install winston
-  $ npm install winston-loggly
+  $ npm -v
 ```
 
 ## Run Tests
@@ -74,8 +141,8 @@ Once you have valid configuration and credentials you can run tests with [npm][7
   npm test
 ```
 
-#### Author: [Charlie Robbins](http://blog.nodejitsu.com)
-#### License: MIT
+#### Author: [Charlie Robbins](http://www.github.com/indexzero)
+#### Contributors: [Loggly](http://github.com/loggly), [Shweta Jain](http://github.com/shwetajain148),
 
 [0]: http://loggly.com
 [1]: https://github.com/flatiron/winston

lib/winston-loggly.js

@@ -6,17 +6,20 @@
  *
  */
 
-var events = require('events'),
-    loggly = require('loggly'),
+var clone = require('clone'),
+    loggly = require('node-loggly-bulk'),
     util = require('util'),
     winston = require('winston'),
+    Transport = require('winston-transport'),
     Stream = require('stream').Stream;
 
 //
 // Remark: This should be at a higher level.
 //
 var code = /\u001b\[(\d+(;\d+)*)?m/g;
 
+var timerFunctionForProcessExit = null;
+
 //
 // ### function Loggly (options)
 // #### @options {Object} Options for this instance.
@@ -33,7 +36,7 @@ var Loggly = exports.Loggly = function (options) {
     options.token = options.inputToken;
   }
 
-  winston.Transport.call(this, options);
+  Transport.call(this, options);
   if (!options.subdomain) {
     throw new Error('Loggly Subdomain is required');
   }
@@ -50,33 +53,57 @@ var Loggly = exports.Loggly = function (options) {
   this.client = loggly.createClient({
     subdomain: options.subdomain,
     auth: options.auth || null,
-    json: options.json || false,
+    json: options.json || false, //TODO: should be false
     proxy: options.proxy || null,
     token: options.token,
     tags: tags,
-    isBulk: options.isBulk || false
+    isBulk: options.isBulk || false,
+    bufferOptions: options.bufferOptions || {size: 500, retriesInMilliSeconds: 30 * 1000}
   });
 
-  this.timestamp = options.timestamp || false;
+  this.timestamp = options.timestamp === false ? false : true;
   this.stripColors = options.stripColors || false;
 };
 
+//
+// Helper function to call process.exit() after waiting
+// 10 seconds.
+//
+var flushLogsAndExit = exports.flushLogsAndExit = function () {
+    if (timerFunctionForProcessExit === null) {
+      timerFunctionForProcessExit = setInterval(function () {
+        process.exit();
+      },10000);
+    }
+}
+
 //
 // Inherit from `winston.Transport`.
 //
-util.inherits(Loggly, winston.Transport);
+util.inherits(Loggly, Transport);
 
 //
 // Define a getter so that `winston.transports.Loggly`
 // is available and thus backwards compatible.
 //
 winston.transports.Loggly = Loggly;
+winston.transports.flushLogsAndExit = flushLogsAndExit;
 
 //
 // Expose the name of this Transport on the prototype
 //
 Loggly.prototype.name = 'loggly';
 
+const validateMetadata = (meta) => {
+  if (meta == null) {
+    return {};
+  } else if (typeof meta !== 'object') {
+    return { metadata: meta };
+  } else {
+    return clone(meta);
+  }
+}
+
 //
 // ### function log (level, msg, [meta], callback)
 // #### @level {string} Level at which to log the message.
@@ -86,34 +113,35 @@ Loggly.prototype.name = 'loggly';
 // Core logging method exposed to Winston. Metadata is optional.
 //
 Loggly.prototype.log = function (level, msg, meta, callback) {
+
+  const message = validateMetadata(meta);
+
   if (this.silent) {
     return callback(null, true);
   }
 
-  if (this.timestamp && (!meta || !meta.timestamp)) {
-    meta = meta || {};
-    meta.timestamp = (new Date()).toISOString();
+  if (this.timestamp && !message.timestamp) {
+    message.timestamp = (new Date()).toISOString();
   }
 
   if (this.stripColors) {
     msg = ('' + msg).replace(code, '');
   }
 
-  var message = winston.clone(meta || {}),
-      self    = this;
+  const self = this;
 
   message.level = level;
-  message.message = msg;
+  message.message = msg || message.message;
 
   //
   // Helper function for responded to logging.
   //
-  function logged() {
+  function logged(err) {
     self.emit('logged');
-    callback(null, true);
+    callback(err, true);
   }
 
-  return meta && meta.tags
+  return (meta && meta.tags)
     ? this.client.log(message, meta.tags, logged)
     : this.client.log(message, logged);
 };
@@ -123,9 +151,9 @@ Loggly.prototype.log = function (level, msg, meta, callback) {
 // #### @options {Object} Set stream options
 // Returns a log stream.
 //
-Loggly.prototype.stream = function(options) {
+Loggly.prototype.stream = function(maybeOptions) {
   var self = this,
-      options = options || {},
+      options = maybeOptions || {},
       stream = new Stream,
       last,
       start = options.start,
@@ -157,15 +185,15 @@ Loggly.prototype.stream = function(options) {
         return setTimeout(check, 2000);
       }
 
-      var result = res[res.length-1];
+      var result = results[results.length-1];
       if (result && result.timestamp) {
         if (last == null) {
           last = result.timestamp;
           return;
         }
         last = result.timestamp;
       } else {
-        return func();
+        return;
       }
 
       results.forEach(function(log) {
@@ -218,10 +246,10 @@ Loggly.prototype.formatQuery = function (query) {
 // ### function formatResults (results, options)
 // #### @results {Object|Array} Results returned from `.query`.
 // #### @options {Object} **Optional** Formatting options
-// Formats the specified `results` with the given `options` accordinging
+// Formats the specified `results` with the given `options` according
 // to the implementation of this transport.
 //
-Loggly.prototype.formatResults = function (results, options) {
+Loggly.prototype.formatResults = function (results, _options) {
   return results;
 };