roarr - npm Package Compare versions

Comparing version 1.3.1 to 1.4.0

dist/bin/index.js

@@ -1,2 +0,2 @@
-#!/bin/bash
+#!/usr/bin/env node
 'use strict';
@@ -8,92 +8,5 @@
 
-var _split = require('split2');
-
-var _split2 = _interopRequireDefault(_split);
-
-var _chalk = require('chalk');
-
-var _chalk2 = _interopRequireDefault(_chalk);
-
-var _prettyjson = require('prettyjson');
-
-var _prettyjson2 = _interopRequireDefault(_prettyjson);
-
 function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
 
-function _objectWithoutProperties(obj, keys) { var target = {}; for (var i in obj) { if (keys.indexOf(i) >= 0) continue; if (!Object.prototype.hasOwnProperty.call(obj, i)) continue; target[i] = obj[i]; } return target; }
-
-// @flow
-
-var argv = _yargs2.default.env('ROARR').help().options({
-  'include-context': {
-    default: true,
-    type: 'boolean'
-  }
-}).parse();
-
-var isRoarrLine = function isRoarrLine(text /*: string*/) /*: boolean*/ {
-  return text.includes('"message"') && text.includes('"sequence"');
-};
-
-var logLevelColorMap = {
-  DEBUG: 'gray',
-  ERROR: 'red',
-  FATAL: 'red',
-  INFO: 'cyan',
-  TRACE: 'gray',
-  WARN: 'yellow'
-};
-
-var createLogFormatter = function createLogFormatter() {
-  var stream = (0, _split2.default)(function (line) {
-    if (!isRoarrLine(line)) {
-      return null;
-    }
-
-    var message = JSON.parse(line);
-
-    var logLevel = message.context.logLevel.toUpperCase();
-
-    var logLevelColorName = logLevelColorMap[logLevel] || 'inverse';
-
-    var formattedMessage = '';
-
-    formattedMessage = '[' + new Date(message.time).toISOString() + '] ' + _chalk2.default[logLevelColorName](logLevel);
-
-    if (message.context.package) {
-      formattedMessage += ' (@' + message.context.package + ')';
-    }
-
-    if (message.context.namespace) {
-      formattedMessage += ' (#' + message.context.namespace + ')';
-    }
-
-    // eslint-disable-next-line no-console
-    console.log(formattedMessage + ': ' + message.message);
-
-    if (argv.includeContext && message.context) {
-      /* eslint-disable no-unused-vars */
-      var _message$context = message.context,
-          tmp0 = _message$context.application,
-          tmp1 = _message$context.logLevel,
-          tmp2 = _message$context.namespace,
-          tmp3 = _message$context.package,
-          tmp4 = _message$context.package,
-          rest = _objectWithoutProperties(_message$context, ['application', 'logLevel', 'namespace', 'package', 'package']);
-
-      /* eslint-enable */
-
-      if (Object.keys(rest).length) {
-        // eslint-disable-next-line no-console
-        console.log(_prettyjson2.default.render(rest) + '\n');
-      }
-    }
-
-    return null;
-  });
-
-  return stream;
-};
-
-process.stdin.pipe(createLogFormatter()).pipe(process.stdout);
+_yargs2.default.env('ROARR').commandDir('commands').help().wrap(80).parse();
 //# sourceMappingURL=index.js.map

package.json

@@ -20,2 +20,3 @@ {
     "sprintf-js": "^1.1.1",
+    "ulid": "^1.0.0",
     "yargs": "^9.0.1"
@@ -77,3 +78,3 @@ },
   },
-  "version": "1.3.1"
+  "version": "1.4.0"
 }

README.md

@@ -11,2 +11,3 @@ # Roarr
 
