hyperledger-cacti · petermetz · Mar 31, 2021 · Mar 31, 2021
@@ -8,6 +8,10 @@
 - [Deployment Scenarios](#deployment-scenarios)
   - [Production Deployment Example](#production-deployment-example)
   - [Low Resource Deployment Example](#low-resource-deployment-example)
+- [Prometheus Exporter](#prometheus-exporter)
+  - [Usage Prometheus](#usage-prometheus)
+  - [Prometheus Integration](#prometheus-integration)
+  - [Helper Code](#helper-code)
 - [FAQ](#faq)
   - [What is the difference between a Cactus Node and a Cactus API Server?](#what-is-the-difference-between-a-cactus-node-and-a-cactus-api-server)
   - [Is the API server horizontally scalable?](#is-the-api-server-horizontally-scalable)
@@ -196,6 +200,47 @@ of the machine they are hosted on:
 
 ![deployment-low-resource-example.png](https://github.com/hyperledger/cactus/raw/4a337be719a9d2e2ccb877edccd7849f4be477ec/whitepaper/deployment-low-resource-example.png)
 
+## Prometheus Exporter
+This class creates a prometheus exporter, which scrapes the total Cactus node count.
+
+### Usage Prometheus
+The prometheus exporter object is initialized in the `ApiServer` class constructor itself, so instantiating the object of the `ApiServer` class, gives access to the exporter object.
+You can also initialize the prometheus exporter object seperately and then pass it to the `IApiServerConstructorOptions` interface for `ApiServer` constructor.
+
+`getPrometheusExporterMetricsV1` function returns the prometheus exporter metrics, currently displaying the total plugins imported, which currently refreshes to match the plugin count, everytime `setTotalPluginImports` method is called.
+
+### Prometheus Integration
+To use Prometheus with this exporter make sure to install [Prometheus main component](https://prometheus.io/download/).
+Once Prometheus is setup, the corresponding scrape_config needs to be added to the prometheus.yml
+
+```(yaml)
+- job_name: 'consortium_manual_exporter'
+  metrics_path: /api/v1/api-server/get-prometheus-exporter-metrics
+  scrape_interval: 5s
+  static_configs:
+    - targets: ['{host}:{port}']
+```
+
+Here the `host:port` is where the prometheus exporter metrics are exposed. The test cases (For example, packages/cactus-plugin-consortium-manual/src/test/typescript/unit/consortium/get-node-jws-endpoint-v1.test.ts) exposes it over `0.0.0.0` and a random port(). The random port can be found in the running logs of the test case and looks like (42379 in the below mentioned URL)
+`Metrics URL: http://0.0.0.0:42379/api/v1/api-server/get-prometheus-exporter-metrics/get-prometheus-exporter-metrics`
+
+Once edited, you can start the prometheus service by referencing the above edited prometheus.yml file.
+On the prometheus graphical interface (defaulted to http://localhost:9090), choose **Graph** from the menu bar, then select the **Console** tab. From the **Insert metric at cursor** drop down, select **cactus_api_server_total_plugin_imports** and click **execute**
+
+### Helper code
+
+###### response.type.ts
+This file contains the various responses of the metrics.
+
+###### data-fetcher.ts
+This file contains functions encasing the logic to process the data points.
+
+###### metrics.ts
+This file lists all the prometheus metrics and what they are used for.
+
+
+
+
 
 ## FAQ
 

@@ -101,6 +101,7 @@
     "express-openapi-validator": "3.10.0",
     "jose": "1.27.2",
     "node-forge": "0.10.0",
+    "prom-client": "13.1.0",
     "semver": "7.3.2",
     "uuid": "7.0.2"
   },

@@ -73,6 +73,10 @@
                     "createdAt",
                     "memoryUsage"
                 ]
+            },
+            "PrometheusExporterMetricsResponse": {
+                "type": "string",
+                "nullable": false
             }
         }
     },
@@ -102,6 +106,31 @@
                     }
                 }
             }
+        },
+        "/api/v1/api-server/get-prometheus-exporter-metrics": {
+            "get": {
+                "x-hyperledger-cactus": {
+                    "http": {
+                        "verbLowerCase": "get",
+                        "path": "/api/v1/api-server/get-prometheus-exporter-metrics"
+                    }
+                },
+                "operationId": "getPrometheusExporterMetricsV1",
+                "summary": "Get the Prometheus Metrics",
+                "parameters": [],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "content": {
+                            "text/plain": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/PrometheusExporterMetricsResponse"
+                                }
+                            }
+                        }
+                    }
+                }
+            }
         }
     }
 }
