@oas-tools/oas-telemetry 0.2.2 → 0.4.0

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

@@ -34,6 +34,7 @@ class InMemoryExporter {
             cleanSpans.forEach(t => {
               dbglog(`Sending trace <${t._id}> to plugin (Plugin #${i}) <${p.name}>`);
               dbglog(`Trace: \n<${JSON.stringify(t, null, 2)}`);
+              //TODO: This should be called newSpan instead of newTrace
               p.newTrace(t);
             });
           });
@@ -65,8 +66,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();
@@ -110,30 +111,30 @@ function removeCircularRefs(obj) {
   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"
- * //     }
- * //   }
- * // }
+/**
+ * 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 = {};
@@ -157,11 +158,11 @@ function convertToNestedObject(obj) {
   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.
+/**
+ * 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

package/dist/index.cjs

@@ -12,6 +12,8 @@ var _path = _interopRequireDefault(require("path"));
 var _jsYaml = _interopRequireDefault(require("js-yaml"));
 var _ui = _interopRequireDefault(require("./ui.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 }; }
 // telemetryMiddleware.js
 
@@ -202,29 +204,87 @@ const listPlugins = (req, res) => {
     };
   }));
 };
-const registerPlugin = (req, res) => {
+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}...`);
-  _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`);
+  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 {
-      console.error(`Plugin <${plugin.getName()}> can not be configured`);
-      res.status(400).send(`Plugin configuration problem`);
+      const response = await _axios.default.get(pluginResource.url);
+      pluginCode = response.data;
+    }
+    if (!pluginCode) {
+      res.status(400).send(`Plugin code could not be loaded`);
+      return;
     }
-  }).catch(err => console.error("registerPlugin:" + err));
+    //install dependencies if any
+    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;
+  }
+
+  // Check if the plugin is in module.default or module.plugin (supports default syntax)
+  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;
+    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`);
+  }
 };
 module.exports = exports.default;

package/dist/types/exporters/InMemoryDbExporter.d.ts

@@ -0,0 +1,16 @@
+export class InMemoryExporter {
+    static plugins: any[];
+    _spans: any;
+    _stopped: boolean;
+    export(readableSpans: any, resultCallback: any): any;
+    start(): void;
+    stop(): void;
+    shutdown(): Promise<void>;
+    /**
+     * Exports any pending spans in the exporter
+     */
+    forceFlush(): Promise<void>;
+    reset(): void;
+    getFinishedSpans(): any;
+    activatePlugin(plugin: any): void;
+}

package/dist/types/index.d.ts

@@ -0,0 +1 @@
+export default function oasTelemetry(tlConfig?: any): import("express-serve-static-core").Router;

package/dist/types/telemetry.d.ts

@@ -0,0 +1,2 @@
+export const inMemoryExporter: InMemoryExporter;
+import { InMemoryExporter } from './exporters/InMemoryDbExporter.js';

package/dist/types/ui.d.ts

@@ -0,0 +1,4 @@
+export default function ui(): {
+    main: string;
+    detail: string;
+};