@gravito/ripple 3.1.0 → 4.0.1

package/dist/core/src/instrumentation/types.d.ts

@@ -0,0 +1,182 @@
+/**
+ * @gravito/core - OpenTelemetry 類型定義
+ *
+ * 定義 OpenTelemetry SDK 集成所需的類型與介面。
+ */
+/**
+ * Tracing（追蹤）導出器類型
+ */
+export type TracingExporter = 'jaeger' | 'otlp' | 'console' | 'none';
+/**
+ * Metrics（指標）導出器類型
+ */
+export type MetricsExporter = 'prometheus' | 'otlp' | 'console' | 'none';
+/**
+ * Tracing 配置選項
+ */
+export interface TracingConfig {
+    /** 是否啟用追蹤（預設：true） */
+    enabled?: boolean;
+    /** 導出器類型（預設：otlp） */
+    exporter?: TracingExporter;
+    /** Jaeger HTTP 端點（使用 jaeger 導出器時） */
+    jaegerEndpoint?: string;
+    /** OTLP 端點（使用 otlp 導出器時） */
+    otlpEndpoint?: string;
+    /** 採樣率（0-1，預設：1.0 = 100%） */
+    samplingRate?: number;
+    /** 是否啟用自動儀器化（預設：false） */
+    autoInstrumentation?: boolean;
+    /** Batch Span Processor 配置 */
+    batchConfig?: {
+        /** 最大批次大小（預設：512） */
+        maxExportBatchSize?: number;
+        /** 導出間隔（毫秒，預設：5000） */
+        scheduledDelayMillis?: number;
+        /** 導出超時（毫秒，預設：30000） */
+        exportTimeoutMillis?: number;
+        /** 最大隊列大小（預設：2048） */
+        maxQueueSize?: number;
+    };
+}
+/**
+ * Metrics 配置選項
+ */
+export interface MetricsConfig {
+    /** 是否啟用指標（預設：true） */
+    enabled?: boolean;
+    /** 導出器類型（預設：otlp） */
+    exporter?: MetricsExporter;
+    /** Prometheus 端口（使用 prometheus 導出器時，預設：9090） */
+    prometheusPort?: number;
+    /** Prometheus 端點路徑（預設：/metrics） */
+    prometheusEndpoint?: string;
+    /** OTLP 端點（使用 otlp 導出器時） */
+    otlpEndpoint?: string;
+    /** 導出間隔（毫秒，預設：60000） */
+    exportIntervalMillis?: number;
+}
+/**
+ * OpenTelemetry SDK 完整配置
+ */
+export interface OpenTelemetryConfig {
+    /** 是否啟用 OpenTelemetry（預設：true） */
+    enabled?: boolean;
+    /** 服務名稱（預設：gravito-app） */
+    serviceName?: string;
+    /** 服務版本（預設：1.0.0） */
+    serviceVersion?: string;
+    /** 環境名稱（預設：development） */
+    environment?: 'development' | 'staging' | 'production' | string;
+    /** 自定義 Resource Attributes */
+    resourceAttributes?: Record<string, string | number | boolean>;
+    /** Tracing 配置 */
+    tracing?: TracingConfig;
+    /** Metrics 配置 */
+    metrics?: MetricsConfig;
+    /** 是否在控制台輸出初始化日誌（預設：true） */
+    logInitialization?: boolean;
+}
+/**
+ * OpenTelemetry SDK 實例包裝
+ *
+ * 封裝初始化後的 SDK 實例與相關資源。
+ */
+export interface OpenTelemetrySDK {
+    /** SDK 是否已啟動 */
+    isStarted: boolean;
+    /** SDK 是否已關閉 */
+    isShutdown: boolean;
+    /** 服務名稱 */
+    serviceName: string;
+    /** 服務版本 */
+    serviceVersion: string;
+    /** Tracer Provider（如果啟用追蹤） */
+    tracerProvider: unknown | null;
+    /** Meter Provider（如果啟用指標） */
+    meterProvider: unknown | null;
+    /** 原始配置 */
+    config: OpenTelemetryConfig;
+    /** 關閉 SDK */
+    shutdown: () => Promise<void>;
+}
+/**
+ * 支援的 OpenTelemetry 環境變數
+ *
+ * 參考：https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/
+ */
+export declare const OTEL_ENV_VARS: {
+    /** 服務名稱 */
+    readonly SERVICE_NAME: "OTEL_SERVICE_NAME";
+    /** 服務版本 */
+    readonly SERVICE_VERSION: "OTEL_SERVICE_VERSION";
+    /** 環境名稱 */
+    readonly DEPLOYMENT_ENVIRONMENT: "OTEL_DEPLOYMENT_ENVIRONMENT";
+    /** Resource Attributes */
+    readonly RESOURCE_ATTRIBUTES: "OTEL_RESOURCE_ATTRIBUTES";
+    /** OTLP 端點（通用） */
+    readonly OTLP_ENDPOINT: "OTEL_EXPORTER_OTLP_ENDPOINT";
+    /** OTLP Traces 端點 */
+    readonly OTLP_TRACES_ENDPOINT: "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT";
+    /** OTLP Metrics 端點 */
+    readonly OTLP_METRICS_ENDPOINT: "OTEL_EXPORTER_OTLP_METRICS_ENDPOINT";
+    /** 採樣器類型 */
+    readonly TRACES_SAMPLER: "OTEL_TRACES_SAMPLER";
+    /** 採樣率參數 */
+    readonly TRACES_SAMPLER_ARG: "OTEL_TRACES_SAMPLER_ARG";
+    /** 是否啟用 OpenTelemetry */
+    readonly GRAVITO_ENABLED: "GRAVITO_OTEL_ENABLED";
+    /** Jaeger 端點 */
+    readonly JAEGER_ENDPOINT: "JAEGER_ENDPOINT";
+    /** Prometheus 端口 */
+    readonly PROMETHEUS_PORT: "PROMETHEUS_PORT";
+};
+/**
+ * 完整的 BatchConfig 類型（所有屬性必填）
+ */
+export interface BatchConfigRequired {
+    maxExportBatchSize: number;
+    scheduledDelayMillis: number;
+    exportTimeoutMillis: number;
+    maxQueueSize: number;
+}
+/**
+ * 完整的 TracingConfig 類型（所有屬性必填）
+ */
+export interface TracingConfigRequired {
+    enabled: boolean;
+    exporter: TracingExporter;
+    jaegerEndpoint: string;
+    otlpEndpoint: string;
+    samplingRate: number;
+    autoInstrumentation: boolean;
+    batchConfig: BatchConfigRequired;
+}
+/**
+ * 完整的 MetricsConfig 類型（所有屬性必填）
+ */
+export interface MetricsConfigRequired {
+    enabled: boolean;
+    exporter: MetricsExporter;
+    prometheusPort: number;
+    prometheusEndpoint: string;
+    otlpEndpoint: string;
+    exportIntervalMillis: number;
+}
+/**
+ * 完整的 OpenTelemetryConfig 類型（所有屬性必填）
+ */
+export interface OpenTelemetryConfigRequired {
+    enabled: boolean;
+    serviceName: string;
+    serviceVersion: string;
+    environment: 'development' | 'staging' | 'production';
+    resourceAttributes: Record<string, string | number | boolean>;
+    tracing: TracingConfigRequired;
+    metrics: MetricsConfigRequired;
+    logInitialization: boolean;
+}
+/**
+ * 預設配置值
+ */
+export declare const DEFAULT_CONFIG: OpenTelemetryConfigRequired;

