@oas-tools/oas-telemetry 0.2.0 → 0.2.2

package/README.md

@@ -1,133 +1,133 @@
-# 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.
+
+
+
+
+
+## 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`);
+});
+```
+

package/dist/exporters/InMemoryDbExporter.cjs

@@ -7,21 +7,36 @@ exports.InMemoryExporter = void 0;
 var _core = require("@opentelemetry/core");
 var _nedb = _interopRequireDefault(require("nedb"));
 function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
+function _defineProperty(obj, key, value) { key = _toPropertyKey(key); if (key in obj) { Object.defineProperty(obj, key, { value: value, enumerable: true, configurable: true, writable: true }); } else { obj[key] = value; } return obj; }
+function _toPropertyKey(t) { var i = _toPrimitive(t, "string"); return "symbol" == typeof i ? i : i + ""; }
+function _toPrimitive(t, r) { if ("object" != typeof t || !t) return t; var e = t[Symbol.toPrimitive]; if (void 0 !== e) { var i = e.call(t, r || "default"); if ("object" != typeof i) return i; throw new TypeError("@@toPrimitive must return a primitive value."); } return ("string" === r ? String : Number)(t); }
+let dbglog = () => {};
+if (process.env.OTDEBUG == "true") dbglog = console.log;
+
 //import in memory database
 
 class InMemoryExporter {
   constructor() {
     this._spans = new _nedb.default();
-    this._stopped = false;
+    this._stopped = true;
   }
   export(readableSpans, resultCallback) {
     try {
       if (!this._stopped) {
-        // Remove circular references
-        const cleanSpans = readableSpans.map(span => removeCircular(span));
+        // Prepare spans to be inserted into the in-memory database (remove circular references and convert to nested objects)
+        const cleanSpans = readableSpans.map(nestedSpan => removeCircularRefs(nestedSpan)) // to avoid JSON parsing error
+        .map(span => applyNesting(span)) // to avoid dot notation in keys (neDB does not support dot notation in keys)
+        .filter(span => !span.attributes?.http?.target?.includes("/telemetry")); // to avoid telemetry spans
 
         // Insert spans into the in-memory database
         this._spans.insert(cleanSpans, (err, newDoc) => {
+          InMemoryExporter.plugins.forEach((p, i) => {
+            cleanSpans.forEach(t => {
+              dbglog(`Sending trace <${t._id}> to plugin (Plugin #${i}) <${p.name}>`);
+              dbglog(`Trace: \n<${JSON.stringify(t, null, 2)}`);
+              p.newTrace(t);
+            });
+          });
           if (err) {
             console.error(err);
             return;
@@ -50,8 +65,8 @@ class InMemoryExporter {
     this._spans = new _nedb.default();
     return this.forceFlush();
   }
-  /**
-   * Exports any pending spans in the exporter
+  /**
+   * Exports any pending spans in the exporter
    */
   forceFlush() {
     return Promise.resolve();
@@ -62,9 +77,15 @@ class InMemoryExporter {
   getFinishedSpans() {
     return this._spans;
   }
+  activatePlugin(plugin) {
+    dbglog(`Activating plugin <${plugin.getName()}>...`);
+    InMemoryExporter.plugins.push(plugin);
+    dbglog(`Plugin <${plugin.getName()}> active (Total active plugins: ${InMemoryExporter.plugins.length})`);
+  }
 }
 exports.InMemoryExporter = InMemoryExporter;
-function removeCircular(obj) {
+_defineProperty(InMemoryExporter, "plugins", []);
+function removeCircularRefs(obj) {
   const seen = new WeakMap(); // Used to keep track of visited objects
 
   // Replacer function to handle circular references
@@ -86,10 +107,68 @@ function removeCircular(obj) {
   // Convert the object to a string and then parse it back
   // This will trigger the replacer function to handle circular references
   const jsonString = JSON.stringify(obj, replacer);
-  const spanNoDotsInKeys = jsonString.replace(/[^"]*":/g, match => {
-    // Replace all dots in the key with underscores (e.g. "http.method" -> "http_method")
-    const newMatch = match.replace(/\./g, "_dot_");
-    return newMatch;
-  });
-  return JSON.parse(spanNoDotsInKeys);
+  return JSON.parse(jsonString);
+}
+
+/**
+ * Recursively converts dot-separated keys in an object to nested objects.
+ * 
+ * @param {Object} obj - The object to process.
+ * @returns {Object} - The object with all dot-separated keys converted to nested objects.
+ * @example
+ * // Input:
+ * // {
+ * //   "http.method": "GET",
+ * //   "http.url": "http://example.com",
+ * //   "nested.obj.key": "value"
+ * // }
+ * // Output:
+ * // {
+ * //   "http": {
+ * //     "method": "GET",
+ * //     "url": "http://example.com"
+ * //   },
+ * //   "nested": {
+ * //     "obj": {
+ * //       "key": "value"
+ * //     }
+ * //   }
+ * // }
+ */
+function convertToNestedObject(obj) {
+  const result = {};
+  for (const key in obj) {
+    const keys = key.split('.');
+    let temp = result;
+    for (let i = 0; i < keys.length; i++) {
+      const currentKey = keys[i];
+      if (i === keys.length - 1) {
+        // Last key, set the value
+        temp[currentKey] = obj[key];
+      } else {
+        // Intermediate key, ensure the object exists
+        if (!temp[currentKey]) {
+          temp[currentKey] = {};
+        }
+        temp = temp[currentKey];
+      }
+    }
+  }
+  return result;
+}
+
+/**
+ * Applies nesting to all dot-separated keys within an object.
+ * 
+ * @param {Object} obj - The object to apply nesting to.
+ * @returns {Object} - The transformed object with nested structures.
+ */
+function applyNesting(obj) {
+  // Recursively apply convertToNestedObject to each level of the object
+  for (const key in obj) {
+    if (typeof obj[key] === 'object' && obj[key] !== null) {
+      obj[key] = applyNesting(obj[key]);
+    }
+  }
+  return convertToNestedObject(obj);
 }

package/dist/index.cjs

@@ -10,11 +10,14 @@ var _v = _interopRequireDefault(require("v8"));
 var _fs = require("fs");
 var _path = _interopRequireDefault(require("path"));
 var _jsYaml = _interopRequireDefault(require("js-yaml"));
-var _url = require("url");
 var _ui = _interopRequireDefault(require("./ui.cjs"));
+var _axios = _interopRequireDefault(require("axios"));
 function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
 // telemetryMiddleware.js
 
+let dbglog = () => {};
+if (process.env.OTDEBUG == "true") dbglog = console.log;
+let plugins = [];
 let telemetryStatus = {
   active: true
 };
@@ -25,19 +28,18 @@ let telemetryConfig = {
 };
 function oasTelemetry(tlConfig) {
   if (tlConfig) {
-    console.log('Telemetry config provided');
+    dbglog('Telemetry config provided');
     telemetryConfig = tlConfig;
     if (telemetryConfig.exporter == undefined) telemetryConfig.exporter = _telemetry.inMemoryExporter;
   }
-  if (telemetryConfig.spec) console.log(`Spec content provided`);else {
-    if (telemetryConfig.specFileName != "") console.log(`Spec file used for telemetry: ${telemetryConfig.specFileName}`);else {
-      console.log("No spec available !");
+  if (telemetryConfig.spec) dbglog(`Spec content provided`);else {
+    if (telemetryConfig.specFileName != "") dbglog(`Spec file used for telemetry: ${telemetryConfig.specFileName}`);else {
+      console.error("No spec available !");
     }
   }
   const router = (0, _express.Router)();
-
-  //const baseURL = telemetryConfig.baseURL;
-
+  if (telemetryConfig.baseURL) baseURL = telemetryConfig.baseURL;
+  router.use((0, _express.json)());
   router.get(baseURL, mainPage);
   router.get(baseURL + "/detail/*", detailPage);
   router.get(baseURL + "/spec", specLoader);
@@ -49,6 +51,8 @@ function oasTelemetry(tlConfig) {
   router.get(baseURL + "/list", listTelemetry);
   router.post(baseURL + "/find", findTelemetry);
   router.get(baseURL + "/heapStats", heapStats);
+  router.get(baseURL + "/plugins", listPlugins);
+  router.post(baseURL + "/plugins", registerPlugin);
   return router;
 }
 const apiPage = (req, res) => {
@@ -87,7 +91,7 @@ const specLoader = (req, res) => {
       res.setHeader('Content-Type', 'application/json');
       res.send(json);
     } catch (e) {
-      console.log(`ERROR loading spec file ${telemetryConfig.specFileName}: ${e}`);
+      console.error(`ERROR loading spec file ${telemetryConfig.specFileName}: ${e}`);
     }
   } else {
     if (telemetryConfig.spec) {
@@ -98,7 +102,7 @@ const specLoader = (req, res) => {
         try {
           spec = JSON.stringify(_jsYaml.default.load(telemetryConfig.spec), null, 2);
         } catch (ey) {
-          console.log(`Error parsing spec: ${ej} - ${ey}`);
+          console.error(`Error parsing spec: ${ej} - ${ey}`);
         }
       }
       if (!spec) {
@@ -112,16 +116,17 @@ const specLoader = (req, res) => {
 };
 const startTelemetry = (req, res) => {
   telemetryConfig.exporter.start();
-  telemetryStatus.active = true;
   res.send('Telemetry started');
 };
 const stopTelemetry = (req, res) => {
   telemetryConfig.exporter.stop();
-  telemetryStatus.active = false;
   res.send('Telemetry stopped');
 };
 const statusTelemetry = (req, res) => {
-  res.send(telemetryStatus);
+  const status = !telemetryConfig.exporter._stopped || false;
+  res.send({
+    active: status
+  });
 };
 const resetTelemetry = (req, res) => {
   telemetryConfig.exporter.reset();
@@ -141,25 +146,6 @@ const listTelemetry = (req, res) => {
     });
   });
 };
-const findTelemetry = (req, res) => {
-  const spansDB = telemetryConfig.exporter.getFinishedSpans();
-  const search = req.body;
-  spansDB.find(search, (err, docs) => {
-    if (err) {
-      console.error(err);
-      res.send({
-        spansCount: "error",
-        spans: []
-      });
-      return;
-    }
-    const spans = docs;
-    res.send({
-      spansCount: spans.length,
-      spans: spans
-    });
-  });
-};
 const heapStats = (req, res) => {
   var heapStats = _v.default.getHeapStatistics();
 
@@ -171,4 +157,74 @@ const heapStats = (req, res) => {
   roundedHeapStats['units'] = 'MB';
   res.send(roundedHeapStats);
 };
+const findTelemetry = (req, res) => {
+  const spansDB = telemetryConfig.exporter.getFinishedSpans();
+  const body = req.body;
+  const search = body?.search ? body.search : {};
+  if (body?.flags?.containsRegex) {
+    try {
+      body.config?.regexIds?.forEach(regexId => {
+        search[regexId] = new RegExp(search[regexId]);
+      });
+    } catch (e) {
+      console.error(e);
+      res.status(404).send({
+        spansCount: 0,
+        spans: [],
+        error: e
+      });
+      return;
+    }
+    spansDB.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
+      });
+    });
+  }
+};
+const listPlugins = (req, res) => {
+  res.send(plugins.map(p => {
+    return {
+      id: p.id,
+      url: p.url,
+      active: p.active
+    };
+  }));
+};
+const registerPlugin = (req, res) => {
+  let pluginResource = req.body;
+  dbglog(`Plugin Registration Request: = ${JSON.stringify(req.body, null, 2)}...`);
+  dbglog(`Getting plugin at ${pluginResource.url}...`);
+  _axios.default.get(pluginResource.url).then(response => {
+    dbglog(`Plugin fetched.`);
+    const pluginCode = response.data;
+    dbglog("Plugin size: " + pluginCode.length);
+    var plugin;
+    eval(pluginCode);
+    plugin.load(pluginResource.config);
+    if (plugin.isConfigured()) {
+      dbglog(`Loaded plugin <${plugin.getName()}>`);
+      pluginResource.plugin = plugin;
+      pluginResource.name = plugin.getName();
+      pluginResource.active = true;
+      plugins.push(pluginResource);
+      _telemetry.inMemoryExporter.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`);
+    }
+  }).catch(err => console.error("registerPlugin:" + err));
+};
 module.exports = exports.default;