@skillsmith/core 0.1.0

package/dist/src/telemetry/prometheus.js

@@ -0,0 +1,252 @@
+/**
+ * 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 { getMetrics } from './metrics.js';
+/**
+ * Metric descriptions for Prometheus HELP text
+ */
+const METRIC_DESCRIPTIONS = {
+    'skillsmith.mcp.request.latency': {
+        name: 'skillsmith_mcp_request_latency_ms',
+        type: 'histogram',
+        help: 'Latency of MCP tool requests in milliseconds',
+    },
+    'skillsmith.mcp.request.count': {
+        name: 'skillsmith_mcp_request_total',
+        type: 'counter',
+        help: 'Total number of MCP tool requests',
+    },
+    'skillsmith.mcp.error.count': {
+        name: 'skillsmith_mcp_errors_total',
+        type: 'counter',
+        help: 'Total number of MCP tool errors',
+    },
+    'skillsmith.db.query.latency': {
+        name: 'skillsmith_db_query_latency_ms',
+        type: 'histogram',
+        help: 'Latency of database queries in milliseconds',
+    },
+    'skillsmith.db.query.count': {
+        name: 'skillsmith_db_query_total',
+        type: 'counter',
+        help: 'Total number of database queries',
+    },
+    'skillsmith.cache.hits': {
+        name: 'skillsmith_cache_hits_total',
+        type: 'counter',
+        help: 'Total number of cache hits',
+    },
+    'skillsmith.cache.misses': {
+        name: 'skillsmith_cache_misses_total',
+        type: 'counter',
+        help: 'Total number of cache misses',
+    },
+    'skillsmith.cache.size': {
+        name: 'skillsmith_cache_entries',
+        type: 'gauge',
+        help: 'Current number of entries in cache',
+    },
+    'skillsmith.embedding.latency': {
+        name: 'skillsmith_embedding_latency_ms',
+        type: 'histogram',
+        help: 'Latency of embedding generation in milliseconds',
+    },
+    'skillsmith.embedding.count': {
+        name: 'skillsmith_embedding_total',
+        type: 'counter',
+        help: 'Total number of embeddings generated',
+    },
+    'skillsmith.search.latency': {
+        name: 'skillsmith_search_latency_ms',
+        type: 'histogram',
+        help: 'Latency of search operations in milliseconds',
+    },
+    'skillsmith.search.count': {
+        name: 'skillsmith_search_total',
+        type: 'counter',
+        help: 'Total number of search operations',
+    },
+    'skillsmith.operations.active': {
+        name: 'skillsmith_operations_active',
+        type: 'gauge',
+        help: 'Number of currently active operations',
+    },
+    // Rate limiting metrics (from security module)
+    'skillsmith.rate_limit.allowed': {
+        name: 'skillsmith_rate_limit_allowed_total',
+        type: 'counter',
+        help: 'Total number of requests allowed by rate limiter',
+    },
+    'skillsmith.rate_limit.blocked': {
+        name: 'skillsmith_rate_limit_blocked_total',
+        type: 'counter',
+        help: 'Total number of requests blocked by rate limiter',
+    },
+    // Audit metrics
+    'skillsmith.audit.events': {
+        name: 'skillsmith_audit_events_total',
+        type: 'counter',
+        help: 'Total number of audit events logged',
+    },
+    // Security scan metrics
+    'skillsmith.security_scan.count': {
+        name: 'skillsmith_security_scan_total',
+        type: 'counter',
+        help: 'Total number of security scans performed',
+    },
+    'skillsmith.security_scan.findings': {
+        name: 'skillsmith_security_scan_findings_total',
+        type: 'counter',
+        help: 'Total number of security findings detected',
+    },
+};
+/**
+ * Convert internal metric name to Prometheus format
+ * - Replace dots with underscores
+ * - Apply prefix if provided
+ */
+function toPrometheusName(internalName, prefix) {
+    const meta = METRIC_DESCRIPTIONS[internalName];
+    const baseName = meta?.name ?? internalName.replace(/\./g, '_');
+    return prefix ? `${prefix}_${baseName}` : baseName;
+}
+/**
+ * Format labels as Prometheus label string
+ */
+function formatLabels(labels) {
+    if (!labels || Object.keys(labels).length === 0) {
+        return '';
+    }
+    const pairs = Object.entries(labels)
+        .map(([k, v]) => `${k}="${escapeLabel(v)}"`)
+        .join(',');
+    return `{${pairs}}`;
+}
+/**
+ * Escape label values for Prometheus format
+ */
+function escapeLabel(value) {
+    return value.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, '\\n');
+}
+/**
+ * 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 function exportToPrometheus(snapshot, options = {}) {
+    const { includeMetadata = true, prefix, globalLabels, timestamp } = options;
+    const lines = [];
+    // Process counters
+    for (const [name, value] of Object.entries(snapshot.counters)) {
+        const promName = toPrometheusName(name, prefix);
+        const meta = METRIC_DESCRIPTIONS[name];
+        if (includeMetadata && meta) {
+            lines.push(`# HELP ${promName} ${meta.help}`);
+            lines.push(`# TYPE ${promName} counter`);
+        }
+        const labels = formatLabels(globalLabels);
+        const ts = timestamp ? ` ${timestamp}` : '';
+        lines.push(`${promName}${labels} ${value}${ts}`);
+        lines.push(''); // Blank line between metrics
+    }
+    // Process histograms
+    for (const [name, stats] of Object.entries(snapshot.histograms)) {
+        const promName = toPrometheusName(name, prefix);
+        const meta = METRIC_DESCRIPTIONS[name];
+        const ts = timestamp ? ` ${timestamp}` : '';
+        if (includeMetadata && meta) {
+            lines.push(`# HELP ${promName} ${meta.help}`);
+            lines.push(`# TYPE ${promName} histogram`);
+        }
+        // Export histogram summary stats as gauges (since we don't have actual buckets)
+        const baseLabels = globalLabels ? formatLabels(globalLabels) : '';
+        lines.push(`${promName}_count${baseLabels} ${stats.count}${ts}`);
+        lines.push(`${promName}_sum${baseLabels} ${stats.sum}${ts}`);
+        // Export percentiles as quantiles
+        const p50Labels = formatLabels({ ...globalLabels, quantile: '0.5' });
+        const p95Labels = formatLabels({ ...globalLabels, quantile: '0.95' });
+        const p99Labels = formatLabels({ ...globalLabels, quantile: '0.99' });
+        lines.push(`${promName}${p50Labels} ${stats.p50}${ts}`);
+        lines.push(`${promName}${p95Labels} ${stats.p95}${ts}`);
+        lines.push(`${promName}${p99Labels} ${stats.p99}${ts}`);
+        lines.push('');
+    }
+    // Process gauges
+    for (const [name, value] of Object.entries(snapshot.gauges)) {
+        const promName = toPrometheusName(name, prefix);
+        const meta = METRIC_DESCRIPTIONS[name];
+        if (includeMetadata && meta) {
+            lines.push(`# HELP ${promName} ${meta.help}`);
+            lines.push(`# TYPE ${promName} gauge`);
+        }
+        const labels = formatLabels(globalLabels);
+        const ts = timestamp ? ` ${timestamp}` : '';
+        lines.push(`${promName}${labels} ${value}${ts}`);
+        lines.push('');
+    }
+    return lines.join('\n').trim();
+}
+/**
+ * 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 function getPrometheusMetrics(options = {}) {
+    const metrics = getMetrics();
+    const snapshot = metrics.getSnapshot();
+    return exportToPrometheus(snapshot, options);
+}
+/**
+ * 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 function createPrometheusHandler(options = {}) {
+    return (_req, res) => {
+        res.set('Content-Type', 'text/plain; version=0.0.4; charset=utf-8');
+        res.send(getPrometheusMetrics(options));
+    };
+}
+//# sourceMappingURL=prometheus.js.map

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

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

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

@@ -0,0 +1,151 @@
+/**
+ * SMI-739: OpenTelemetry Tracer Setup
+ * SMI-755: Graceful fallback when OpenTelemetry unavailable
+ *
+ * Provides distributed tracing for Skillsmith operations:
+ * - MCP tool calls
+ * - Database queries
+ * - Cache operations
+ * - External API calls
+ *
+ * Configuration:
+ * - OTEL_EXPORTER_OTLP_ENDPOINT: OTLP endpoint for trace export
+ * - OTEL_SERVICE_NAME: Service name (default: skillsmith)
+ * - SKILLSMITH_TELEMETRY_ENABLED: Master switch for all telemetry (default: auto)
+ * - SKILLSMITH_TRACING_ENABLED: Enable/disable tracing (default: true if endpoint set)
+ *
+ * Graceful Fallback:
+ * - If OpenTelemetry packages are not installed, uses NoOp implementations
+ * - Logs warning on fallback (unless SKILLSMITH_TELEMETRY_ENABLED=false)
+ * - All tracing APIs remain functional (just don't record)
+ */
+/**
+ * Local type definitions matching OpenTelemetry interfaces
+ * SMI-755: Allows compilation without @opentelemetry/api installed
+ */
+interface OTelSpan {
+    setAttributes(attributes: Record<string, unknown>): void;
+    setStatus(status: {
+        code: number;
+        message?: string;
+    }): void;
+    recordException(error: Error): void;
+    addEvent(name: string, attributes?: Record<string, unknown>): void;
+    end(): void;
+}
+interface OTelSpanOptions {
+    attributes?: Record<string, unknown>;
+    links?: unknown[];
+    startTime?: number;
+    root?: boolean;
+    kind?: number;
+}
+type Span = OTelSpan;
+type SpanOptions = OTelSpanOptions;
+/**
+ * Tracer configuration
+ */
+export interface TracerConfig {
+    /** Service name for spans (default: skillsmith) */
+    serviceName?: string;
+    /** OTLP endpoint URL */
+    endpoint?: string;
+    /** Enable auto-instrumentation (default: true) */
+    autoInstrument?: boolean;
+    /** Enable console exporter for debugging (default: false) */
+    consoleExport?: boolean;
+    /** Sample rate 0-1 (default: 1.0 = 100%) */
+    sampleRate?: number;
+}
+/**
+ * Span attribute types
+ */
+export interface SpanAttributes {
+    [key: string]: string | number | boolean | string[] | number[] | boolean[] | undefined;
+}
+/**
+ * Span wrapper for easier usage
+ */
+export interface SpanWrapper {
+    /** Add attributes to span */
+    setAttributes(attributes: SpanAttributes): void;
+    /** Set span status */
+    setStatus(code: 'ok' | 'error', message?: string): void;
+    /** Record an exception */
+    recordException(error: Error): void;
+    /** Add an event to the span */
+    addEvent(name: string, attributes?: SpanAttributes): void;
+    /** End the span */
+    end(): void;
+    /** Get the underlying OTEL span (if available) */
+    getSpan(): Span | null;
+}
+/**
+ * Skillsmith Tracer - Wrapper for OpenTelemetry tracing
+ */
+export declare class SkillsmithTracer {
+    private tracer;
+    private initialized;
+    private enabled;
+    private config;
+    private sdkInstance;
+    constructor(config?: TracerConfig);
+    /**
+     * Initialize the tracer
+     * Must be called before creating spans
+     */
+    initialize(): Promise<void>;
+    /**
+     * Check if tracing is enabled
+     */
+    isEnabled(): boolean;
+    /**
+     * Start a new span
+     *
+     * @param name - Span name (e.g., 'mcp.tool.search', 'db.query')
+     * @param options - Span options
+     * @returns SpanWrapper for manipulating the span
+     */
+    startSpan(name: string, options?: SpanOptions): SpanWrapper;
+    /**
+     * Execute a function within a span context
+     *
+     * @param name - Span name
+     * @param fn - Function to execute
+     * @param options - Span options
+     * @returns Result of the function
+     */
+    withSpan<T>(name: string, fn: (span: SpanWrapper) => Promise<T>, options?: SpanOptions): Promise<T>;
+    /**
+     * Execute a synchronous function within a span context
+     */
+    withSpanSync<T>(name: string, fn: (span: SpanWrapper) => T, options?: SpanOptions): T;
+    /**
+     * Get the current active span (if any)
+     */
+    getCurrentSpan(): SpanWrapper;
+    /**
+     * Shutdown the tracer and flush pending spans
+     */
+    shutdown(): Promise<void>;
+}
+/**
+ * Get the default tracer instance
+ */
+export declare function getTracer(): SkillsmithTracer;
+/**
+ * Initialize the default tracer
+ * Should be called at application startup
+ */
+export declare function initializeTracing(config?: TracerConfig): Promise<SkillsmithTracer>;
+/**
+ * Shutdown the default tracer
+ * Should be called at application shutdown
+ */
+export declare function shutdownTracing(): Promise<void>;
+/**
+ * Decorator for tracing async methods
+ */
+export declare function traced(spanName?: string): <T extends (...args: unknown[]) => Promise<unknown>>(target: unknown, propertyKey: string, descriptor: TypedPropertyDescriptor<T>) => TypedPropertyDescriptor<T>;
+export {};
+//# sourceMappingURL=tracer.d.ts.map

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

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