@momentumcms/plugins-otel 0.5.4 → 0.5.5

package/package.json

@@ -1,37 +1,62 @@
 {
-  "name": "@momentumcms/plugins-otel",
-  "version": "0.5.4",
-  "description": "OpenTelemetry observability plugin for Momentum CMS",
-  "license": "MIT",
-  "author": "Momentum CMS Contributors",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/DonaldMurillo/momentum-cms.git",
-    "directory": "libs/plugins/otel"
-  },
-  "homepage": "https://github.com/DonaldMurillo/momentum-cms#readme",
-  "bugs": {
-    "url": "https://github.com/DonaldMurillo/momentum-cms/issues"
-  },
-  "keywords": [
-    "cms",
-    "momentum-cms",
-    "opentelemetry",
-    "observability",
-    "tracing",
-    "metrics"
-  ],
-  "engines": {
-    "node": ">=18"
-  },
-  "main": "./index.cjs",
-  "types": "./src/index.d.ts",
-  "peerDependencies": {
-    "@momentumcms/core": "0.5.4",
-    "@momentumcms/logger": "0.5.4",
-    "@momentumcms/plugins-core": "0.5.4",
-    "@opentelemetry/api": "^1.0.0"
-  },
-  "dependencies": {},
-  "module": "./index.js"
-}
+	"name": "@momentumcms/plugins-otel",
+	"version": "0.5.5",
+	"description": "OpenTelemetry observability plugin for Momentum CMS",
+	"license": "MIT",
+	"author": "Momentum CMS Contributors",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/DonaldMurillo/momentum-cms.git",
+		"directory": "libs/plugins/otel"
+	},
+	"homepage": "https://github.com/DonaldMurillo/momentum-cms#readme",
+	"bugs": {
+		"url": "https://github.com/DonaldMurillo/momentum-cms/issues"
+	},
+	"keywords": [
+		"cms",
+		"momentum-cms",
+		"opentelemetry",
+		"observability",
+		"tracing",
+		"metrics"
+	],
+	"engines": {
+		"node": ">=18"
+	},
+	"main": "./index.cjs",
+	"types": "./src/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./src/index.d.ts",
+			"default": "./index.cjs"
+		},
+		"./admin-routes": {
+			"types": "./src/lib/otel-admin-routes.d.ts",
+			"default": "./lib/otel-admin-routes.cjs"
+		}
+	},
+	"peerDependencies": {
+		"@opentelemetry/api": "^1.3.0",
+		"@opentelemetry/sdk-metrics": "^2.0.0",
+		"@opentelemetry/exporter-prometheus": "^0.213.0",
+		"@momentumcms/plugins-core": "0.5.5",
+		"@momentumcms/logger": "0.5.5",
+		"@momentumcms/core": "0.5.5",
+		"express": "^4.21.2",
+		"@angular/core": "~21.2.0",
+		"@angular/common": "~21.2.0",
+		"@momentumcms/ui": "0.5.5",
+		"@ng-icons/core": "^33.0.0",
+		"@ng-icons/heroicons": "^33.0.0"
+	},
+	"peerDependenciesMeta": {
+		"@opentelemetry/sdk-metrics": {
+			"optional": true
+		},
+		"@opentelemetry/exporter-prometheus": {
+			"optional": true
+		}
+	},
+	"dependencies": {}
+}

package/src/index.d.ts

@@ -1,2 +1,2 @@
 export { otelPlugin } from './lib/otel-plugin';
-export type { OtelPluginConfig } from './lib/otel-plugin.types';
+export type { OtelPluginConfig, OtelMetricsConfig, OtelSummaryData, OtelSnapshotData, SpanRecord, } from './lib/otel-plugin.types';

package/src/lib/api/otel-api-guards.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Shared type guards and interfaces for OTel API consumers.
+ *
+ * Used by both the query handler and the snapshot service to
+ * duck-type the MomentumAPI and collection operations.
+ */
+export interface MomentumAPILike {
+    collection(slug: string): unknown;
+    setContext(ctx: Record<string, unknown>): MomentumAPILike;
+}
+export interface FindableCollection {
+    find(query: Record<string, unknown>): Promise<{
+        docs?: unknown[];
+        totalDocs?: number;
+        totalPages?: number;
+    }>;
+}
+export interface CreatableCollection {
+    create(data: Record<string, unknown>): Promise<unknown>;
+}
+export interface DeletableCollection {
+    delete(id: string): Promise<unknown>;
+}
+export declare function isFindable(val: unknown): val is FindableCollection;
+export declare function isCreatable(val: unknown): val is CreatableCollection;
+export declare function isDeletable(val: unknown): val is DeletableCollection;
+export declare function isRecord(val: unknown): val is Record<string, unknown>;