package/dist/core/src/observability/Metrics.d.ts

@@ -0,0 +1,244 @@
+/**
+ * @gravito/core - Prometheus Metrics Setup
+ *
+ * 設置和導出 Prometheus 指標，用於性能監控。
+ */
+/**
+ * Prometheus 指標配置
+ */
+export interface PrometheusMetricsConfig {
+    /** Prometheus 抓取端口 */
+    port?: number;
+    /** 指標前綴 */
+    prefix?: string;
+    /** 上報間隔（毫秒） */
+    interval?: number;
+    /** 是否啟用默認指標（如內存、CPU） */
+    defaultMetrics?: boolean;
+}
+/**
+ * Prometheus 指標導出器
+ *
+ * 將 Gravito 事件系統的指標導出到 Prometheus
+ *
+ * @example
+ * ```typescript
+ * import { setupPrometheusMetrics } from '@gravito/core/observability'
+ *
+ * const exporter = await setupPrometheusMetrics({
+ *   port: 9090,
+ *   prefix: 'gravito_event_'
+ * })
+ * ```
+ *
+ * @public
+ */
+export declare function setupPrometheusMetrics(config?: PrometheusMetricsConfig): Promise<{
+    port: number;
+    endpoint: string;
+} | null>;
+/**
+ * 事件系統指標定義
+ *
+ * 這些指標用於監控事件派發系統的性能和可靠性。
+ *
+ * @public
+ */
+export interface EventMetricsDefinition {
+    /** 事件派發延遲（直方圖） */
+    dispatchLatency: {
+        name: string;
+        help: string;
+        labels: string[];
+        buckets: number[];
+    };
+    /** 監聽器執行時間（直方圖） */
+    listenerExecutionTime: {
+        name: string;
+        help: string;
+        labels: string[];
+        buckets: number[];
+    };
+    /** 隊列深度（量表） */
+    queueDepth: {
+        name: string;
+        help: string;
+        labels: string[];
+    };
+    /** 失敗計數（計數器） */
+    failureRate: {
+        name: string;
+        help: string;
+        labels: string[];
+    };
+    /** 超時計數（計數器） */
+    timeoutCount: {
+        name: string;
+        help: string;
+        labels: string[];
+    };
+    /** 吞吐量（計數器） */
+    throughput: {
+        name: string;
+        help: string;
+        labels: string[];
+    };
+    /** 熔斷器狀態（量表） */
+    circuitBreakerState: {
+        name: string;
+        help: string;
+        labels: string[];
+    };
+    /** 熔斷器狀態轉換（計數器） */
+    circuitBreakerTransitions: {
+        name: string;
+        help: string;
+        labels: string[];
+    };
+    /** 熔斷器失敗計數（計數器） */
+    circuitBreakerFailures: {
+        name: string;
+        help: string;
+        labels: string[];
+    };
+    /** 熔斷器成功計數（計數器） */
+    circuitBreakerSuccesses: {
+        name: string;
+        help: string;
+        labels: string[];
+    };
+    /** 熔斷器 OPEN 持續時間（直方圖） */
+    circuitBreakerOpenDuration: {
+        name: string;
+        help: string;
+        labels: string[];
+        buckets: number[];
+    };
+}
+/**
+ * 獲取事件系統的標準指標定義
+ *
+ * @param prefix - 指標名稱前綴（默認：gravito_event_）
+ * @returns 指標定義對象
+ *
+ * @example
+ * ```typescript
+ * import { getEventMetricsDefinition } from '@gravito/core/observability'
+ *
+ * const metrics = getEventMetricsDefinition('gravito_event_')
+ * console.log(metrics.dispatchLatency.name)  // gravito_event_dispatch_latency_seconds
+ * ```
+ *
+ * @public
+ */
+export declare function getEventMetricsDefinition(prefix?: string): EventMetricsDefinition;
+/**
+ * Prometheus 查詢範例
+ *
+ * 提供常用的 Prometheus 查詢語句，用於監控事件系統
+ *
+ * @public
+ */
+export declare const PROMETHEUS_QUERIES: {
+    /** 事件派發延遲 P95 */
+    dispatchLatencyP95: string;
+    /** 事件派發延遲 P99 */
+    dispatchLatencyP99: string;
+    /** 隊列深度（按優先級） */
+    queueDepthByPriority: string;
+    /** 吞吐量（事件/秒） */
+    throughput: string;
+    /** 失敗率 */
+    failureRate: string;
+    /** 監聽器執行時間 P99 */
+    listenerLatencyP99: string;
+    /** 超時次數 */
+    timeoutCount: string;
+    /** 吞吐量異常檢測 */
+    throughputAnomaly: string;
+    /** 熔斷器狀態（0=CLOSED, 1=HALF_OPEN, 2=OPEN） */
+    circuitBreakerState: string;
+    /** 熔斷器開啟率 */
+    circuitBreakerOpenRate: string;
+    /** 熔斷器恢復率 */
+    circuitBreakerRecoveryRate: string;
+    /** 熔斷器失敗率 */
+    circuitBreakerFailureRate: string;
+    /** 熔斷器 OPEN 持續時間 P95 */
+    circuitBreakerOpenDurationP95: string;
+    /** 熔斷器 OPEN 持續時間 P99 */
+    circuitBreakerOpenDurationP99: string;
+};
+/**
+ * Prometheus 告警規則
+ *
+ * 提供預定義的告警規則，用於監控事件系統的健康狀況
+ *
+ * @public
+ */
+export declare const PROMETHEUS_ALERT_RULES: {
+    /** P99 延遲過高 */
+    HighDispatchLatency: {
+        expr: string;
+        for: string;
+        severity: string;
+        summary: string;
+        description: string;
+    };
+    /** 隊列深度過高 */
+    HighQueueDepth: {
+        expr: string;
+        for: string;
+        severity: string;
+        summary: string;
+        description: string;
+    };
+    /** 失敗率過高 */
+    HighFailureRate: {
+        expr: string;
+        for: string;
+        severity: string;
+        summary: string;
+        description: string;
+    };
+    /** 監聽器執行時間過長 */
+    SlowListener: {
+        expr: string;
+        for: string;
+        severity: string;
+        summary: string;
+        description: string;
+    };
+    /** 吞吐量異常下降 */
+    ThroughputDrop: {
+        expr: string;
+        for: string;
+        severity: string;
+        summary: string;
+        description: string;
+    };
+    /** 熔斷器持續開啟 */
+    CircuitBreakerOpen: {
+        expr: string;
+        for: string;
+        severity: string;
+        summary: string;
+        description: string;
+    };
+    /** 熔斷器頻繁切換 */
+    CircuitBreakerFlapping: {
+        expr: string;
+        for: string;
+        severity: string;
+        summary: string;
+        description: string;
+    };
+    /** 熔斷器故障率過高 */
+    CircuitBreakerHighFailureRate: {
+        expr: string;
+        for: string;
+        severity: string;
+        summary: string;
+        description: string;
+    };
+};

