feat(extension-metrics): add metrics extension for prometheus

extensions/metrics/.npmrc

@@ -0,0 +1 @@
+package-lock=true

extensions/metrics/LICENSE

@@ -0,0 +1,25 @@
+Copyright (c) IBM Corp. 2019. All Rights Reserved.
+Node module: @loopback/extension-metrics
+This project is licensed under the MIT License, full text below.
+
+--------
+
+MIT license
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

extensions/metrics/README.md

@@ -0,0 +1,202 @@
+# @loopback/extension-metrics
+
+This module contains a component to report metrics for
+[Prometheus](https://prometheus.io/).
+
+## Installation
+
+```sh
+npm install --save @loopback/extension-metrics
+```
+
+## Basic use
+
+The component should be loaded in the constructor of your custom Application
+class.
+
+Start by importing the component class:
+
+```ts
+import {MetricsComponent} from '@loopback/extension-metrics';
+```
+
+In the constructor, add the component to your application:
+
+```ts
+this.component(MetricsComponent);
+```
+
+By default, Metrics route is mounted at `/metrics`. This path can be customized
+via Metrics configuration as follows:
+
+```ts
+this.bind(MetricsBindings.CONFIG).to({
+  endpoint: {
+    basePath: '/metrics',
+  },
+  defaultMetrics: {
+    options: {
+      timeout: 5000,
+    },
+  },
+});
+```
+
+## Metrics Collected
+
+There are three types of metrics being collected by this component:
+
+1. Node.js metrics - built-in by https://github.com/siimon/prom-client
+2. LoopBack method invocations - built-in by this module using an interceptor
+3. Metrics by the application code or other modules
+
+## Pull vs Push
+
+Prometheus supports two modes to collect metrics:
+
+- pull - scaping from metrics http endpoint exposed by the system being
+  monitored
+- push - pushing metrics from the system being monitored to a push gateway
+
+See
+https://prometheus.io/docs/introduction/faq/#why-do-you-pull-rather-than-push
+
+## Try it out
+
+```sh
+npm run demo
+```
+
+### /metrics endpoint
+
+http://localhost:3000/metrics returns metrics in plain text format. It includes
+information for the Node.js process as well as LoopBack method invocations.
+
+```
+# HELP process_cpu_user_seconds_total Total user CPU time spent in seconds.
+# TYPE process_cpu_user_seconds_total counter
+process_cpu_user_seconds_total 0.132181 1564508354524
+
+# HELP process_cpu_system_seconds_total Total system CPU time spent in seconds.
+# TYPE process_cpu_system_seconds_total counter
+process_cpu_system_seconds_total 0.023608999999999998 1564508354524
+
+# HELP process_cpu_seconds_total Total user and system CPU time spent in seconds.
+# TYPE process_cpu_seconds_total counter
+process_cpu_seconds_total 0.15578999999999998 1564508354524
+
+# HELP process_start_time_seconds Start time of the process since unix epoch in seconds.
+# TYPE process_start_time_seconds gauge
+process_start_time_seconds 1564508343
+
+# HELP process_resident_memory_bytes Resident memory size in bytes.
+# TYPE process_resident_memory_bytes gauge
+process_resident_memory_bytes 61800448 1564508354524
+
+# HELP nodejs_eventloop_lag_seconds Lag of event loop in seconds.
+# TYPE nodejs_eventloop_lag_seconds gauge
+nodejs_eventloop_lag_seconds 0.002172946 1564508354526
+
+# HELP nodejs_active_handles Number of active libuv handles grouped by handle type. Every handle type is C++ class name.
+# TYPE nodejs_active_handles gauge
+nodejs_active_handles{type="WriteStream"} 2 1564508354524
+nodejs_active_handles{type="Server"} 1 1564508354524
+nodejs_active_handles{type="Socket"} 2 1564508354524
+
+# HELP nodejs_active_handles_total Total number of active handles.
+# TYPE nodejs_active_handles_total gauge
+nodejs_active_handles_total 5 1564508354526
+
+# HELP nodejs_active_requests Number of active libuv requests grouped by request type. Every request type is C++ class name.
+# TYPE nodejs_active_requests gauge
+
+# HELP nodejs_active_requests_total Total number of active requests.
+# TYPE nodejs_active_requests_total gauge
+nodejs_active_requests_total 0 1564508354526
+
+# HELP nodejs_heap_size_total_bytes Process heap size from node.js in bytes.
+# TYPE nodejs_heap_size_total_bytes gauge
+nodejs_heap_size_total_bytes 27545600 1564508354526
+
+# HELP nodejs_heap_size_used_bytes Process heap size used from node.js in bytes.
+# TYPE nodejs_heap_size_used_bytes gauge
+nodejs_heap_size_used_bytes 23788272 1564508354526
+
+# HELP nodejs_external_memory_bytes Nodejs external memory size in bytes.
+# TYPE nodejs_external_memory_bytes gauge
+nodejs_external_memory_bytes 1234918 1564508354526
+
+# HELP nodejs_heap_space_size_total_bytes Process heap space size total from node.js in bytes.
+# TYPE nodejs_heap_space_size_total_bytes gauge
+nodejs_heap_space_size_total_bytes{space="read_only"} 524288 1564508354526
+nodejs_heap_space_size_total_bytes{space="new"} 1048576 1564508354526
+nodejs_heap_space_size_total_bytes{space="old"} 16900096 1564508354526
+nodejs_heap_space_size_total_bytes{space="code"} 688128 1564508354526
+nodejs_heap_space_size_total_bytes{space="map"} 1576960 1564508354526
+nodejs_heap_space_size_total_bytes{space="large_object"} 6758400 1564508354526
+nodejs_heap_space_size_total_bytes{space="code_large_object"} 49152 1564508354526
+nodejs_heap_space_size_total_bytes{space="new_large_object"} 0 1564508354526
+
+# HELP nodejs_heap_space_size_used_bytes Process heap space size used from node.js in bytes.
+# TYPE nodejs_heap_space_size_used_bytes gauge
+nodejs_heap_space_size_used_bytes{space="read_only"} 31712 1564508354526
+nodejs_heap_space_size_used_bytes{space="new"} 9584 1564508354526
+nodejs_heap_space_size_used_bytes{space="old"} 15723128 1564508354526
+nodejs_heap_space_size_used_bytes{space="code"} 377600 1564508354526
+nodejs_heap_space_size_used_bytes{space="map"} 918480 1564508354526
+nodejs_heap_space_size_used_bytes{space="large_object"} 6726408 1564508354526
+nodejs_heap_space_size_used_bytes{space="code_large_object"} 3456 1564508354526
+nodejs_heap_space_size_used_bytes{space="new_large_object"} 0 1564508354526
+
+# HELP nodejs_heap_space_size_available_bytes Process heap space size available from node.js in bytes.
+# TYPE nodejs_heap_space_size_available_bytes gauge
+nodejs_heap_space_size_available_bytes{space="read_only"} 492264 1564508354526
+nodejs_heap_space_size_available_bytes{space="new"} 1038368 1564508354526
+nodejs_heap_space_size_available_bytes{space="old"} 1105240 1564508354526
+nodejs_heap_space_size_available_bytes{space="code"} 285952 1564508354526
+nodejs_heap_space_size_available_bytes{space="map"} 657072 1564508354526
+nodejs_heap_space_size_available_bytes{space="large_object"} 0 1564508354526
+nodejs_heap_space_size_available_bytes{space="code_large_object"} 0 1564508354526
+nodejs_heap_space_size_available_bytes{space="new_large_object"} 1047952 1564508354526
+
+# HELP nodejs_version_info Node.js version info.
+# TYPE nodejs_version_info gauge
+nodejs_version_info{version="v12.4.0",major="12",minor="4",patch="0"} 1
+
+# HELP loopback_invocation_duration_seconds method invocation
+# TYPE loopback_invocation_duration_seconds gauge
+
+# HELP loopback_invocation_duration_histogram method invocation histogram
+# TYPE loopback_invocation_duration_histogram histogram
+
+# HELP loopback_invocation_total method invocation counts
+# TYPE loopback_invocation_total counter
+loopback_invocation_total 1
+
+# HELP loopback_invocation_duration_summary method invocation summary
+# TYPE loopback_invocation_duration_summary summary
+```
+
+### Prometheus UI
+
+Open http://localhost:9090 to load Prometheus web UI.
+
+![Prometheus Demo](prometheus-demo.png)
+
+## Contributions
+
+- [Guidelines](https://github.com/strongloop/loopback-next/blob/master/docs/CONTRIBUTING.md)
+- [Join the team](https://github.com/strongloop/loopback-next/issues/110)
+
+## Tests
+
+Run `npm test` from the root folder.
+
+## Contributors
+
+See
+[all contributors](https://github.com/strongloop/loopback-next/graphs/contributors).
+
+## License
+
+MIT

extensions/metrics/index.d.ts

@@ -0,0 +1,6 @@
+// Copyright IBM Corp. 2018. All Rights Reserved.
+// Node module: @loopback/rest-explorer
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/licenses/MIT
+
+export * from './dist';

extensions/metrics/index.js

@@ -0,0 +1,6 @@
+// Copyright IBM Corp. 2019. All Rights Reserved.
+// Node module: @loopback/extension-metrics
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/licenses/MIT
+
+module.exports = require('./dist');

extensions/metrics/index.ts

@@ -0,0 +1,8 @@
+// Copyright IBM Corp. 2019. All Rights Reserved.
+// Node module: @loopback/extension-metrics
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/licenses/MIT
+
+// DO NOT EDIT THIS FILE
+// Add any additional (re)exports to src/index.ts instead.
+export * from './src';

extensions/metrics/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@loopback/extension-metrics",
+  "version": "0.1.0",
+  "description": "LoopBack Metrics for Prometheus",
+  "engines": {
+    "node": ">=8.9"
+  },
+  "scripts": {
+    "build": "lb-tsc",
+    "clean": "lb-clean loopback-extension-metrics*.tgz dist tsconfig.build.tsbuildinfo package",
+    "pretest": "npm run build",
+    "test": "lb-mocha \"dist/__tests__/**/*.js\"",
+    "verify": "npm pack && tar xf loopback-extension-metrics*.tgz && tree package && npm run clean",
+    "demo": "./src/__examples__/demo.sh"
+  },
+  "author": "IBM Corp.",
+  "copyright.owner": "IBM Corp.",
+  "license": "MIT",
+  "dependencies": {
+    "@loopback/context": "^1.21.0",
+    "@loopback/core": "^1.8.7",
+    "@loopback/rest": "^1.16.5",
+    "prom-client": "^11.5.3"
+  },
+  "devDependencies": {
+    "@loopback/build": "^2.0.5",
+    "@loopback/eslint-config": "^2.0.2",
+    "@loopback/testlab": "^1.7.1",
+    "@types/node": "^10.14.13"
+  },
+  "keywords": [
+    "LoopBack",
+    "Cloud Native",
+    "Prometheus",
+    "Metrics"
+  ],
+  "files": [
+    "README.md",
+    "index.js",
+    "index.d.ts",
+    "dist",
+    "src",
+    "!*/__tests__",
+    "templates"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/strongloop/loopback-next.git",
+    "directory": "extensions/metrics"
+  }
+}

extensions/metrics/src/__examples__/demo.sh

@@ -0,0 +1,21 @@
+#!/bin/bash
+
+# This script runs prometheus to scape and visulize metrics collected for the
+# example LoopBack 4 application.
+
+DIR=`dirname $0`
+CWD=`pwd`
+CONFIG=$CWD/$DIR/prometheus.yml
+
+PROM_CONTAINER_NAME="prometheus_lb4_demo"
+docker rm -f $PROM_CONTAINER_NAME
+docker pull prom/prometheus:latest
+docker run --name $PROM_CONTAINER_NAME -p 9090:9090 -v $CONFIG:/etc/prometheus/prometheus.yml -d prom/prometheus
+
+echo Prometheus is running at http://localhost:9090.
+
+pushd $DIR/../.. >/dev/null
+npm run build
+node ./dist/__examples__/metrics
+popd
+

extensions/metrics/src/__examples__/metrics.ts

@@ -0,0 +1,19 @@
+// Copyright IBM Corp. 2019. All Rights Reserved.
+// Node module: @loopback/rest-explorer
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/licenses/MIT
+
+import {RestApplication} from '@loopback/rest';
+import {MetricsComponent} from '../';
+
+async function main() {
+  const app = new RestApplication({rest: {port: process.env.PORT || 3000}});
+  app.component(MetricsComponent);
+  await app.start();
+  console.log(app.restServer.url);
+}
+
+main().catch(err => {
+  console.error(err);
+  process.exit(1);
+});