package/src/lib/api/otel-query-handler.d.ts

@@ -0,0 +1,20 @@
+/**
+ * OTel Query Handler
+ *
+ * Express Router that serves the observability summary, history,
+ * export, and purge endpoints for the admin dashboard.
+ * Admin-gated using type guards (no assertions).
+ */
+import type { Router } from 'express';
+import type { MetricsStore } from '../metrics/metrics-store';
+import type { MetricsSnapshotService } from '../metrics/metrics-snapshot-service';
+import { type MomentumAPILike } from './otel-api-guards';
+/**
+ * Creates an Express Router that serves OTel endpoints.
+ *
+ * `GET /api/otel/summary` — live metrics snapshot
+ * `GET /api/otel/history` — persisted snapshots with time range
+ * `DELETE /api/otel/history` — purge all snapshots
+ * `GET /api/otel/export` — streaming CSV download
+ */
+export declare function createOtelQueryRouter(store: MetricsStore, getApi?: () => MomentumAPILike | null, snapshotService?: MetricsSnapshotService | null): Router;

package/src/lib/exporters/prometheus-handler.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Prometheus Scrape Endpoint
+ *
+ * Express Router that exposes metrics in Prometheus text exposition format.
+ * Uses @opentelemetry/exporter-prometheus in manual mode (no standalone server).
+ */
+import type { Router } from 'express';
+interface PrometheusHandlerOptions {
+    /** The PrometheusExporter instance (from @opentelemetry/exporter-prometheus) */
+    exporter: unknown;
+}
+/**
+ * Creates an Express Router that serves the Prometheus scrape endpoint.
+ *
+ * The endpoint is intentionally unauthenticated — Prometheus scrapers
+ * typically don't carry auth tokens, and metrics data is operational
+ * (not sensitive user data).
+ */
+export declare function createPrometheusHandler(options: PrometheusHandlerOptions): Router;
+export {};

package/src/lib/metrics/collection-metrics.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Collection Operation Metrics
+ *
+ * Injects hooks into collections that record OTel metrics (counters, histograms)
+ * and update the internal MetricsStore for each CRUD operation.
+ */
+import type { CollectionConfig } from '@momentumcms/core';
+import type { Meter } from '@opentelemetry/api';
+import type { MetricsStore } from './metrics-store';
+interface CollectionMetricsOptions {
+    store: MetricsStore;
+    /** OTel Meter instance (optional) */
+    meter?: Meter | null;
+    /** Filter to specific operations */
+    operations?: string[];
+}
+/**
+ * Injects collection hooks that record operation metrics.
+ */
+export declare function injectCollectionMetricsHooks(collections: CollectionConfig[], options: CollectionMetricsOptions): void;
+export {};

package/src/lib/metrics/metrics-snapshot-service.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Metrics Snapshot Service
+ *
+ * Periodically persists in-memory metrics to the otel-snapshots collection
+ * and restores them on startup. Auto-prunes old snapshots to bound DB growth.
+ */
+import type { MetricsStore } from './metrics-store';
+import { type MomentumAPILike } from '../api/otel-api-guards';
+export type { MomentumAPILike } from '../api/otel-api-guards';
+export interface MetricsSnapshotServiceOptions {
+    store: MetricsStore;
+    getApi: () => MomentumAPILike | null;
+    snapshotInterval?: number;
+    retentionDays?: number;
+}
+export declare class MetricsSnapshotService {
+    private readonly store;
+    private readonly getApi;
+    private readonly snapshotInterval;
+    private readonly retentionDays;
+    private readonly logger;
+    private timer;
+    private flushing;
+    constructor(options: MetricsSnapshotServiceOptions);
+    start(): void;
+    flush(): Promise<void>;
+    restore(): Promise<void>;
+    shutdown(): Promise<void>;
+    purgeAll(): Promise<number>;
+    private prune;
+}

