Doc updates logging reporter (#45)

* Update docs and add Logging Reporter

* Update example output

* Update method to be protected

* Yarn Format

* pr feed back

* localhost -> yaorg.github.io

Author: fieldju

packages/measured-core/package.json

@@ -12,7 +12,7 @@
   "main": "./lib/index.js",
   "scripts": {
     "clean": "rm -fr build",
-    "format": "prettier --write '**/*.{ts,js}'",
+    "format": "prettier --write './lib/**/*.{ts,js}'",
     "lint": "eslint lib --ext .js",
     "test:node": "mocha './test/**/test-*.js'",
     "test:node:coverage": "nyc --report-dir build/coverage/ --reporter=html --reporter=text mocha './test/**/test-*.js'",

packages/measured-node-metrics/lib/utils/CpuUtils.js

@@ -16,7 +16,7 @@ module.exports = {
 
     cpus.forEach(cpu => {
       //Total up the time in the cores tick
-      Object.keys(cpu.times).forEach((type) => {
+      Object.keys(cpu.times).forEach(type => {
         totalTick += cpu.times[type];
       });
       //Total up the idle time of the core
@@ -37,6 +37,6 @@ module.exports = {
     const idleDifference = endMeasure.idle - startMeasure.idle;
     const totalDifference = endMeasure.total - startMeasure.total;
     //Calculate the average percentage CPU usage
-    return Math.ceil(100 - (100 * idleDifference / totalDifference));
+    return Math.ceil(100 - 100 * idleDifference / totalDifference);
   }
 };

packages/measured-node-metrics/package.json

@@ -12,7 +12,7 @@
   "main": "./lib/index.js",
   "scripts": {
     "clean": "rm -fr build",
-    "format": "prettier --write '**/*.{ts,js}'",
+    "format": "prettier --write './lib/**/*.{ts,js}'",
     "lint": "eslint lib --ext .js",
     "test:node": "mocha './test/**/test-*.js'",
     "test:node:coverage": "nyc --report-dir build/coverage/ --reporter=html --reporter=text mocha './test/**/test-*.js'",

packages/measured-reporting/README.md

@@ -15,19 +15,94 @@ npm install measured-reporting
 ### [Self Reporting Metrics Registry](https://yaorg.github.io/node-measured/SelfReportingMetricsRegistry.html)
 A dimensional aware self-reporting metrics registry, just supply this class with a reporter implementation at instantiation and this is all you need to instrument application level metrics in your app.
 
+See the [SelfReportingMetricsRegistryOptions](http://yaorg.github.io/node-measured/build/docs/packages/measured-reporting/global.html#SelfReportingMetricsRegistryOptions) for advanced configuration.
+
+```javascript
+const { SelfReportingMetricsRegistry, LoggingReporter } = require('measured-reporting');
+const registry = new SelfReportingMetricsRegistry(new LoggingReporter({
+  defaultDimensions: {
+    hostname: os.hostname()
+  }
+}));
+
+// The metric will flow through LoggingReporter#_reportMetrics(metrics) every 10 seconds by default
+const myCounter = registry.getOrCreateCounter('my-counter');
+
+```
+
 ### [Reporter Abstract Class](https://yaorg.github.io/node-measured/Reporter.html)
-The base class for reporter implementations. This class is extended and the [_reportMetrics(metrics)](https://yaorg.github.io/node-measured/Reporter.html#_reportMetrics__anchor) method gets overridden to create an data aggregator specific reporter. See the [SignalFx Reporter](../measured-signalfx-reporter/) for an example implementation.
+Extend this class and override the [_reportMetrics(metrics)](https://yaorg.github.io/node-measured/Reporter.html#_reportMetrics__anchor) method to create a vendor specific reporter implementation. 
 
+See the [ReporterOptions](http://yaorg.github.io/node-measured/build/docs/packages/measured-reporting/global.html#ReporterOptions) for advanced configuration.
+
+#### Current Implementations
+- [SignalFx Reporter](https://yaorg.github.io/node-measured/SignalFxMetricsReporter.html) in the `measured-signalfx-reporter` package.
+  - reports metrics to SignalFx.
+- [Logging Reporter](https://yaorg.github.io/node-measured/LoggingReporter.html) in the `measured-reporting` package.
+  - A reporter impl that simply logs the metrics via the Logger
+
+#### Creating an anonymous Implementation
 You can technically create an anonymous instance of this, see the following example.
 ```javascript
-// Create anonymous console logging Reporter instance.
-const reporter = new class extends Reporter {
+const os = require('os');
+const process = require('process');
+const { SelfReportingMetricsRegistry, Reporter } = require('measured-reporting');
+
+// Create a self reporting registry with an anonymous Reporter instance;
+const registry = new SelfReportingMetricsRegistry(
+  new class extends Reporter {
+    constructor() {
+      super({
+        defaultDimensions: {
+          hostname: os.hostname(),
+          env: process.env['NODE_ENV'] ? process.env['NODE_ENV'] : 'unset'
+        }
+      })
+    }
+
     _reportMetrics(metrics) {
-        metrics.forEach(metric => console.log(JSON.stringify(metric.toJSON())))
+      metrics.forEach(metric => {
+        console.log(JSON.stringify({
+          metricName: metric.name,
+          dimensions: this._getDimensions(metric),
+          data: metric.metricImpl.toJSON()
+        }))
+      });
     }
-};
+  }()
+);
+
+// create a gauge that reports the process uptime every second
+const processUptimeGauge = registry.getOrCreateGauge('node.process.uptime', () => process.uptime(), {}, 1);
+```
+
+Example output:
+```bash
+APP5HTD6ACCD8C:foo jfiel2$ NODE_ENV=development node index.js | bunyan
+[2018-06-06T23:39:49.678Z]  INFO: Reporter/9526 on APP5HTD6ACCD8C: {"metricName":"node.process.uptime","dimensions":{"hostname":"APP5HTD6ACCD8C","env":"development"},"data":0.092}
+[2018-06-06T23:39:50.685Z]  INFO: Reporter/9526 on APP5HTD6ACCD8C: {"metricName":"node.process.uptime","dimensions":{"hostname":"APP5HTD6ACCD8C","env":"development"},"data":1.099}
+[2018-06-06T23:39:51.690Z]  INFO: Reporter/9526 on APP5HTD6ACCD8C: {"metricName":"node.process.uptime","dimensions":{"hostname":"APP5HTD6ACCD8C","env":"development"},"data":2.104}
+[2018-06-06T23:39:52.691Z]  INFO: Reporter/9526 on APP5HTD6ACCD8C: {"metricName":"node.process.uptime","dimensions":{"hostname":"APP5HTD6ACCD8C","env":"development"},"data":3.105}
+[2018-06-06T23:39:53.692Z]  INFO: Reporter/9526 on APP5HTD6ACCD8C: {"metricName":"node.process.uptime","dimensions":{"hostname":"APP5HTD6ACCD8C","env":"development"},"data":4.106}
+```
+
+
+Consider creating a proper class and contributing it back to Measured if it is generic and sharable.
+
+### [Logging Reporter Class](https://yaorg.github.io/node-measured/LoggingReporter.html)
+A simple reporter that logs the metrics via the Logger.
+
+See the [ReporterOptions](http://yaorg.github.io/node-measured/build/docs/packages/measured-reporting/global.html#ReporterOptions) for advanced configuration.
+
+```javascript
+const { SelfReportingMetricsRegistry, LoggingReporter } = require('measured-reporting');
+const registry = new SelfReportingMetricsRegistry(new LoggingReporter({
+  logger: myLogerImpl, // defaults to new bunyan logger if not supplied
+  defaultDimensions: {
+    hostname: require('os').hostname()
+  }
+}));
 ```
-It would of course be better to create a proper class and contribute it back as a new package for measured if it is generic and sharable.
 
 ## What are dimensions?
 As described by Signal Fx:

packages/measured-reporting/lib/index.js

@@ -1,5 +1,6 @@
 const SelfReportingMetricsRegistry = require('./registries/SelfReportingMetricsRegistry');
 const Reporter = require('./reporters/Reporter');
+const LoggingReporter = require('./reporters/LoggingReporter');
 const inputValidators = require('./validators/inputValidators');
 
 /**
@@ -8,14 +9,30 @@ const inputValidators = require('./validators/inputValidators');
  */
 module.exports = {
   /**
+   * The Self Reporting Metrics Registry Class.
+   *
    * @type {SelfReportingMetricsRegistry}
    */
   SelfReportingMetricsRegistry,
+
   /**
+   * The abstract / base Reporter class.
+   *
    * @type {Reporter}
    */
   Reporter,
+
+  /**
+   * The basic included reference reporter, simply logs the metrics.
+   * See {ReporterOptions} for options.
+   *
+   * @type {LoggingReporter}
+   */
+  LoggingReporter,
+
   /**
+   * Various Input Validation functions.
+   *
    * @type {inputValidators}
    */
   inputValidators

packages/measured-reporting/lib/registries/SelfReportingMetricsRegistry.js

@@ -120,8 +120,8 @@ class SelfReportingMetricsRegistry {
    * Creates a {@link Histogram} or gets the existing Histogram for a given name and dimension combo
    *
    * @param {string} name The Metric name
-   * @param {Dimensions} dimensions any custom {@link Dimensions} for the Metric
-   * @param {number} publishingIntervalInSeconds a optional custom publishing interval
+   * @param {Dimensions} [dimensions] any custom {@link Dimensions} for the Metric
+   * @param {number} [publishingIntervalInSeconds] a optional custom publishing interval
    * @return {Histogram}
    */
   getOrCreateHistogram(name, dimensions, publishingIntervalInSeconds) {
@@ -143,8 +143,8 @@ class SelfReportingMetricsRegistry {
    * Creates a {@link Meter} or gets the existing Meter for a given name and dimension combo
    *
    * @param {string} name The Metric name
-   * @param {Dimensions} dimensions any custom {@link Dimensions} for the Metric
-   * @param {number} publishingIntervalInSeconds a optional custom publishing interval
+   * @param {Dimensions} [dimensions] any custom {@link Dimensions} for the Metric
+   * @param {number} [publishingIntervalInSeconds] a optional custom publishing interval
    * @return {Meter}
    */
   getOrCreateMeter(name, dimensions, publishingIntervalInSeconds) {
@@ -165,8 +165,8 @@ class SelfReportingMetricsRegistry {
    * Creates a {@link Counter} or gets the existing Counter for a given name and dimension combo
    *
    * @param {string} name The Metric name
-   * @param {Dimensions} dimensions any custom {@link Dimensions} for the Metric
-   * @param {number} publishingIntervalInSeconds a optional custom publishing interval
+   * @param {Dimensions} [dimensions] any custom {@link Dimensions} for the Metric
+   * @param {number} [publishingIntervalInSeconds] a optional custom publishing interval
    * @return {Counter}
    */
   getOrCreateCounter(name, dimensions, publishingIntervalInSeconds) {
@@ -188,8 +188,8 @@ class SelfReportingMetricsRegistry {
    * Creates a {@link Timer} or gets the existing Timer for a given name and dimension combo.
    *
    * @param {string} name The Metric name
-   * @param {Dimensions} dimensions any custom {@link Dimensions} for the Metric
-   * @param {number} publishingIntervalInSeconds a optional custom publishing interval
+   * @param {Dimensions} [dimensions] any custom {@link Dimensions} for the Metric
+   * @param {number} [publishingIntervalInSeconds] a optional custom publishing interval
    * @return {Timer}
    */
   getOrCreateTimer(name, dimensions, publishingIntervalInSeconds) {
@@ -211,8 +211,8 @@ class SelfReportingMetricsRegistry {
    * Creates a {@link SettableGauge} or gets the existing SettableGauge for a given name and dimension combo.
    *
    * @param {string} name The Metric name
-   * @param {Dimensions} dimensions any custom {@link Dimensions} for the Metric
-   * @param {number} publishingIntervalInSeconds a optional custom publishing interval
+   * @param {Dimensions} [dimensions] any custom {@link Dimensions} for the Metric
+   * @param {number} [publishingIntervalInSeconds] a optional custom publishing interval
    * @return {SettableGauge}
    */
   getOrCreateSettableGauge(name, dimensions, publishingIntervalInSeconds) {
@@ -236,11 +236,17 @@ class SelfReportingMetricsRegistry {
    * @param {string} name The Metric name.
    * @param {function} valueProducingPromiseCallback.
    * @param {number} cachedGaugeUpdateIntervalInSeconds.
-   * @param {Dimensions} dimensions any custom {@link Dimensions} for the Metric.
-   * @param {number} publishingIntervalInSeconds a optional custom publishing interval.
+   * @param {Dimensions} [dimensions] any custom {@link Dimensions} for the Metric.
+   * @param {number} [publishingIntervalInSeconds] a optional custom publishing interval.
    * @return {CachedGauge}
    */
-  getOrCreateCachedGauge(name, valueProducingPromiseCallback, cachedGaugeUpdateIntervalInSeconds, dimensions, publishingIntervalInSeconds) {
+  getOrCreateCachedGauge(
+    name,
+    valueProducingPromiseCallback,
+    cachedGaugeUpdateIntervalInSeconds,
+    dimensions,
+    publishingIntervalInSeconds
+  ) {
     validateCachedGaugeOptions(name, valueProducingPromiseCallback, dimensions, publishingIntervalInSeconds);
 
     let cachedGauge;

packages/measured-reporting/lib/reporters/LoggingReporter.js

@@ -0,0 +1,31 @@
+const Reporter = require('./Reporter');
+
+/**
+ * A reporter impl that simply logs the metrics via the Logger.
+ *
+ * @example
+ * const { SelfReportingMetricsRegistry, LoggingReporter } = require('measured-reporting');
+ * const registry = new SelfReportingMetricsRegistry(new LoggingReporter());
+ *
+ * @extends {Reporter}
+ */
+class LoggingReporter extends Reporter {
+  /**
+   * Logs the metrics via the inherited logger instance.
+   * @param {MetricWrapper[]} metrics
+   * @protected
+   */
+  _reportMetrics(metrics) {
+    metrics.forEach(metric => {
+      this._log.info(
+        JSON.stringify({
+          metricName: metric.name,
+          dimensions: this._getDimensions(metric),
+          data: metric.metricImpl.toJSON()
+        })
+      );
+    });
+  }
+}
+
+module.exports = LoggingReporter;

packages/measured-reporting/lib/reporters/Reporter.js

@@ -8,6 +8,50 @@ const DEFAULT_REPORTING_INTERVAL_IN_SECONDS = 10;
  * The abstract reporter that specific implementations can extend to create a Self Reporting Metrics Registry Reporter.
  *
  * {@link SelfReportingMetricsRegistry}
+ *
+ * @example
+ * const os = require('os');
+ * const process = require('process');
+ * const { SelfReportingMetricsRegistry, Reporter } = require('measured-reporting');
+ *
+ * // Create a self reporting registry with a named anonymous reporter instance;
+ * const registry = new SelfReportingMetricsRegistry(
+ *   new class ConsoleReporter extends Reporter {
+ *     constructor() {
+ *       super({
+ *         defaultDimensions: {
+ *           hostname: os.hostname(),
+ *           env: process.env['NODE_ENV'] ? process.env['NODE_ENV'] : 'unset'
+ *         }
+ *        })
+ *     }
+ *
+ *     _reportMetrics(metrics) {
+ *        metrics.forEach(metric => {
+ *          console.log(JSON.stringify({
+ *            metricName: metric.name,
+ *            dimensions: this._getDimensions(metric),
+ *            data: metric.metricImpl.toJSON()
+ *           }))
+ *       });
+ *     }
+ *  }()
+ * );
+ *
+ * @example
+ * // Create a regular class that extends Reporter
+ * class LoggingReporter extends Reporter {
+ *   _reportMetrics(metrics) {
+ *     metrics.forEach(metric => {
+ *       this._log.info(JSON.stringify({
+ *        metricName: metric.name,
+ *        dimensions: this._getDimensions(metric),
+ *        data: metric.metricImpl.toJSON()
+ *       }))
+ *     });
+ *   }
+ * }
+ *
  * @abstract
  */
 class Reporter {

packages/measured-reporting/package.json

@@ -12,7 +12,7 @@
   "main": "./lib/index.js",
   "scripts": {
     "clean": "rm -fr build",
-    "format": "prettier --write '**/*.{ts,js}'",
+    "format": "prettier --write './lib/**/*.{ts,js}'",
     "lint": "eslint lib --ext .js",
     "test:node": "mocha './test/**/test-*.js'",
     "test:node:coverage": "nyc --report-dir build/coverage/ --reporter=html --reporter=text mocha './test/**/test-*.js'",

packages/measured-reporting/test/unit/reporters/test-Reporter.js

@@ -118,9 +118,9 @@ describe('Reporter', () => {
   it('Can be used to create an anonymous instance of a reporter', () => {
     const anonymousReporter = new class extends Reporter {
       _reportMetrics(metrics) {
-        metrics.forEach(metric => console.log(JSON.stringify(metric)))
+        metrics.forEach(metric => console.log(JSON.stringify(metric)));
       }
-    };
+    }();
 
     validateReporterInstance(anonymousReporter);
   });