@@ -33,18 +33,22 @@ import { Logger, LoggerProvider, Servers } from "@hyperledger/cactus-common";
 import { ICactusApiServerOptions } from "./config/config-service";
 import OAS from "../json/openapi.json";
 import { OpenAPIV3 } from "express-openapi-validator/dist/framework/types";
+
+import { PrometheusExporter } from "./prometheus-exporter/prometheus-exporter";
 export interface IApiServerConstructorOptions {
   pluginRegistry?: PluginRegistry;
   httpServerApi?: Server | SecureServer;
   httpServerCockpit?: Server | SecureServer;
   config: ICactusApiServerOptions;
+  prometheusExporter?: PrometheusExporter;
 }
 
 export class ApiServer {
   private readonly log: Logger;
   private pluginRegistry: PluginRegistry | undefined;
   private readonly httpServerApi: Server | SecureServer;
   private readonly httpServerCockpit: Server | SecureServer;
+  public prometheusExporter: PrometheusExporter;
 
   constructor(public readonly options: IApiServerConstructorOptions) {
     if (!options) {
@@ -78,12 +82,36 @@ export class ApiServer {
       this.httpServerCockpit = createServer();
     }
 
+    if (this.options.prometheusExporter) {
+      this.prometheusExporter = this.options.prometheusExporter;
+    } else {
+      this.prometheusExporter = new PrometheusExporter({
+        pollingIntervalInMin: 1,
+      });
+    }
+    this.prometheusExporter.setTotalPluginImports(this.getPluginImportsCount());
+
     this.log = LoggerProvider.getOrCreate({
       label: "api-server",
       level: options.config.logLevel,
     });
   }
 
+  public getPrometheusExporter(): PrometheusExporter {
+    return this.prometheusExporter;
+  }
+
+  public async getPrometheusExporterMetrics(): Promise<string> {
+    this.prometheusExporter.setTotalPluginImports(this.getPluginImportsCount());
+    const res: string = await this.prometheusExporter.getPrometheusMetrics();
+    this.log.debug(`getPrometheusExporterMetrics() response: %o`, res);
+    return res;
+  }
+
+  public getPluginImportsCount(): number {
+    return this.pluginRegistry?.plugins.length || 0;
+  }
+
   async start(): Promise<any> {
     this.checkNodeVersion();
     const tlsMaxVersion = this.options.config.tlsDefaultMaxVersion;
@@ -159,6 +187,9 @@ export class ApiServer {
         this.pluginRegistry = this.options.pluginRegistry;
       }
     }
+    await this.prometheusExporter.setTotalPluginImports(
+      await this.getPluginImportsCount(),
+    );
     return this.pluginRegistry;
   }
 
@@ -312,6 +343,28 @@ export class ApiServer {
     const { path: httpPath, verbLowerCase: httpVerb } = http;
     (app as any)[httpVerb](httpPath, healthcheckHandler);
 
+    const prometheusExporterHandler = (req: Request, res: Response) => {
+      this.getPrometheusExporterMetrics().then((resBody) => {
+        res.status(200);
+        res.send(resBody);
+      });
+    };
+
+    const {
+      "/api/v1/api-server/get-prometheus-exporter-metrics": oasPathPrometheus,
+    } = OAS.paths;
+    const { http: httpPrometheus } = oasPathPrometheus.get[
+      "x-hyperledger-cactus"
+    ];
+    const {
+      path: httpPathPrometheus,
+      verbLowerCase: httpVerbPrometheus,
+    } = httpPrometheus;
+    (app as any)[httpVerbPrometheus](
+      httpPathPrometheus,
+      prometheusExporterHandler,
+    );
+
     const registry = await this.getOrInitPluginRegistry();
 
     this.log.info(`Starting to install web services...`);

@@ -108,6 +108,42 @@ export const DefaultApiAxiosParamCreator = function (configuration?: Configurati
 
 
 
+            const query = new URLSearchParams(localVarUrlObj.search);
+            for (const key in localVarQueryParameter) {
+                query.set(key, localVarQueryParameter[key]);
+            }
+            for (const key in options.query) {
+                query.set(key, options.query[key]);
+            }
+            localVarUrlObj.search = (new URLSearchParams(query)).toString();
+            let headersFromBaseOptions = baseOptions && baseOptions.headers ? baseOptions.headers : {};
+            localVarRequestOptions.headers = {...localVarHeaderParameter, ...headersFromBaseOptions, ...options.headers};
+
+            return {
+                url: localVarUrlObj.pathname + localVarUrlObj.search + localVarUrlObj.hash,
+                options: localVarRequestOptions,
+            };
+        },
+        /**
+         * 
+         * @summary Get the Prometheus Metrics
+         * @param {*} [options] Override http request option.
+         * @throws {RequiredError}
+         */
+        getPrometheusExporterMetricsV1: async (options: any = {}): Promise<RequestArgs> => {
+            const localVarPath = `/api/v1/api-server/get-prometheus-exporter-metrics`;
+            // use dummy base URL string because the URL constructor only accepts absolute URLs.
+            const localVarUrlObj = new URL(localVarPath, 'https://example.com');
+            let baseOptions;
+            if (configuration) {
+                baseOptions = configuration.baseOptions;
+            }
+            const localVarRequestOptions = { method: 'GET', ...baseOptions, ...options};
+            const localVarHeaderParameter = {} as any;
+            const localVarQueryParameter = {} as any;
+
+
+
             const query = new URLSearchParams(localVarUrlObj.search);
             for (const key in localVarQueryParameter) {
                 query.set(key, localVarQueryParameter[key]);
@@ -146,6 +182,19 @@ export const DefaultApiFp = function(configuration?: Configuration) {
                 return axios.request(axiosRequestArgs);
             };
         },
+        /**
+         * 
+         * @summary Get the Prometheus Metrics
+         * @param {*} [options] Override http request option.
+         * @throws {RequiredError}
+         */
+        async getPrometheusExporterMetricsV1(options?: any): Promise<(axios?: AxiosInstance, basePath?: string) => AxiosPromise<string>> {
+            const localVarAxiosArgs = await DefaultApiAxiosParamCreator(configuration).getPrometheusExporterMetricsV1(options);
+            return (axios: AxiosInstance = globalAxios, basePath: string = BASE_PATH) => {
+                const axiosRequestArgs = {...localVarAxiosArgs.options, url: basePath + localVarAxiosArgs.url};
+                return axios.request(axiosRequestArgs);
+            };
+        },
     }
 };
 
@@ -164,6 +213,15 @@ export const DefaultApiFactory = function (configuration?: Configuration, basePa
         getHealthCheck(options?: any): AxiosPromise<HealthCheckResponse> {
             return DefaultApiFp(configuration).getHealthCheck(options).then((request) => request(axios, basePath));
         },
+        /**
+         * 
+         * @summary Get the Prometheus Metrics
+         * @param {*} [options] Override http request option.
+         * @throws {RequiredError}
+         */
+        getPrometheusExporterMetricsV1(options?: any): AxiosPromise<string> {
+            return DefaultApiFp(configuration).getPrometheusExporterMetricsV1(options).then((request) => request(axios, basePath));
+        },
     };
 };
 