package/dist/core/src/observability/QueueDashboard.d.ts

@@ -0,0 +1,136 @@
+import type { DeadLetterQueue } from '../events/DeadLetterQueue';
+import type { EventPriorityQueue } from '../events/EventPriorityQueue';
+import type { MessageQueueBridge } from '../events/MessageQueueBridge';
+import type { WorkerPool } from '../events/WorkerPool';
+import type { HookManager } from '../HookManager';
+/**
+ * Configuration for QueueDashboard
+ * All subsystem references are optional to support progressive integration
+ */
+export interface QueueDashboardConfig {
+    eventQueue?: EventPriorityQueue;
+    workerPool?: WorkerPool;
+    hookManager?: HookManager;
+    dlq?: DeadLetterQueue;
+    messageQueueBridge?: MessageQueueBridge;
+}
+/**
+ * Queue depth and backpressure metrics
+ */
+export interface QueueMetrics {
+    depth: {
+        total: number;
+        high: number;
+        normal: number;
+        low: number;
+    };
+    backpressure: {
+        state: string;
+        rejectedCount: number;
+        degradedCount: number;
+        enqueueRate: number;
+    };
+    processing: boolean;
+}
+/**
+ * Worker pool and thread statistics
+ */
+export interface WorkerMetrics {
+    poolSize: number;
+    activeWorkers: number;
+    utilization: number;
+    queueDepth: number;
+    totalProcessed: number;
+    totalSuccess: number;
+    totalFailures: number;
+    successRate: number;
+    workers: Array<{
+        id: string;
+        state: string;
+        tasksProcessed: number;
+        tasksSucceeded: number;
+        tasksFailed: number;
+        avgDurationMs: number;
+        currentLoad: number;
+    }>;
+}
+/**
+ * Timeline event for job processing history
+ */
+export interface JobEvent {
+    id: string;
+    hook: string;
+    status: 'pending' | 'processing' | 'completed' | 'failed' | 'in_dlq';
+    priority: string;
+    createdAt: number;
+    error?: string;
+    retryCount: number;
+}
+/**
+ * Error statistics and circuit breaker status
+ */
+export interface ErrorStats {
+    totalErrors: number;
+    byEvent: Record<string, number>;
+    circuitBreakers: Array<{
+        eventName: string;
+        state: string;
+        failures: number;
+        successes: number;
+    }>;
+    dlqCount: number;
+}
+/**
+ * Complete dashboard snapshot at a point in time
+ */
+export interface DashboardSnapshot {
+    timestamp: number;
+    queue: QueueMetrics;
+    workers: WorkerMetrics;
+    timeline: JobEvent[];
+    errors: ErrorStats;
+}
+/**
+ * QueueDashboard aggregates metrics from all event processing subsystems
+ * Uses Facade pattern to read-only aggregate data without modifying subsystems
+ */
+export declare class QueueDashboard {
+    private readonly config;
+    constructor(config: QueueDashboardConfig);
+    /**
+     * Get current queue metrics (depth, backpressure state, enqueue rate)
+     */
+    getQueueMetrics(): QueueMetrics;
+    /**
+     * Get current worker pool metrics (size, utilization, success rate)
+     */
+    getWorkerMetrics(): WorkerMetrics;
+    /**
+     * Get job event timeline from DLQ entries (recent failures)
+     * @param limit Maximum number of entries to return (default: 50)
+     */
+    getJobTimeline(limit?: number): JobEvent[];
+    /**
+     * Get error statistics including circuit breaker status and DLQ counts
+     */
+    getErrorBreakdown(): ErrorStats;
+    /**
+     * Export metrics in JSON or Prometheus format
+     * @param format Export format: 'json' or 'prometheus'
+     */
+    exportMetrics(format: 'json' | 'prometheus'): string;
+    /**
+     * Get complete snapshot of all metrics at a point in time
+     */
+    getSnapshot(options?: {
+        timelineLimit?: number;
+    }): DashboardSnapshot;
+    /**
+     * Format metrics in Prometheus/OpenMetrics text format
+     */
+    private formatPrometheus;
+    /**
+     * Escape special characters in Prometheus labels
+     */
+    private escapePrometheusLabel;
+}