@oas-tools/oas-telemetry 0.7.1 → 0.8.0-alpha.1

package/dist/esm/docs/openapi.yaml

@@ -31,8 +31,8 @@ servers:
       port:
         default: "3000"
       basePath:
-        default: telemetry
-        description: Base path for all endpoints. Can be customized, e.g. "myCustomTelemetryPath"
+        default: oas-telemetry
+        description: Base path for all endpoints. Configured via OASTLM_BOOT_BASE_URL environment variable
 
 tags:
   - name: traces
@@ -326,6 +326,44 @@ paths:
                     type: string
                     example: Invalid retention time. Must be a positive number.
 
+  /traces/export:
+    get:
+      tags:
+        - traces
+      summary: Export collected traces
+      description: Export all collected traces in line-delimited JSON format
+      responses:
+        '200':
+          description: Traces exported successfully
+          content:
+            application/json:
+              schema:
+                type: string
+
+  /traces/import:
+    post:
+      tags:
+        - traces
+      summary: Import traces
+      description: Import traces from line-delimited JSON format
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: string
+      responses:
+        '200':
+          description: Traces imported successfully
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  message:
+                    type: string
+                    example: Traces imported successfully
+
   /metrics:
     get:
       summary: Get collected metrics
@@ -548,6 +586,69 @@ paths:
                     type: string
                     example: Invalid retention time. Must be a positive number.
 
+  /metrics/export:
+    get:
+      tags:
+        - metrics
+      summary: Export collected metrics
+      description: Export all collected metrics in line-delimited JSON format
+      responses:
+        '200':
+          description: Metrics exported successfully
+          content:
+            application/json:
+              schema:
+                type: string
+
+  /metrics/import:
+    post:
+      tags:
+        - metrics
+      summary: Import metrics
+      description: Import metrics from line-delimited JSON format
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: string
+      responses:
+        '200':
+          description: Metrics imported successfully
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  message:
+                    type: string
+                    example: Metrics imported successfully
+
+  /metrics/stats:
+    get:
+      tags:
+        - metrics
+      summary: Get metrics statistics
+      description: Get statistics about collected metrics
+      responses:
+        '200':
+          description: Metrics statistics retrieved successfully
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  totalMetrics:
+                    type: number
+                    example: 42
+                  activeMetrics:
+                    type: number
+                    example: 35
+                  retentionTime:
+                    type: number
+                    description: Retention time in seconds
+                    example: 3600
+
   /logs:
     get:
       summary: Get collected logs
@@ -683,6 +784,44 @@ paths:
                     type: string
                     example: Invalid regex in query
 
+  /logs/export:
+    get:
+      tags:
+        - logs
+      summary: Export collected logs
+      description: Export all collected logs in line-delimited JSON format
+      responses:
+        '200':
+          description: Logs exported successfully
+          content:
+            application/json:
+              schema:
+                type: string
+
+  /logs/import:
+    post:
+      tags:
+        - logs
+      summary: Import logs
+      description: Import logs from line-delimited JSON format
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: string
+      responses:
+        '200':
+          description: Logs imported successfully
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  message:
+                    type: string
+                    example: Logs imported successfully
+
   /utils/spec:
     get:
       summary: Get OpenAPI spec in JSON
@@ -842,14 +981,14 @@ paths:
                     type: string
                     example: Started generating mock logs
 
-  /utils/generate-wait/{seconds}:
+  /utils/generate-wait:
     get:
       summary: Wait for the specified seconds
       tags:
         - utils
       parameters:
         - name: seconds
-          in: path
+          in: query
           required: false
           schema:
             type: integer
@@ -867,6 +1006,21 @@ paths:
                     type: number
                     example: 2
 
+  /utils/oas-telemetry-spec:
+    get:
+      summary: Get OAS-Telemetry specification
+      tags:
+        - utils
+      description: Retrieve the OpenAPI specification for OAS-Telemetry
+      responses:
+        '200':
+          description: OK
+          content:
+            application/json:
+              schema:
+                type: object
+                description: OpenAPI specification
+
   /health:
     get:
       summary: Health check

package/dist/esm/index.js

@@ -5,25 +5,26 @@ import { getConfig } from './config/config.js';
 import { Router } from 'express';
 import { configureRoutes } from './routesManager.js';
 import { configureTelemetry } from './telemetry/telemetryConfigurator.js';
+import { isTelemetryConfigured, setTelemetryRouter, getTelemetryRouter } from './telemetry/telemetryRegistry.js';
 import { bootEnvVariables } from "./config/bootConfig.js";