package/src/lib/metrics/metrics-store.d.ts

@@ -0,0 +1,31 @@
+/**
+ * In-memory metrics store for the admin dashboard API.
+ *
+ * Maintains rolling counters and a circular buffer of recent spans
+ * so the `/api/otel/summary` endpoint can return a JSON snapshot
+ * without directly depending on the OTel SDK.
+ */
+import type { SpanRecord, OtelSummaryData, OtelSnapshotData } from '../otel-plugin.types';
+export type { SpanRecord, OtelSummaryData, OtelSnapshotData } from '../otel-plugin.types';
+export declare class MetricsStore {
+    private readonly startTime;
+    private readonly maxSpans;
+    private readonly recentSpans;
+    private readonly collectionMetrics;
+    private activeRequests;
+    private totalRequests;
+    private totalDurationMs;
+    private errorCount;
+    private readonly byMethod;
+    private readonly byStatusCode;
+    constructor(maxSpans?: number);
+    recordSpan(span: SpanRecord): void;
+    recordCollectionOperation(collection: string, operation: 'create' | 'update' | 'delete', durationMs: number): void;
+    recordHttpRequest(method: string, statusCode: number, durationMs: number): void;
+    incrementActiveRequests(): void;
+    decrementActiveRequests(): void;
+    getSnapshotData(): OtelSnapshotData;
+    restore(snapshot: OtelSnapshotData): void;
+    private buildCollectionMetrics;
+    getSummary(): OtelSummaryData;
+}

package/src/lib/metrics/otel-helpers.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Shared OTel helpers.
+ *
+ * Uses the @opentelemetry/api types (already a required peer dep)
+ * to provide properly typed instrument creation without type assertions.
+ */
+import type { Meter, Counter, Histogram, UpDownCounter } from '@opentelemetry/api';
+export interface OtelInstruments {
+    requestDuration: Histogram;
+    requestTotal: Counter;
+    activeRequests: UpDownCounter;
+}
+export interface CollectionInstruments {
+    operationTotal: Counter;
+    operationDuration: Histogram;
+}
+/**
+ * Creates HTTP request instruments from a Meter.
+ */
+export declare function createRequestInstruments(meter: Meter): OtelInstruments;
+/**
+ * Creates collection operation instruments from a Meter.
+ */
+export declare function createCollectionInstruments(meter: Meter): CollectionInstruments;
+/**
+ * Tries to load the OTel SDK and Prometheus exporter.
+ * Returns null if the packages are not installed.
+ */
+export declare function tryLoadOtelSdk(serviceName: string): {
+    meter: Meter;
+    provider: {
+        shutdown: () => Promise<void>;
+    };
+    exporter: unknown;
+} | null;
+/**
+ * Reads span context from a doc's __otelSpan property.
+ */
+export declare function getSpanContext(doc: Record<string, unknown>): {
+    traceId: string;
+    spanId: string;
+} | null;

package/src/lib/metrics/otel-snapshot-collection.d.ts

@@ -0,0 +1,7 @@
+/**
+ * OTel Snapshots Collection
+ *
+ * Internal collection for persisting periodic metric snapshots.
+ * Injected into the collections array by the otel plugin during onInit.
+ */
+export declare const OtelSnapshotsCollection: import("@momentumcms/core").CollectionConfig;

package/src/lib/metrics/request-metrics.d.ts

@@ -0,0 +1,19 @@
+/**
+ * HTTP Request Metrics Middleware
+ *
+ * Express middleware that records HTTP request metrics using both
+ * the OpenTelemetry Metrics API and the internal MetricsStore.
+ */
+import type { Router } from 'express';
+import type { Meter } from '@opentelemetry/api';
+import type { MetricsStore } from './metrics-store';
+interface RequestMetricsOptions {
+    store: MetricsStore;
+    /** OTel Meter instance (optional — when provided, records OTel instruments) */
+    meter?: Meter | null;
+}
+/**
+ * Creates Express middleware that records HTTP request metrics.
+ */
+export declare function createRequestMetricsMiddleware(options: RequestMetricsOptions): Router;
+export {};

package/src/lib/otel-admin-routes.d.ts

@@ -0,0 +1,3 @@
+import type { PluginAdminRouteDescriptor } from '@momentumcms/core';
+
+export declare const otelAdminRoutes: PluginAdminRouteDescriptor[];