+* [Motivation](#motivation)
 * [Usage](#usage)
@@ -16,2 +17,3 @@ * [Prepending context using the global state](#prepending-context-using-the-global-state)
     * [jq primer](#jq-primer)
+* [Log message format](#log-message-format)
 * [API](#api)
@@ -32,2 +34,27 @@ * [`child`](#child)
 
+## Motivation
+
+For a long time I have been a big fan of using [`debug`](https://github.com/visionmedia/debug). `debug` is simple to use, works in Node.js and browser, does not require configuration and it is fast. However, problems arise when you need to parse logs. Anything but one-line text messages cannot be parsed in a safe way.
+
+To log structured data, I have been using [Winston](https://github.com/winstonjs/winston) and [Bunyan](https://github.com/trentm/node-bunyan). These packages are great for application-level logging. I have preferred Bunyan because of the [Bunyan CLI program](https://github.com/trentm/node-bunyan#cli-usage) used to pretty-print logs. However, these packages require program-level configuration – when constructing an instance of a logger, you need to define the transport and the log-level. This makes them unsuitable for use in code designed to be consumed by other applications.
+
+Then there is [pino](https://github.com/pinojs/pino). pino is fast JSON logger, it has CLI program equivalent to Bunyan, it decouples transports, and it has sane default configuration. Unfortunately, you still need to instantiate logger instance at the application-level. This makes it more suitable for application-level logging just like Winston and Bunyan.
+
+I needed a logger that:
+
+* Does not require initialisation.
+* Produces structured data.
+* [Decouples transports](#transports).
+* Has a [CLI program](#cli-tool).
+* Works in Node.js and browser.
+* Configurable using environment variables and [`global`](https://nodejs.org/api/globals.html) namespace.
+
+In other words,
+
+* a logger that I can use in an application code and in dependencies.
+* a logger that allows to correlate logs between the main application code and the dependency code.
+* a logger that works well with transports in external processes.
+
+Roarr is this logger.
+
 ## Usage
@@ -157,2 +184,29 @@
 
+## Log message format
+
+|Property name|Contents|
+|---|---|
+|`context`|Arbitrary, user-provided structured data. See [context property names](#context-property-names).|
+|`message`|User-provided message formatted using [printf](https://en.wikipedia.org/wiki/Printf_format_string).|
+|`sequence`|An incremental ID.|
+|`time`|Unix timestamp in milliseconds.|
+|`version`|Roarr log message format version.|
+
+Example:
+
+```js
+{
+  "context":{
+    "application": "task-runner",
+    "hostname": "curiosity.local",
+    "instanceId": "01BVBK4ZJQ182ZWF6FK4EC8FEY",
+    "taskId": 1
+  },
+  "message":"starting task ID 1",
+  "sequence":0,
+  "time":1506776210000,
+  "version":"1.0.0"
+}
+```
+
 ## API
@@ -247,7 +301,7 @@
 
-To format the logs, pipe the program output to `roarr` program, e.g.
+To format the logs, pipe the program output to `roarr pretty-print` program, e.g.
 
 ```bash
 $ npm install roarr -g
-$ ROARR_LOG=true node index.js | roarr
+$ ROARR_LOG=true node index.js | roarr pretty-print
 
@@ -308,5 +362,7 @@ ```
 |`application`|Name of the application (do not use in code intended for distribution; see `package` property instead).|
-|`package`|Name of the package.|
+|`hostname`|Machine hostname. See `roarr augment --append-hostname` option.|
+|`instanceId`|Unique instance ID. Used to distinguish log source in high-concurrency environments. See `roarr augment --append-instance-id` option.|
 |`logLevel`|Human-readable name of the log-level, e.g. "error". See [API](#api) for build-in loggers with a pre-set log-level.|
 |`namespace`|Namespace within a package, e.g. function name. Treat the same way that you would construct namespaces when using the [`debug`](https://github.com/visionmedia/debug) package.|
+|`package`|Name of the package.|
 
@@ -313,0 +369,0 @@ ### Using Roarr in an application

No alert changes

Improved metrics

Total package byte prevSize

51956

increased by32.39%

Number of package files

32

increased by60%

Lines of code

336

increased by38.27%

Number of lines in readme file

399

increased by16.33%

Worsened metrics

Dependency count

7

increased by16.67%

Dependency changes

• + Addedulid@^1.0.0

• + Addedulid@1.1.1(transitive)