-// WARN: If changed the API, also change in packages/lib/src/types/cjs-index.d.ts (used for CJS compilation)
 /**
  * Returns the OAS-Telemetry middleware.
  * All parameters are optional. However, either `spec` or `specFileName` must be provided to enable endpoint filtering.
  */
-export default function oasTelemetry(oasTlmInputConfig) {
+function oasTelemetry(oasTlmInputConfig) {
+    if (isTelemetryConfigured()) {
+        return getTelemetryRouter();
+    }
     const router = Router();
-    // This environment variable cannot be set via the config object,
-    // as it is required to disable OpenTelemetry SDK initialization,
-    // which occurs during the first import at the top of this file.
     if (bootEnvVariables.OASTLM_BOOT_MODULE_DISABLED) {
+        setTelemetryRouter(router);
         return router;
     }
     const oasTlmConfig = getConfig(oasTlmInputConfig);
-    logger.info("BaseUrl: ", oasTlmConfig.general.baseUrl);
-    if (!oasTlmConfig.general.spec && !oasTlmConfig.general.specFileName)
-        logger.warn("No spec provided, endpoint filtering will not be available. Please provide either `spec` or `specFileName` in the configuration.");
+    logger.info("BaseUrl: ", bootEnvVariables.OASTLM_BOOT_BASE_URL);
     configureTelemetry(oasTlmConfig);
     configureRoutes(router, oasTlmConfig);
+    setTelemetryRouter(router);
     return router;
 }
+export { oasTelemetry };

package/dist/esm/routesManager.js

@@ -13,21 +13,17 @@ import { getAIRoutes } from "./tlm-ai/aiRoutes.js";
 import { bootEnvVariables } from "./config/bootConfig.js";
 import { getPluginRoutes } from "./tlm-plugin/pluginRoutes.js";
 export const configureRoutes = (router, oasTlmConfig) => {
+    if (!oasTlmConfig.general.spec && !oasTlmConfig.general.specFileName) {
+        logger.warn("No spec provided, endpoint filtering will not be available. Please provide either `spec` or `specFileName` in the configuration.");
+    }
     if (bootEnvVariables.OASTLM_BOOT_ENV === 'development') {
         logger.info("Running in development mode, enabling CORS for all origins");
         router.use(cors({
-            origin: (origin, callback) => {
-                if (!origin || /^http:\/\/localhost:\d+$/.test(origin)) {
-                    callback(null, true);
-                }
-                else {
-                    callback(new Error('Not allowed by CORS'));
-                }
-            },
+            origin: true,
             credentials: true
         }));
     }
-    const telemetryBaseUrl = oasTlmConfig.general.baseUrl;
+    const telemetryBaseUrl = bootEnvVariables.OASTLM_BOOT_BASE_URL;
     // Sub-router for all telemetry endpoints
     const telemetryRouter = Router();
     // Body parser for JSON requests
@@ -35,7 +31,7 @@ export const configureRoutes = (router, oasTlmConfig) => {
         if (req.body !== undefined) {
             return next(); // Already parsed, no need to parse again.
         }
-        return json({ limit: '10mb' })(req, res, next);
+        return json({ limit: '500mb' })(req, res, next);
     });
     telemetryRouter.get('/health', (_req, res) => {
         res.status(200).send({ status: 'OK' });

package/dist/esm/telemetry/custom-implementations/exporters/DiskLogExporter.js

@@ -0,0 +1,114 @@
+import { ExportResultCode, hrTimeToMicroseconds } from '@opentelemetry/core';
+import { applyNesting, removeCircularRefs } from '../utils/circular.js';
+import { Enabler } from '../wrappers.js';
+import { DiskWriter } from '../../persistence/DiskWriter.js';
+import logger from '../../../utils/logger.js';
+export class DiskLogExporter extends Enabler {
+    writer;
+    flushIntervalMs;
+    batchSize;
+    queuedLogs = [];
+    flushTimer = null;
+    flushing = false;
+    constructor(options) {
+        super();
+        this.flushIntervalMs = options.flushIntervalMs || 1000;
+        this.batchSize = options.batchSize || 500;
+        this.writer = new DiskWriter({
+            directoryPath: options.directoryPath,
+            segmentPrefix: 'logs',
+            maxSegmentBytes: options.maxSegmentBytes,
+        });
+    }
+    export(logs, resultCallback) {
+        if (!this.isEnabled()) {
+            resultCallback({ code: ExportResultCode.SUCCESS });
+            return;
+        }
+        try {
+            const serializableLogs = logs
+                .map((logRecord) => this.formatLogRecord(logRecord))
+                .map((log) => removeCircularRefs(log))
+                .map((log) => applyNesting(log));
+            if (serializableLogs.length > 0) {
+                this.queuedLogs.push(...serializableLogs);
+                if (this.queuedLogs.length >= this.batchSize) {
+                    void this.flushPending();
+                }
+                else {
+                    this.scheduleFlush();
+                }
+            }
+            resultCallback({ code: ExportResultCode.SUCCESS });
+        }
+        catch (error) {
+            logger.error(`[DiskLogExporter] Failed to queue logs: ${error?.message || error}`);
+            resultCallback({
+                code: ExportResultCode.FAILED,
+                error: error instanceof Error ? error : new Error(String(error)),
+            });
+        }
+    }
+    async shutdown() {
+        this.disable();
+        if (this.flushTimer) {
+            clearTimeout(this.flushTimer);
+            this.flushTimer = null;
+        }
+        await this.flushPending(true);
+        await this.writer.flush();
+    }
+    async forceFlush() {
+        await this.flushPending(true);
+        await this.writer.flush();
+    }
+    scheduleFlush() {
+        if (this.flushTimer)
+            return;
+        this.flushTimer = setTimeout(() => {
+            this.flushTimer = null;
+            void this.flushPending(true);
+        }, this.flushIntervalMs);
+    }
+    async flushPending(forceAll = false) {
+        if (this.flushing)
+            return;
+        if (this.queuedLogs.length === 0)
+            return;
+        this.flushing = true;
+        try {
+            while (this.queuedLogs.length > 0) {
+                if (!forceAll && this.queuedLogs.length < this.batchSize) {
+                    this.scheduleFlush();
+                    break;
+                }
+                const size = forceAll ? this.queuedLogs.length : this.batchSize;
+                const batch = this.queuedLogs.splice(0, size);
+                await this.writer.appendRecords(batch);
+            }
+        }
+        catch (error) {
+            logger.error(`[DiskLogExporter] Failed writing logs to disk: ${error?.message || error}`);
+        }
+        finally {
+            this.flushing = false;
+        }
+    }
+    formatLogRecord(logRecord) {
+        return {
+            resource: {
+                attributes: logRecord.resource.attributes,
+            },
+            instrumentationScope: logRecord.instrumentationScope,
+            timestamp: hrTimeToMicroseconds(logRecord.hrTime) ?? Date.now(),
+            observedTimestamp: hrTimeToMicroseconds(logRecord.hrTimeObserved) ?? Date.now(),
+            traceId: logRecord.spanContext?.traceId,
+            spanId: logRecord.spanContext?.spanId,
+            traceFlags: logRecord.spanContext?.traceFlags,
+            severityText: logRecord.severityText,
+            severityNumber: logRecord.severityNumber,
+            body: logRecord.body,
+            attributes: logRecord.attributes,
+        };
+    }
+}

package/dist/esm/telemetry/custom-implementations/exporters/DiskMetricExporter.js

@@ -0,0 +1,94 @@
+import { ExportResultCode } from '@opentelemetry/core';
+import { removeCircularRefs } from '../utils/circular.js';
+import { Enabler } from '../wrappers.js';
+import logger from '../../../utils/logger.js';
+import { DiskWriter } from '../../persistence/DiskWriter.js';
+export class DiskMetricExporter extends Enabler {
+    writer;
+    flushIntervalMs;
+    batchSize;
+    queuedScopeMetrics = [];
+    flushTimer = null;
+    flushing = false;
+    constructor(options) {
+        super();
+        this.flushIntervalMs = options.flushIntervalMs || 1000;
+        this.batchSize = options.batchSize || 500;
+        this.writer = new DiskWriter({
+            directoryPath: options.directoryPath,
+            segmentPrefix: 'metrics',
+            maxSegmentBytes: options.maxSegmentBytes,
+        });
+    }
+    export(resourceMetrics, resultCallback) {
+        if (!this.isEnabled()) {
+            resultCallback({ code: ExportResultCode.SUCCESS });
+            return;
+        }
+        try {
+            const scopeMetrics = removeCircularRefs(resourceMetrics.scopeMetrics || []);
+            if (Array.isArray(scopeMetrics) && scopeMetrics.length > 0) {
+                this.queuedScopeMetrics.push(...scopeMetrics);
+                if (this.queuedScopeMetrics.length >= this.batchSize) {
+                    void this.flushPending();
+                }
+                else {
+                    this.scheduleFlush();
+                }
+            }
+            resultCallback({ code: ExportResultCode.SUCCESS });
+        }
+        catch (error) {
+            logger.error(`[DiskMetricExporter] Failed to queue scope metrics: ${error?.message || error}`);
+            resultCallback({
+                code: ExportResultCode.FAILED,
+                error: error instanceof Error ? error : new Error(String(error)),
+            });
+        }
+    }
+    async shutdown() {
+        this.disable();
+        if (this.flushTimer) {
+            clearTimeout(this.flushTimer);
+            this.flushTimer = null;
+        }
+        await this.flushPending(true);
+        await this.writer.flush();
+    }
+    async forceFlush() {
+        await this.flushPending(true);
+        await this.writer.flush();
+    }
+    scheduleFlush() {
+        if (this.flushTimer)
+            return;
+        this.flushTimer = setTimeout(() => {
+            this.flushTimer = null;
+            void this.flushPending(true);
+        }, this.flushIntervalMs);
+    }
+    async flushPending(forceAll = false) {
+        if (this.flushing)
+            return;
+        if (this.queuedScopeMetrics.length === 0)
+            return;
+        this.flushing = true;
+        try {
+            while (this.queuedScopeMetrics.length > 0) {
+                if (!forceAll && this.queuedScopeMetrics.length < this.batchSize) {
+                    this.scheduleFlush();
+                    break;
+                }
+                const size = forceAll ? this.queuedScopeMetrics.length : this.batchSize;
+                const batch = this.queuedScopeMetrics.splice(0, size);
+                await this.writer.appendRecords(batch);
+            }
+        }
+        catch (error) {
+            logger.error(`[DiskMetricExporter] Failed writing metrics to disk: ${error?.message || error}`);
+        }
+        finally {
+            this.flushing = false;
+        }
+    }
+}

package/dist/esm/telemetry/custom-implementations/exporters/DiskTraceExporter.js

@@ -0,0 +1,96 @@
+import { ExportResultCode } from '@opentelemetry/core';
+import logger from '../../../utils/logger.js';
+import { applyNesting, removeCircularRefs } from '../utils/circular.js';
+import { DiskWriter } from '../../persistence/DiskWriter.js';
+import { Enabler } from '../wrappers.js';
+export class DiskTraceExporter extends Enabler {
+    writer;
+    flushIntervalMs;
+    batchSize;
+    queuedSpans = [];
+    flushTimer = null;
+    flushing = false;
+    constructor(options) {
+        super();
+        this.flushIntervalMs = options.flushIntervalMs || 1000;
+        this.batchSize = options.batchSize || 500;
+        this.writer = new DiskWriter({
+            directoryPath: options.directoryPath,
+            segmentPrefix: 'traces',
+            maxSegmentBytes: options.maxSegmentBytes,
+        });
+    }
+    export(spans, resultCallback) {
+        if (!this.isEnabled()) {
+            resultCallback({ code: ExportResultCode.SUCCESS });
+            return;
+        }
+        try {
+            const serializableSpans = spans
+                .map((span) => removeCircularRefs(span))
+                .map((span) => applyNesting(span));
+            if (serializableSpans.length > 0) {
+                this.queuedSpans.push(...serializableSpans);
+                if (this.queuedSpans.length >= this.batchSize) {
+                    void this.flushPending();
+                }
+                else {
+                    this.scheduleFlush();
+                }
+            }
+            resultCallback({ code: ExportResultCode.SUCCESS });
+        }
+        catch (error) {
+            logger.error(`[DiskTraceExporter] Failed to queue spans: ${error?.message || error}`);
+            resultCallback({
+                code: ExportResultCode.FAILED,
+                error: error instanceof Error ? error : new Error(String(error)),
+            });
+        }
+    }
+    async shutdown() {
+        this.disable();
+        if (this.flushTimer) {
+            clearTimeout(this.flushTimer);
+            this.flushTimer = null;
+        }
+        await this.flushPending(true);
+        await this.writer.flush();
+    }
+    async forceFlush() {
+        await this.flushPending(true);
+        await this.writer.flush();
+    }
+    scheduleFlush() {
+        if (this.flushTimer)
+            return;
+        this.flushTimer = setTimeout(() => {
+            this.flushTimer = null;
+            void this.flushPending(true);
+        }, this.flushIntervalMs);
+    }
+    async flushPending(forceAll = false) {
+        if (this.flushing)
+            return;
+        if (this.queuedSpans.length === 0)
+            return;
+        this.flushing = true;
+        try {
+            while (this.queuedSpans.length > 0) {
+                if (!forceAll && this.queuedSpans.length < this.batchSize) {
+                    this.scheduleFlush();
+                    break;
+                }
+                const size = forceAll ? this.queuedSpans.length : this.batchSize;
+                const batch = this.queuedSpans.splice(0, size);
+                await this.writer.appendRecords(batch);
+            }
+        }
+        catch (error) {
+            logger.error(`[DiskTraceExporter] Failed writing spans to disk: ${error?.message || error}`);
+        }
+        finally {
+            this.flushing = false;
+        }
+    }
+}