@skillsmith/core 0.1.0

package/dist/src/telemetry/metrics.js

@@ -0,0 +1,401 @@
+/**
+ * SMI-739: Custom Metrics Registration
+ * SMI-755: Graceful fallback when OpenTelemetry unavailable
+ *
+ * Provides metrics collection for Skillsmith operations:
+ * - Request latency histograms
+ * - Cache hit/miss counters
+ * - Error rate counters
+ * - Active operations gauges
+ *
+ * Configuration:
+ * - OTEL_EXPORTER_OTLP_ENDPOINT: OTLP endpoint for metrics export
+ * - SKILLSMITH_TELEMETRY_ENABLED: Master switch for all telemetry (default: auto)
+ * - SKILLSMITH_METRICS_ENABLED: Enable/disable metrics (default: true if endpoint set)
+ *
+ * Graceful Fallback:
+ * - If OpenTelemetry packages are not installed, uses in-memory implementations
+ * - Metrics APIs remain functional for local statistics
+ */
+/** Whether OpenTelemetry packages are available */
+let otelAvailable = null;
+/**
+ * Dynamic import helper that bypasses TypeScript type checking (SMI-755)
+ */
+async function dynamicImport(moduleName) {
+    try {
+        const importFn = new Function('m', 'return import(m)');
+        return await importFn(moduleName);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Check if OpenTelemetry is available (SMI-755)
+ */
+async function checkOTelAvailability() {
+    if (otelAvailable !== null)
+        return otelAvailable;
+    const result = await dynamicImport('@opentelemetry/api');
+    otelAvailable = result !== null;
+    return otelAvailable;
+}
+/**
+ * Histogram bucket boundaries for latency metrics
+ */
+export const LATENCY_BUCKETS = [1, 5, 10, 25, 50, 100, 250, 500, 1000, 2500, 5000, 10000];
+/**
+ * No-op gauge implementation (used for gauges that track values locally)
+ */
+class NoOpGauge {
+    values = new Map();
+    set(value, labels) {
+        const key = labels ? JSON.stringify(labels) : '';
+        this.values.set(key, value);
+    }
+    getValue(labels) {
+        const key = labels ? JSON.stringify(labels) : '';
+        return this.values.get(key) ?? 0;
+    }
+}
+/**
+ * In-memory counter for when OTEL is not available
+ */
+class InMemoryCounter {
+    values = new Map();
+    add(value, labels) {
+        const key = labels ? JSON.stringify(labels) : '';
+        const current = this.values.get(key) ?? 0;
+        this.values.set(key, current + value);
+    }
+    increment(labels) {
+        this.add(1, labels);
+    }
+    getValues() {
+        return new Map(this.values);
+    }
+}
+/**
+ * In-memory histogram for when OTEL is not available
+ */
+class InMemoryHistogram {
+    values = [];
+    labeledValues = new Map();
+    record(value, labels) {
+        this.values.push(value);
+        if (labels) {
+            const key = JSON.stringify(labels);
+            const arr = this.labeledValues.get(key) ?? [];
+            arr.push(value);
+            this.labeledValues.set(key, arr);
+        }
+    }
+    getStats() {
+        if (this.values.length === 0) {
+            return { count: 0, sum: 0, mean: 0, p50: 0, p95: 0, p99: 0 };
+        }
+        const sorted = [...this.values].sort((a, b) => a - b);
+        const sum = sorted.reduce((acc, v) => acc + v, 0);
+        const mean = sum / sorted.length;
+        const percentile = (p) => {
+            const index = Math.ceil((p / 100) * sorted.length) - 1;
+            return sorted[Math.max(0, index)];
+        };
+        return {
+            count: sorted.length,
+            sum,
+            mean,
+            p50: percentile(50),
+            p95: percentile(95),
+            p99: percentile(99),
+        };
+    }
+}
+/**
+ * Skillsmith Metrics Registry
+ */
+export class MetricsRegistry {
+    counters = new Map();
+    histograms = new Map();
+    gauges = new Map();
+    enabled = false;
+    initialized = false;
+    config;
+    // Predefined metrics
+    mcpRequestLatency;
+    mcpRequestCount;
+    mcpErrorCount;
+    dbQueryLatency;
+    dbQueryCount;
+    cacheHits;
+    cacheMisses;
+    cacheSize;
+    embeddingLatency;
+    embeddingCount;
+    searchLatency;
+    searchCount;
+    activeOperations;
+    constructor(config = {}) {
+        this.config = {
+            serviceName: config.serviceName ?? process.env.OTEL_SERVICE_NAME ?? 'skillsmith',
+            endpoint: config.endpoint ?? process.env.OTEL_EXPORTER_OTLP_ENDPOINT ?? '',
+            exportIntervalMs: config.exportIntervalMs ?? 60000,
+            consoleExport: config.consoleExport ?? false,
+        };
+        // SMI-755: Check master telemetry switch first
+        const telemetryDisabled = process.env.SKILLSMITH_TELEMETRY_ENABLED === 'false';
+        if (telemetryDisabled) {
+            this.enabled = false;
+            // Still create in-memory metrics for local use, just skip OTEL export
+            // Skip further enable checks - master switch overrides all
+        }
+        else {
+            // Check if metrics should be enabled
+            const explicitlyEnabled = process.env.SKILLSMITH_METRICS_ENABLED === 'true';
+            const explicitlyDisabled = process.env.SKILLSMITH_METRICS_ENABLED === 'false';
+            if (explicitlyDisabled) {
+                this.enabled = false;
+            }
+            else if (explicitlyEnabled || this.config.endpoint || this.config.consoleExport) {
+                this.enabled = true;
+            }
+        }
+        // Create predefined metrics
+        this.mcpRequestLatency = this.createHistogram('skillsmith.mcp.request.latency', {
+            description: 'Latency of MCP tool requests in milliseconds',
+            unit: 'ms',
+        });
+        this.mcpRequestCount = this.createCounter('skillsmith.mcp.request.count', {
+            description: 'Total number of MCP tool requests',
+        });
+        this.mcpErrorCount = this.createCounter('skillsmith.mcp.error.count', {
+            description: 'Total number of MCP tool errors',
+        });
+        this.dbQueryLatency = this.createHistogram('skillsmith.db.query.latency', {
+            description: 'Latency of database queries in milliseconds',
+            unit: 'ms',
+        });
+        this.dbQueryCount = this.createCounter('skillsmith.db.query.count', {
+            description: 'Total number of database queries',
+        });
+        this.cacheHits = this.createCounter('skillsmith.cache.hits', {
+            description: 'Total number of cache hits',
+        });
+        this.cacheMisses = this.createCounter('skillsmith.cache.misses', {
+            description: 'Total number of cache misses',
+        });
+        this.cacheSize = this.createGauge('skillsmith.cache.size', {
+            description: 'Current cache size in entries',
+        });
+        this.embeddingLatency = this.createHistogram('skillsmith.embedding.latency', {
+            description: 'Latency of embedding generation in milliseconds',
+            unit: 'ms',
+        });
+        this.embeddingCount = this.createCounter('skillsmith.embedding.count', {
+            description: 'Total number of embeddings generated',
+        });
+        this.searchLatency = this.createHistogram('skillsmith.search.latency', {
+            description: 'Latency of search operations in milliseconds',
+            unit: 'ms',
+        });
+        this.searchCount = this.createCounter('skillsmith.search.count', {
+            description: 'Total number of search operations',
+        });
+        this.activeOperations = this.createGauge('skillsmith.operations.active', {
+            description: 'Number of currently active operations',
+        });
+    }
+    /**
+     * Initialize metrics collection
+     */
+    async initialize() {
+        if (this.initialized)
+            return;
+        if (!this.enabled) {
+            this.initialized = true;
+            return;
+        }
+        // SMI-755: Check if OpenTelemetry is available before attempting to load
+        const isAvailable = await checkOTelAvailability();
+        if (!isAvailable) {
+            // Metrics still work via in-memory implementations, just log info
+            console.info('[Skillsmith Metrics] OpenTelemetry not installed. ' +
+                'Using in-memory metrics (available via getSnapshot()).');
+            this.initialized = true;
+            return;
+        }
+        try {
+            // SMI-755: Lazy load OTEL metrics API with error handling
+            // Note: Full OTEL metrics setup would require additional SDK initialization
+            // For now, we use in-memory metrics that can be exported via the stats endpoint
+            await dynamicImport('@opentelemetry/api');
+            this.initialized = true;
+        }
+        catch (error) {
+            console.warn('[Skillsmith Metrics] Failed to initialize OpenTelemetry:', error);
+            this.enabled = false;
+            this.initialized = true;
+        }
+    }
+    /**
+     * Check if metrics are enabled
+     */
+    isEnabled() {
+        return this.enabled;
+    }
+    /**
+     * Create a counter metric
+     */
+    createCounter(name, _options) {
+        if (this.counters.has(name)) {
+            return this.counters.get(name);
+        }
+        // Use in-memory counter for now
+        const counter = new InMemoryCounter();
+        this.counters.set(name, counter);
+        return counter;
+    }
+    /**
+     * Create a histogram metric
+     */
+    createHistogram(name, _options) {
+        if (this.histograms.has(name)) {
+            return this.histograms.get(name);
+        }
+        // Use in-memory histogram for now
+        const histogram = new InMemoryHistogram();
+        this.histograms.set(name, histogram);
+        return histogram;
+    }
+    /**
+     * Create a gauge metric
+     */
+    createGauge(name, _options) {
+        if (this.gauges.has(name)) {
+            return this.gauges.get(name);
+        }
+        // Use no-op gauge that tracks values
+        const gauge = new NoOpGauge();
+        this.gauges.set(name, gauge);
+        return gauge;
+    }
+    /**
+     * Get current cache hit ratio
+     */
+    getCacheHitRatio() {
+        const hits = this.counters.get('skillsmith.cache.hits');
+        const misses = this.counters.get('skillsmith.cache.misses');
+        if (!hits || !misses)
+            return 0;
+        const hitValues = hits.getValues();
+        const missValues = misses.getValues();
+        let totalHits = 0;
+        let totalMisses = 0;
+        for (const [, count] of hitValues) {
+            totalHits += count;
+        }
+        for (const [, count] of missValues) {
+            totalMisses += count;
+        }
+        const total = totalHits + totalMisses;
+        return total > 0 ? totalHits / total : 0;
+    }
+    /**
+     * Get all metrics as a snapshot
+     */
+    getSnapshot() {
+        const snapshot = {
+            timestamp: new Date().toISOString(),
+            counters: {},
+            histograms: {},
+            gauges: {},
+        };
+        // Collect counter values
+        for (const [name, counter] of this.counters) {
+            if (counter instanceof InMemoryCounter) {
+                const values = counter.getValues();
+                let total = 0;
+                for (const [, count] of values) {
+                    total += count;
+                }
+                snapshot.counters[name] = total;
+            }
+        }
+        // Collect histogram stats
+        for (const [name, histogram] of this.histograms) {
+            if (histogram instanceof InMemoryHistogram) {
+                snapshot.histograms[name] = histogram.getStats();
+            }
+        }
+        // Collect gauge values
+        for (const [name, gauge] of this.gauges) {
+            snapshot.gauges[name] = gauge.getValue();
+        }
+        return snapshot;
+    }
+    /**
+     * Reset all metrics
+     */
+    reset() {
+        // Recreate all metrics
+        for (const [name] of this.counters) {
+            this.counters.set(name, new InMemoryCounter());
+        }
+        for (const [name] of this.histograms) {
+            this.histograms.set(name, new InMemoryHistogram());
+        }
+        for (const [name] of this.gauges) {
+            this.gauges.set(name, new NoOpGauge());
+        }
+    }
+}
+// Default metrics registry instance
+let defaultRegistry = null;
+/**
+ * Get the default metrics registry
+ */
+export function getMetrics() {
+    if (!defaultRegistry) {
+        defaultRegistry = new MetricsRegistry();
+    }
+    return defaultRegistry;
+}
+/**
+ * Initialize the default metrics registry
+ */
+export async function initializeMetrics(config) {
+    if (defaultRegistry) {
+        defaultRegistry.reset();
+    }
+    defaultRegistry = new MetricsRegistry(config);
+    await defaultRegistry.initialize();
+    return defaultRegistry;
+}
+/**
+ * Helper: Time an async operation and record to histogram
+ */
+export async function timeAsync(histogram, fn, labels) {
+    const start = performance.now();
+    try {
+        return await fn();
+    }
+    finally {
+        const duration = performance.now() - start;
+        histogram.record(duration, labels);
+    }
+}
+/**
+ * Helper: Time a sync operation and record to histogram
+ */
+export function timeSync(histogram, fn, labels) {
+    const start = performance.now();
+    try {
+        return fn();
+    }
+    finally {
+        const duration = performance.now() - start;
+        histogram.record(duration, labels);
+    }
+}
+//# sourceMappingURL=metrics.js.map

package/dist/src/telemetry/metrics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.js","sourceRoot":"","sources":["../../../src/telemetry/metrics.ts"],"names":[],"mappings":"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"}

package/dist/src/telemetry/prometheus.d.ts

@@ -0,0 +1,81 @@
+/**
+ * SMI-1018: Prometheus Metrics Exporter
+ *
+ * Exports Skillsmith metrics in Prometheus text exposition format.
+ * Integrates with existing MetricsRegistry for monitoring dashboards.
+ *
+ * @see https://prometheus.io/docs/instrumenting/exposition_formats/
+ */
+import type { MetricsSnapshot } from './metrics.js';
+/**
+ * Prometheus export options
+ */
+export interface PrometheusExportOptions {
+    /** Include TYPE and HELP comments (default: true) */
+    includeMetadata?: boolean;
+    /** Prefix for all metric names (default: none) */
+    prefix?: string;
+    /** Custom labels to add to all metrics */
+    globalLabels?: Record<string, string>;
+    /** Timestamp for all metrics (epoch ms, default: current time) */
+    timestamp?: number;
+}
+/**
+ * Export metrics snapshot to Prometheus text format
+ *
+ * @param snapshot - Metrics snapshot from MetricsRegistry.getSnapshot()
+ * @param options - Export options
+ * @returns Prometheus text exposition format string
+ *
+ * @example
+ * ```typescript
+ * const metrics = getMetrics()
+ * const snapshot = metrics.getSnapshot()
+ * const prometheusText = exportToPrometheus(snapshot)
+ * // Returns:
+ * // # HELP skillsmith_mcp_request_total Total number of MCP tool requests
+ * // # TYPE skillsmith_mcp_request_total counter
+ * // skillsmith_mcp_request_total 42
+ * ```
+ */
+export declare function exportToPrometheus(snapshot: MetricsSnapshot, options?: PrometheusExportOptions): string;
+/**
+ * Get current metrics in Prometheus format
+ * Convenience function that combines getSnapshot() and exportToPrometheus()
+ *
+ * @param options - Export options
+ * @returns Prometheus text exposition format string
+ *
+ * @example
+ * ```typescript
+ * // In an HTTP handler:
+ * app.get('/metrics', (req, res) => {
+ *   res.set('Content-Type', 'text/plain; version=0.0.4')
+ *   res.send(getPrometheusMetrics())
+ * })
+ * ```
+ */
+export declare function getPrometheusMetrics(options?: PrometheusExportOptions): string;
+/**
+ * Prometheus HTTP endpoint handler
+ *
+ * Creates a handler function suitable for Express/Koa/etc.
+ *
+ * @param options - Export options
+ * @returns Handler function (req, res) => void
+ *
+ * @example
+ * ```typescript
+ * // Express
+ * import express from 'express'
+ * import { createPrometheusHandler } from '@skillsmith/core'
+ *
+ * const app = express()
+ * app.get('/metrics', createPrometheusHandler())
+ * ```
+ */
+export declare function createPrometheusHandler(options?: PrometheusExportOptions): (req: unknown, res: {
+    set: (k: string, v: string) => void;
+    send: (body: string) => void;
+}) => void;
+//# sourceMappingURL=prometheus.d.ts.map

package/dist/src/telemetry/prometheus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prometheus.d.ts","sourceRoot":"","sources":["../../../src/telemetry/prometheus.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AAiBnD;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,qDAAqD;IACrD,eAAe,CAAC,EAAE,OAAO,CAAA;IACzB,kDAAkD;IAClD,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,0CAA0C;IAC1C,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACrC,kEAAkE;IAClE,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAoID;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,eAAe,EACzB,OAAO,GAAE,uBAA4B,GACpC,MAAM,CAgER;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,GAAE,uBAA4B,GAAG,MAAM,CAIlF;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,GAAE,uBAA4B,GACpC,CACD,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE;IAAE,GAAG,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IAAC,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;CAAE,KACvE,IAAI,CAKR"}