@@ -184,6 +242,17 @@ export class DefaultApi extends BaseAPI {
     public getHealthCheck(options?: any) {
         return DefaultApiFp(this.configuration).getHealthCheck(options).then((request) => request(this.axios, this.basePath));
     }
+
+    /**
+     * 
+     * @summary Get the Prometheus Metrics
+     * @param {*} [options] Override http request option.
+     * @throws {RequiredError}
+     * @memberof DefaultApi
+     */
+    public getPrometheusExporterMetricsV1(options?: any) {
+        return DefaultApiFp(this.configuration).getPrometheusExporterMetricsV1(options).then((request) => request(this.axios, this.basePath));
+    }
 }
 
 
@@ -0,0 +1,12 @@
+import { TotalPluginImports } from "./response.type";
+
+import {
+  totalTxCount,
+  K_CACTUS_API_SERVER_TOTAL_PLUGIN_IMPORTS,
+} from "./metrics";
+
+export async function collectMetrics(totalPluginImports: TotalPluginImports) {
+  totalTxCount
+    .labels(K_CACTUS_API_SERVER_TOTAL_PLUGIN_IMPORTS)
+    .set(totalPluginImports.counter);
+}
@@ -0,0 +1,10 @@
+import { Gauge } from "prom-client";
+
+export const K_CACTUS_API_SERVER_TOTAL_PLUGIN_IMPORTS =
+  "cactus_api_server_total_plugin_imports";
+
+export const totalTxCount = new Gauge({
+  name: K_CACTUS_API_SERVER_TOTAL_PLUGIN_IMPORTS,
+  help: "Total number of plugins imported",
+  labelNames: ["type"],
+});