package/src/lib/otel-plugin.d.ts

@@ -1,12 +1,13 @@
 /**
- * OpenTelemetry Tracing Plugin
+ * OpenTelemetry Observability Plugin
  *
- * Injects tracing spans into collection hooks and optionally
- * enriches log entries with trace/span IDs.
+ * Injects tracing spans into collection hooks, optionally enriches log
+ * entries with trace/span IDs, and can collect metrics exposed via a
+ * Prometheus scrape endpoint and an admin dashboard.
  *
  * Requires @opentelemetry/api as a peer dependency.
- * The user is responsible for setting up the OTel SDK (exporters, etc.).
- * This plugin only creates spans using the OTel API.
+ * Metrics features require @opentelemetry/sdk-metrics and optionally
+ * @opentelemetry/exporter-prometheus (both optional peer deps).
  *
  * @example
  * ```typescript
@@ -14,7 +15,10 @@
  *
  * export default defineMomentumConfig({
  *   plugins: [
- *     otelPlugin({ serviceName: 'my-cms' }),
+ *     otelPlugin({
+ *       serviceName: 'my-cms',
+ *       metrics: { enabled: true, prometheus: true },
+ *     }),
  *   ],
  * });
  * ```
@@ -22,7 +26,7 @@
 import type { MomentumPlugin } from '@momentumcms/plugins/core';
 import type { OtelPluginConfig } from './otel-plugin.types';
 /**
- * Creates an OpenTelemetry tracing plugin.
+ * Creates an OpenTelemetry observability plugin.
  *
  * @param config - Plugin configuration
  * @returns MomentumPlugin instance

package/src/lib/otel-plugin.types.d.ts

@@ -1,6 +1,82 @@
 /**
- * OTel Plugin Configuration Types
+ * OTel Plugin Types
+ *
+ * Shared types used by both server (metrics-store) and browser (dashboard service).
  */
+/**
+ * A recorded span for the admin dashboard.
+ */
+export interface SpanRecord {
+    traceId: string;
+    spanId: string;
+    name: string;
+    collection: string;
+    operation: string;
+    durationMs: number;
+    status: 'ok' | 'error';
+    timestamp: string;
+}
+/**
+ * Collection metrics entry for the admin dashboard.
+ */
+export interface CollectionMetricEntry {
+    collection: string;
+    creates: number;
+    updates: number;
+    deletes: number;
+    avgDurationMs: number;
+}
+/**
+ * Full observability summary returned by the admin API.
+ */
+export interface OtelSummaryData {
+    uptime: number;
+    activeRequests: number;
+    memoryUsageMb: number;
+    requestMetrics: {
+        totalRequests: number;
+        avgDurationMs: number;
+        errorCount: number;
+        byMethod: Record<string, number>;
+        byStatusCode: Record<string, number>;
+    };
+    collectionMetrics: CollectionMetricEntry[];
+    recentSpans: SpanRecord[];
+}
+/**
+ * A persisted metric snapshot (stored in the otel-snapshots collection).
+ */
+export interface OtelSnapshotData {
+    id?: string;
+    totalRequests: number;
+    errorCount: number;
+    avgDurationMs: number;
+    memoryUsageMb: number;
+    byMethod: Record<string, number>;
+    byStatusCode: Record<string, number>;
+    collectionMetrics: CollectionMetricEntry[];
+    topSpans: SpanRecord[];
+    createdAt?: string;
+}
+/**
+ * Metrics configuration for the OpenTelemetry plugin.
+ */
+export interface OtelMetricsConfig {
+    /** Enable metrics collection. @default false */
+    enabled?: boolean;
+    /** Prometheus scrape endpoint. @default true when metrics enabled */
+    prometheus?: boolean | {
+        path?: string;
+    };
+    /** Custom MeterProvider instance. When omitted and prometheus is enabled, one is auto-created. */
+    meterProvider?: unknown;
+    /** Admin observability dashboard. @default true when metrics enabled */
+    adminDashboard?: boolean;
+    /** Interval between snapshot flushes in ms. @default 60000 */
+    snapshotInterval?: number;
+    /** Days to retain snapshots before auto-pruning. @default 7 */
+    retentionDays?: number;
+}
 /**
  * Configuration for the OpenTelemetry plugin.
  */
