@oas-tools/oas-telemetry 0.4.0 → 0.5.0

package/README.md

@@ -1,133 +1,151 @@
-# OAS TELEMETRY
-
-OAS Telemetry offers an express middleware designed for collecting telemetry data using Open Telemetry in applications built using the OpenAPI Specification (OAS). This middleware allows developers to easily incorporate telemetry functionality into their APIs.
-
-OAS Telemetry provides a set of endpoints that can be accessed to perform various actions related to telemetry data, such as starting and stopping data collection, resetting telemetry data, listing collected data, and searching for specific telemetry records. These endpoints can be easily integrated into an Express.js application, providing developers with a convenient way to manage and analyze telemetry data.
-
-Additionally, OAS Telemetry offers customization options, allowing developers to configure the telemetry middleware according to their specific requirements.
-
-Overall, OAS Telemetry will serve as a valuable tool for developers looking to gain insights into the operation and performance of their OAS-based APIs, enabling them to monitor, debug, and optimize their applications effectively.
-
-
-
-
-
-## Usage
-To use the middelware add this two lines in your index.js (ESM):
-```js
-import oasTelemetry from 'oas-telemetry';
-import {readFileSync} from 'fs';
-
-app.use(oasTelemetry({
-    spec : readFileSync('./spec/oas.yaml',{ encoding: 'utf8', flag: 'r' })
-}))
-
-```
-
-## Custom Configuration
-
-You can also customize the telemetry configuration by passing options to the middleware function. For example:
-```js
-const customTelemetryConfig = {
-    exporter: myCustomExporter,
-    spec: /* OAS content in json or yaml */
-};
-
-app.use(oasTelemetry(customTelemetryConfig));
-```
-
-## Telemetry UI
-
-You can access the telemetry UI in the endpoint ``/telemetry``
-
-
-## API Telemetry Endpoints
-
-OAS Telemetry middleware adds the following endpoints to your Express application:
-
-
-- /telemetry/start: Start telemetry data collection.
-- /telemetry/stop: Stop telemetry data collection.
-- /telemetry/status: Get status of telemetry.
-- /telemetry/reset: Reset telemetry data.
-- /telemetry/list: List all telemetry data.
-- /telemetry/find (POST): Search telemetry data.
-- /telemetry/heapStats: Shows v8 heapStats.
-
-
-## Simple Example [ES Module](https://nodejs.org/docs/latest/api/esm.html) (*.mjs)
-```js index.mjs
-import oasTelemetry from '@oas-tools/oas-telemetry';
-import express from 'express';
-
-const app = express();
-const port = 3000;
-
-const spec = { "paths": {
-                    "/api/v1/pets": {
-                        "get": {
-                            "summary": "Get pets",
-                            "responses":{
-                                "200": {
-                                    "description": "Success"
-                                }
-                            }
-                        }
-                    }
-                }
-            }
-
-app.use(oasTelemetry({
-    spec : JSON.stringify(spec)
-}))
-
-app.use(express.json());
-
-app.get("/api/v1/pets", (req, res) => {
-    res.send([{ name: "rocky"},{ name: "pikachu"}]);
-});
-
-app.listen(port, () => {
-    console.log(`Example app listening at http://localhost:${port}`);
-    console.log(`Telemetry portal available at http://localhost:${port}/telemetry`);
-});
-```
-
-## Simple Example [Common.js Module](https://nodejs.org/docs/latest/api/modules.html) (*.cjs)
-```js index.cjs
-let oasTelemetry = require('@oas-tools/oas-telemetry');
-let express = require('express');
-
-const app = express();
-const port = 3000;
-
-const spec = { "paths": {
-                    "/api/v1/pets": {
-                        "get": {
-                            "summary": "Get pets",
-                            "responses":{
-                                "200": {
-                                    "description": "Success"
-                                }
-                            }
-                        }
-                    }
-                }
-            }
-
-app.use(oasTelemetry({
-    spec : JSON.stringify(spec)
-}))
-
-app.use(express.json());
-
-app.get("/api/v1/pets", (req, res) => {
-    res.send([{ name: "rocky"},{ name: "pikachu"}]);
-});
-
-app.listen(port, () => {
-    console.log(`Example app listening at http://localhost:${port}`);
-    console.log(`Telemetry portal available at http://localhost:${port}/telemetry`);
-});
-```
-
+# OAS TELEMETRY
+
+OAS Telemetry offers an express middleware designed for collecting telemetry data using Open Telemetry in applications built using the OpenAPI Specification (OAS). This middleware allows developers to easily incorporate telemetry functionality into their APIs.
+
+OAS Telemetry provides a set of endpoints that can be accessed to perform various actions related to telemetry data, such as starting and stopping data collection, resetting telemetry data, listing collected data, and searching for specific telemetry records. These endpoints can be easily integrated into an Express.js application, providing developers with a convenient way to manage and analyze telemetry data.
+
+Additionally, OAS Telemetry offers customization options, allowing developers to configure the telemetry middleware according to their specific requirements.
+
+Overall, OAS Telemetry will serve as a valuable tool for developers looking to gain insights into the operation and performance of their OAS-based APIs, enabling them to monitor, debug, and optimize their applications effectively.
+
+The package now supports both ES Module (ESM) and CommonJS (CJS) formats, making it compatible with a wide range of applications. Furthermore, OAS Telemetry provides a range of plugins to extend its functionality, enabling developers to tailor telemetry data collection, alerting, and reporting to meet specific requirements. See the [Telemetry Plugins](#telemetry-plugins) section for more information.
+
+
+
+
+
+## Usage
+To use the middelware add this two lines in your index.js (ESM):
+```js
+import oasTelemetry from 'oas-telemetry';
+import {readFileSync} from 'fs';
+
+app.use(oasTelemetry({
+    spec : readFileSync('./spec/oas.yaml',{ encoding: 'utf8', flag: 'r' })
+}))
+
+```
+
+## Custom Configuration
+
+You can also customize the telemetry configuration by passing options to the middleware function. For example:
+```js
+const customTelemetryConfig = {
+    exporter: myCustomExporter,
+    spec: /* OAS content in json or yaml */
+};
+
+app.use(oasTelemetry(customTelemetryConfig));
+```
+
+## Telemetry UI
+
+You can access the telemetry UI in the endpoint ``/telemetry``
+
+
+## API Telemetry Endpoints
+
+OAS Telemetry middleware adds the following endpoints to your Express application:
+
+
+- /telemetry/start: Start telemetry data collection.
+- /telemetry/stop: Stop telemetry data collection.
+- /telemetry/status: Get status of telemetry.
+- /telemetry/reset: Reset telemetry data.
+- /telemetry/list: List all telemetry data.
+- /telemetry/find (POST): Search telemetry data.
+- /telemetry/heapStats: Shows v8 heapStats.
+
+- /telemetry/plugins: List all plugins.
+- /telemetry/plugins (POST): Add a plugin.
+
+
+## Simple Example [ES Module](https://nodejs.org/docs/latest/api/esm.html) (*.mjs)
+```js index.mjs
+import oasTelemetry from '@oas-tools/oas-telemetry';
+import express from 'express';
+
+const app = express();
+const port = 3000;
+
+const spec = { "paths": {
+                    "/api/v1/pets": {
+                        "get": {
+                            "summary": "Get pets",
+                            "responses":{
+                                "200": {
+                                    "description": "Success"
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+
+app.use(oasTelemetry({
+    spec : JSON.stringify(spec)
+}))
+
+app.use(express.json());
+
+app.get("/api/v1/pets", (req, res) => {
+    res.send([{ name: "rocky"},{ name: "pikachu"}]);
+});
+
+app.listen(port, () => {
+    console.log(`Example app listening at http://localhost:${port}`);
+    console.log(`Telemetry portal available at http://localhost:${port}/telemetry`);
+});
+```
+
+## Simple Example [Common.js Module](https://nodejs.org/docs/latest/api/modules.html) (*.cjs)
+```js index.cjs
+let oasTelemetry = require('@oas-tools/oas-telemetry');
+let express = require('express');
+
+const app = express();
+const port = 3000;
+
+const spec = { "paths": {
+                    "/api/v1/pets": {
+                        "get": {
+                            "summary": "Get pets",
+                            "responses":{
+                                "200": {
+                                    "description": "Success"
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+
+app.use(oasTelemetry({
+    spec : JSON.stringify(spec)
+}))
+
+app.use(express.json());
+
+app.get("/api/v1/pets", (req, res) => {
+    res.send([{ name: "rocky"},{ name: "pikachu"}]);
+});
+
+app.listen(port, () => {
+    console.log(`Example app listening at http://localhost:${port}`);
+    console.log(`Telemetry portal available at http://localhost:${port}/telemetry`);
+});
+```
+
+## Telemetry Plugins
+
+OAS Telemetry supports a range of plugins to extend its functionality, allowing developers to tailor telemetry data collection, alerting, and reporting to meet specific requirements. Plugins enable additional features, such as integration with alerting systems, custom data exporters, and data visualization tools.
+
+One example plugin is the **Outlier Alert Over Messaging** plugin, which can be configured to send anomaly alerts to messaging platforms like Telegram. This plugin is especially useful for monitoring abnormal response times in your API, notifying selected channels to allow rapid responses to potential issues. For setup details, refer to its [README documentation](https://github.com/oas-tools/oas-telemetry-plugin-outlier-messaging/blob/main/README.md).
+
+OAS Telemetry plugins are flexible and support both ES Modules (ESM) and CommonJS (CJS) formats, regardless of whether your application is using ESM or CJS. This compatibility ensures that plugins work seamlessly in all configurations:
+- ESM applications can use plugins in either ESM or CJS format.
+- CJS applications can use plugins in either CJS or ESM format.
+
+This flexibility makes it easy to incorporate a wide variety of plugins in your preferred module system.
+
+

package/dist/client.cjs

@@ -0,0 +1,14 @@
+"use strict";
+
+// client.js
+
+function sendRequest(url, options = {}) {
+  const apiKey = localStorage.getItem('apiKey');
+  if (!options.headers) {
+    options.headers = {};
+  }
+  options.headers['x-api-key'] = apiKey;
+  return fetch(url, options);
+}
+
+// ...existing code...

package/dist/config.cjs

@@ -0,0 +1,27 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.globalOasTlmConfig = exports.default = void 0;
+var _dynamicExporter = _interopRequireDefault(require("./exporters/dynamicExporter.cjs"));
+function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
+//Environment variables
+//OASTLM_API_KEY = 'oas-telemetry-api-key' //Cookie value for the API key
+//OASTLM_MODULE_DISABLED = 'true' //Disables the module (empty middleware and no tracing)
+
+const globalOasTlmConfig = exports.globalOasTlmConfig = {
+  dynamicExporter: new _dynamicExporter.default(),
+  baseURL: "/telemetry4",
+  spec: null,
+  specFileName: "",
+  autoActivate: true,
+  apiKeyMaxAge: 1000 * 60 * 60,
+  // 1 hour
+  password: "oas-telemetry-password",
+  jwtSecret: "oas-telemetry-secret"
+};
+//5 name alternatives. one for globals 
+var _default = exports.default = {
+  globalOasTlmConfig
+};

package/dist/controllers/pluginController.cjs

@@ -0,0 +1,118 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.registerPlugin = exports.listPlugins = exports.checkApiKey = void 0;
+var _config = require("../config.cjs");
+var _axios = _interopRequireDefault(require("axios"));
+var _importFromString = require("import-from-string");
+var _dynamicInstaller = require("dynamic-installer");
+function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
+let dbglog = () => {};
+if (process.env.OTDEBUG == "true") dbglog = console.log;
+const listPlugins = (req, res) => {
+  res.send(_config.globalOasTlmConfig.dynamicExporter.getPlugins().map(p => {
+    return {
+      id: p.id,
+      name: p.name,
+      url: p.url,
+      active: p.active
+    };
+  }));
+};
+exports.listPlugins = listPlugins;
+const registerPlugin = async (req, res) => {
+  let pluginResource = req.body;
+  dbglog(`Plugin Registration Request: = ${JSON.stringify(req.body, null, 2)}...`);
+  dbglog(`Getting plugin at ${pluginResource.url}...`);
+  let pluginCode;
+  if (!pluginResource.url && !pluginResource.code) {
+    res.status(400).send(`Plugin code or URL must be provided`);
+    return;
+  }
+  let module;
+  try {
+    if (pluginResource.code) {
+      pluginCode = pluginResource.code;
+    } else {
+      const response = await _axios.default.get(pluginResource.url);
+      pluginCode = response.data;
+    }
+    if (!pluginCode) {
+      res.status(400).send(`Plugin code could not be loaded`);
+      return;
+    }
+    if (pluginResource.install) {
+      const dependenciesStatus = await (0, _dynamicInstaller.installDependencies)(pluginResource.install);
+      if (!dependenciesStatus.success) {
+        if (pluginResource.install.ignoreErrors === true) {
+          console.warn(`Warning: Error installing dependencies: ${JSON.stringify(dependenciesStatus.details)}`);
+        } else {
+          res.status(400).send(`Error installing dependencies: ${JSON.stringify(dependenciesStatus.details)}`);
+          return;
+        }
+      }
+    }
+    dbglog("Plugin size: " + pluginCode?.length);
+    dbglog("Plugin format: " + pluginResource?.moduleFormat);
+    if (pluginResource?.moduleFormat && pluginResource.moduleFormat.toUpperCase() == "ESM") {
+      console.log("ESM detected");
+      module = await (0, _importFromString.importFromString)(pluginCode);
+    } else {
+      console.log("CJS detected (default)");
+      module = await (0, _importFromString.requireFromString)(pluginCode);
+      console.log(module);
+    }
+  } catch (error) {
+    console.error(`Error loading plugin: ${error}`);
+    res.status(400).send(`Error loading plugin: ${error}`);
+    return;
+  }
+  const plugin = module.default?.plugin ?? module.plugin;
+  if (plugin == undefined) {
+    res.status(400).send(`Plugin code should export a "plugin" object`);
+    console.log("Error in plugin code: no plugin object exported");
+    return;
+  }
+  for (let requiredFunction of ["load", "getName", "isConfigured"]) {
+    if (plugin[requiredFunction] == undefined) {
+      res.status(400).send(`The plugin code exports a "plugin" object, however it should have a "${requiredFunction}" method`);
+      console.log("Error in plugin code: some required functions are missing");
+      return;
+    }
+  }
+  try {
+    await plugin.load(pluginResource.config);
+  } catch (error) {
+    console.error(`Error loading plugin configuration: ${error}`);
+    res.status(400).send(`Error loading plugin configuration: ${error}`);
+    return;
+  }
+  if (plugin.isConfigured()) {
+    dbglog(`Loaded plugin <${plugin.getName()}>`);
+    pluginResource.plugin = plugin;
+    pluginResource.name = plugin.getName();
+    pluginResource.active = true;
+    _config.globalOasTlmConfig.dynamicExporter.pushPlugin(pluginResource);
+    _config.globalOasTlmConfig.dynamicExporter.activatePlugin(pluginResource.plugin);
+    res.status(201).send(`Plugin registered`);
+  } else {
+    console.error(`Plugin <${plugin.getName()}> can not be configured`);
+    res.status(400).send(`Plugin configuration problem`);
+  }
+};
+exports.registerPlugin = registerPlugin;
+const checkApiKey = (req, res) => {
+  const apiKey = req.query.apiKey || req.body.apiKey;
+  if (apiKey === process.env.APIKEY) {
+    res.status(200).send({
+      valid: true
+    });
+  } else {
+    res.status(401).send({
+      valid: false
+    });
+  }
+};
+exports.checkApiKey = checkApiKey;

package/dist/controllers/telemetryController.cjs

@@ -0,0 +1,92 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.stopTelemetry = exports.statusTelemetry = exports.startTelemetry = exports.resetTelemetry = exports.listTelemetry = exports.heapStats = exports.findTelemetry = void 0;
+var _v = _interopRequireDefault(require("v8"));
+var _config = require("../config.cjs");
+function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
+const startTelemetry = (req, res) => {
+  _config.globalOasTlmConfig.dynamicExporter.exporter.start();
+  res.send('Telemetry started');
+};
+exports.startTelemetry = startTelemetry;
+const stopTelemetry = (req, res) => {
+  _config.globalOasTlmConfig.dynamicExporter.exporter.stop();
+  res.send('Telemetry stopped');
+};
+exports.stopTelemetry = stopTelemetry;
+const statusTelemetry = (req, res) => {
+  const isRunning = _config.globalOasTlmConfig.dynamicExporter.exporter.isRunning() || false;
+  res.send({
+    active: isRunning
+  });
+};
+exports.statusTelemetry = statusTelemetry;
+const resetTelemetry = (req, res) => {
+  _config.globalOasTlmConfig.dynamicExporter.exporter.reset();
+  res.send('Telemetry reset');
+};
+exports.resetTelemetry = resetTelemetry;
+const listTelemetry = async (req, res) => {
+  try {
+    const spans = await _config.globalOasTlmConfig.dynamicExporter.exporter.getFinishedSpans();
+    res.send({
+      spansCount: spans.length,
+      spans: spans
+    });
+  } catch (err) {
+    console.error(err);
+    res.status(500).send({
+      error: 'Failed to list telemetry data'
+    });
+  }
+};
+exports.listTelemetry = listTelemetry;
+const heapStats = (req, res) => {
+  var heapStats = _v.default.getHeapStatistics();
+  var roundedHeapStats = Object.getOwnPropertyNames(heapStats).reduce(function (map, stat) {
+    map[stat] = Math.round(heapStats[stat] / 1024 / 1024 * 1000) / 1000;
+    return map;
+  }, {});
+  roundedHeapStats['units'] = 'MB';
+  res.send(roundedHeapStats);
+};
+exports.heapStats = heapStats;
+const findTelemetry = (req, res) => {
+  const body = req.body;
+  const search = body?.search ? body.search : {};
+  if (body?.flags?.containsRegex) {
+    try {
+      body.config?.regexIds?.forEach(regexId => {
+        if (search[regexId]) search[regexId] = new RegExp(search[regexId]);
+      });
+    } catch (e) {
+      console.error(e);
+      res.status(404).send({
+        spansCount: 0,
+        spans: [],
+        error: e
+      });
+      return;
+    }
+    _config.globalOasTlmConfig.dynamicExporter.exporter.find(search, (err, docs) => {
+      if (err) {
+        console.error(err);
+        res.status(404).send({
+          spansCount: 0,
+          spans: [],
+          error: err
+        });
+        return;
+      }
+      const spans = docs;
+      res.send({
+        spansCount: spans.length,
+        spans: spans
+      });
+    });
+  }
+};
+exports.findTelemetry = findTelemetry;

package/dist/controllers/uiController.cjs

@@ -0,0 +1,78 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.specLoader = exports.mainPage = exports.detailPage = exports.apiPage = void 0;
+var _config = require("../config.cjs");
+var _fs = require("fs");
+var _path = _interopRequireDefault(require("path"));
+var _jsYaml = _interopRequireDefault(require("js-yaml"));
+var _uiService = _interopRequireDefault(require("../services/uiService.cjs"));
+function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
+const apiPage = (req, res) => {
+  const baseURL = _config.globalOasTlmConfig.baseURL;
+  let text = `
+    <h1>Telemetry API routes:</h1>
+    <ul>
+        <li><a href="${baseURL}/start">${baseURL}/start</a></li>
+        <li><a href="${baseURL}/stop">${baseURL}/stop</a></li>
+        <li><a href="${baseURL}/status">${baseURL}/status</a></li>
+        <li><a href="${baseURL}/reset">${baseURL}/reset</a></li>
+        <li><a href="${baseURL}/list">${baseURL}/list</a></li>
+        <li><a href="${baseURL}/heapStats">${baseURL}/heapStats</a></li>
+        <li>${baseURL}/find [POST]</li>
+    </ul>
+    `;
+  res.send(text);
+};
+exports.apiPage = apiPage;
+const mainPage = (req, res) => {
+  const baseURL = _config.globalOasTlmConfig.baseURL;
+  res.set('Content-Type', 'text/html');
+  res.send((0, _uiService.default)(baseURL).main);
+};
+exports.mainPage = mainPage;
+const detailPage = (req, res) => {
+  const baseURL = _config.globalOasTlmConfig.baseURL;
+  res.set('Content-Type', 'text/html');
+  res.send((0, _uiService.default)(baseURL).detail);
+};
+exports.detailPage = detailPage;
+const specLoader = (req, res) => {
+  if (_config.globalOasTlmConfig.specFileName) {
+    try {
+      const data = (0, _fs.readFileSync)(_config.globalOasTlmConfig.specFileName, {
+        encoding: 'utf8',
+        flag: 'r'
+      });
+      const extension = _path.default.extname(_config.globalOasTlmConfig.specFileName);
+      let json = data;
+      if (extension == _jsYaml.default) json = JSON.stringify(_jsYaml.default.SafeLoad(data), null, 2);
+      res.setHeader('Content-Type', 'application/json');
+      res.send(json);
+    } catch (e) {
+      console.error(`ERROR loading spec file ${_config.globalOasTlmConfig.specFileName}: ${e}`);
+    }
+  } else if (_config.globalOasTlmConfig.spec) {
+    let spec = false;
+    try {
+      spec = JSON.parse(_config.globalOasTlmConfig.spec);
+    } catch (ej) {
+      try {
+        spec = JSON.stringify(_jsYaml.default.load(_config.globalOasTlmConfig.spec), null, 2);
+      } catch (ey) {
+        console.error(`Error parsing spec: ${ej} - ${ey}`);
+      }
+    }
+    if (!spec) {
+      res.status(404);
+    } else {
+      res.setHeader('Content-Type', 'application/json');
+      res.send(spec);
+    }
+  } else {
+    res.status(404);
+  }
+};
+exports.specLoader = specLoader;