@@ -13,4 +89,6 @@ export interface OtelPluginConfig {
     attributes?: Record<string, string>;
     /** Collection operations to trace. @default all */
     operations?: Array<'create' | 'update' | 'delete' | 'find'>;
+    /** Metrics configuration */
+    metrics?: OtelMetricsConfig;
 }

package/CHANGELOG.md

@@ -1,110 +0,0 @@
-## 0.5.4 (2026-03-07)
-
-This was a version bump only for plugins-otel to align it with other projects, there were no code changes.
-
-## 0.5.0 (2026-02-23)
-
-This was a version bump only for plugins-otel to align it with other projects, there were no code changes.
-
-## 0.4.1 (2026-02-22)
-
-This was a version bump only for plugins-otel to align it with other projects, there were no code changes.
-
-## 0.4.0 (2026-02-22)
-
-### 🚀 Features
-
-- blocks showcase with articles, pages, and UI fixes ([#36](https://github.com/DonaldMurillo/momentum-cms/pull/36))
-
-### ❤️ Thank You
-
-- Claude Opus 4.6
-- Donald Murillo @DonaldMurillo
-
-## 0.3.0 (2026-02-20)
-
-### 🚀 Features
-
-- add named tabs support with nested data grouping and UI improvements ([#30](https://github.com/DonaldMurillo/momentum-cms/pull/30))
-
-### ❤️ Thank You
-
-- Claude Opus 4.6
-- Donald Murillo @DonaldMurillo
-
-## 0.2.0 (2026-02-17)
-
-This was a version bump only for plugins-otel to align it with other projects, there were no code changes.
-
-## 0.1.10 (2026-02-17)
-
-### 🩹 Fixes
-
-- **create-momentum-app:** add shell option to execFileSync for Windows ([#28](https://github.com/DonaldMurillo/momentum-cms/pull/28))
-
-### ❤️ Thank You
-
-- Claude Opus 4.6
-- Donald Murillo @DonaldMurillo
-
-## 0.1.9 (2026-02-16)
-
-This was a version bump only for plugins-otel to align it with other projects, there were no code changes.
-
-## 0.1.8 (2026-02-16)
-
-### 🩹 Fixes
-
-- correct repository URLs and add GitHub link to CLI ([#26](https://github.com/DonaldMurillo/momentum-cms/pull/26))
-
-### ❤️ Thank You
-
-- Claude Opus 4.6
-- Donald Murillo @DonaldMurillo
-
-## 0.1.7 (2026-02-16)
-
-### 🩹 Fixes
-
-- correct repository URLs and add GitHub link to CLI output ([f7e96bb](https://github.com/DonaldMurillo/momentum-cms/commit/f7e96bb))
-
-### ❤️ Thank You
-
-- Claude Opus 4.6
-- Donald Murillo @DonaldMurillo
-
-## 0.1.6 (2026-02-16)
-
-This was a version bump only for plugins-otel to align it with other projects, there were no code changes.
-
-## 0.1.5 (2026-02-16)
-
-This was a version bump only for plugins-otel to align it with other projects, there were no code changes.
-
-## 0.1.4 (2026-02-16)
-
-This was a version bump only for plugins-otel to align it with other projects, there were no code changes.
-
-## 0.1.3 (2026-02-16)
-
-This was a version bump only for plugins-otel to align it with other projects, there were no code changes.
-
-## 0.1.2 (2026-02-16)
-
-### 🩹 Fixes
-
-- **release:** centralize manifestRootsToUpdate to update both source and dist ([2b8f832](https://github.com/DonaldMurillo/momentum-cms/commit/2b8f832))
-- **create-app:** fix Angular SSR, Analog builds, and CJS/ESM compatibility ([28d4d0a](https://github.com/DonaldMurillo/momentum-cms/commit/28d4d0a))
-
-### ❤️ Thank You
-
-- Claude Opus 4.6
-- Donald Murillo @DonaldMurillo
-
-## 0.1.1 (2026-02-16)
-
-This was a version bump only for plugins-otel to align it with other projects, there were no code changes.
-
-## 0.1.0 (2026-02-16)
-
-This was a version bump only for plugins-otel to align it with other projects, there were no code changes.

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2024-present Momentum CMS Contributors
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.