@zucker-framework/monitoring 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,502 @@
+import { OnModuleInit, OnModuleDestroy } from '@nestjs/common';
+import { EventEmitter2 } from '@nestjs/event-emitter';
+
+interface TrackedError {
+    id: string;
+    message: string;
+    stack?: string;
+    category: string;
+    count: number;
+    firstOccurrence: Date;
+    lastOccurrence: Date;
+    metadata?: Record<string, unknown>;
+}
+declare class ErrorTracker {
+    private readonly logger;
+    private errors;
+    private counter;
+    track(error: Error, category?: string, metadata?: Record<string, unknown>): void;
+    getErrors(): TrackedError[];
+    getErrorsByCategory(category: string): TrackedError[];
+    getTopErrors(limit?: number): TrackedError[];
+    clear(): void;
+    clearCategory(category: string): void;
+}
+
+/**
+ * Vendor-neutral context attached to an error report.
+ *
+ * Applications should pass identifiers and low-cardinality diagnostics only.
+ * Product text, prompts, credentials, and other sensitive payloads must be
+ * removed by the application or provider adapter before transmission.
+ */
+interface ErrorContext {
+    requestId?: string;
+    userId?: string;
+    resourceId?: string;
+    [key: string]: unknown;
+}
+interface ErrorReporterUser {
+    id: string;
+    email?: string;
+}
+/** Stable Nest injection token, including when duplicate package copies exist. */
+declare const ERROR_REPORTER: unique symbol;
+/**
+ * Provider-neutral error reporting port.
+ *
+ * Sentry, Datadog, Rollbar, or an internal collector belongs behind this port;
+ * the framework intentionally does not depend on any vendor SDK.
+ */
+interface ErrorReporter {
+    captureException(error: unknown, context?: ErrorContext): void;
+    captureMessage(message: string, context?: ErrorContext): void;
+    setUser(user: ErrorReporterUser | null): void;
+}
+/** Safe default for disabled or unconfigured production integrations. */
+declare class NoopErrorReporter implements ErrorReporter {
+    captureException(): void;
+    captureMessage(): void;
+    setUser(): void;
+}
+
+declare enum HealthStatus {
+    UP = "UP",
+    DOWN = "DOWN",
+    DEGRADED = "DEGRADED"
+}
+interface HealthCheck {
+    name: string;
+    status: HealthStatus;
+    details: Record<string, unknown>;
+    timestamp: Date;
+}
+interface HealthIndicator {
+    name: string;
+    check(): Promise<HealthCheck>;
+}
+declare class HealthCheckService {
+    private readonly logger;
+    private indicators;
+    registerIndicator(indicator: HealthIndicator): void;
+    unregisterIndicator(name: string): void;
+    checkAll(): Promise<{
+        status: HealthStatus;
+        checks: HealthCheck[];
+        timestamp: Date;
+    }>;
+    check(name: string): Promise<HealthCheck | undefined>;
+}
+
+interface MeasurementDefinition {
+    id: string;
+    name: string;
+    dimensions: string[];
+}
+interface MeasurementProvider {
+    getDefinitions(): MeasurementDefinition[];
+    getMeasurements(definitionId: string): Promise<Record<string, unknown>[]>;
+}
+interface MetricPoint {
+    name: string;
+    value: number;
+    tags: Record<string, string>;
+    timestamp: Date;
+}
+interface MetricsCollector {
+    increment(name: string, tags?: Record<string, string>): void;
+    gauge(name: string, value: number, tags?: Record<string, string>): void;
+    histogram(name: string, value: number, tags?: Record<string, string>): void;
+    getMetrics(): MetricPoint[];
+}
+declare class InMemoryMetricsCollector implements MetricsCollector {
+    private metrics;
+    private static sortedTagsKey;
+    increment(name: string, tags?: Record<string, string>): void;
+    gauge(name: string, value: number, tags?: Record<string, string>): void;
+    histogram(name: string, value: number, tags?: Record<string, string>): void;
+    getMetrics(): MetricPoint[];
+    clear(): void;
+}
+
+interface MetricLabels {
+    [key: string]: string;
+}
+/**
+ * 计数器 — 只增不减
+ */
+declare class Counter {
+    readonly name: string;
+    readonly description: string;
+    private values;
+    constructor(name: string, description: string);
+    increment(labels?: MetricLabels, amount?: number): void;
+    get(labels?: MetricLabels): number;
+    getAll(): Array<{
+        labels: MetricLabels;
+        value: number;
+    }>;
+    private labelsKey;
+    private parseKey;
+}
+/**
+ * 仪表 — 可增可减
+ */
+declare class Gauge {
+    readonly name: string;
+    readonly description: string;
+    private values;
+    constructor(name: string, description: string);
+    set(value: number, labels?: MetricLabels): void;
+    get(labels?: MetricLabels): number;
+    increment(labels?: MetricLabels, amount?: number): void;
+    decrement(labels?: MetricLabels, amount?: number): void;
+    getAll(): Array<{
+        labels: MetricLabels;
+        value: number;
+    }>;
+    private labelsKey;
+    private parseKey;
+}
+/**
+ * 直方图 — 观测值分布
+ */
+declare class Histogram {
+    readonly name: string;
+    readonly description: string;
+    readonly buckets: number[];
+    private readonly maxSamples;
+    private observations;
+    constructor(name: string, description: string, buckets?: number[], maxSamples?: number);
+    observe(value: number, labels?: MetricLabels): void;
+    getPercentile(percentile: number, labels?: MetricLabels): number;
+    getCount(labels?: MetricLabels): number;
+    getSum(labels?: MetricLabels): number;
+    getAll(): Array<{
+        labels: MetricLabels;
+        count: number;
+        sum: number;
+        bucketCounts: Record<string, number>;
+    }>;
+    private labelsKey;
+    private parseKey;
+}
+/**
+ * 计时器 — 专门记录耗时
+ */
+declare class Timer {
+    readonly name: string;
+    readonly description: string;
+    private histogram;
+    constructor(name: string, description: string);
+    /**
+     * 记录一次耗时（秒）
+     */
+    record(durationSeconds: number, labels?: MetricLabels): void;
+    /**
+     * 开始计时，返回结束函数
+     */
+    startTimer(labels?: MetricLabels): () => number;
+    getHistogram(): Histogram;
+}
+/**
+ * Summary — 计算分位数（类似 Prometheus summary 类型）
+ */
+declare class Summary {
+    readonly name: string;
+    readonly description: string;
+    readonly quantiles: number[];
+    /** 观测值最大保留时间（毫秒），默认 10 分钟 */
+    private readonly maxAgeMs;
+    private readonly maxSamples;
+    private observations;
+    constructor(name: string, description: string, quantiles?: number[], 
+    /** 观测值最大保留时间（毫秒），默认 10 分钟 */
+    maxAgeMs?: number, maxSamples?: number);
+    observe(value: number, labels?: MetricLabels): void;
+    getQuantile(quantile: number, labels?: MetricLabels): number;
+    getCount(labels?: MetricLabels): number;
+    getSum(labels?: MetricLabels): number;
+    getAll(): Array<{
+        labels: MetricLabels;
+        count: number;
+        sum: number;
+        quantileValues: Record<string, number>;
+    }>;
+    private prune;
+    private labelsKey;
+    private parseKey;
+}
+/**
+ * 指标注册中心
+ */
+declare class MetricsRegistry {
+    private counters;
+    private gauges;
+    private histograms;
+    private timers;
+    private summaries;
+    counter(name: string, description?: string): Counter;
+    gauge(name: string, description?: string): Gauge;
+    histogram(name: string, description?: string, buckets?: number[]): Histogram;
+    timer(name: string, description?: string): Timer;
+    summary(name: string, description?: string, quantiles?: number[]): Summary;
+    getCounters(): Counter[];
+    getGauges(): Gauge[];
+    getHistograms(): Histogram[];
+    getTimers(): Timer[];
+    getSummaries(): Summary[];
+    /**
+     * 重置所有指标
+     */
+    clear(): void;
+}
+
+interface MetricsOptions {
+    /** 可选的注入 registry 实例 */
+    registry?: MetricsRegistry;
+    /** 静态标签，附加到每个指标 */
+    labels?: MetricLabels;
+    /** 是否记录错误次数（默认 true） */
+    trackErrors?: boolean;
+    /** 是否记录活跃请求数（默认 false） */
+    trackActiveRequests?: boolean;
+}
+/**
+ * @Metrics 方法装饰器 — 自动记录调用次数、耗时、错误数
+ *
+ * @param name 指标名称前缀
+ * @param options 可选配置
+ */
+declare function Metrics(name: string, options?: MetricsOptions): MethodDecorator;
+
+interface SystemMetricsOptions {
+    /** 采集间隔（毫秒），默认 15000 */
+    intervalMs?: number;
+    /** 是否启用，默认 true */
+    enabled?: boolean;
+    /** 采集前缀，默认无 */
+    prefix?: string;
+}
+/**
+ * 系统指标采集器：CPU、内存、进程 uptime、事件循环延迟、GC、活跃句柄
+ */
+declare class SystemMetricsCollector implements OnModuleInit, OnModuleDestroy {
+    private readonly registry;
+    private intervalHandle;
+    private options;
+    private lastCpuUsage;
+    private lastCpuUsageTime;
+    constructor(registry: MetricsRegistry);
+    configure(options: SystemMetricsOptions): void;
+    onModuleInit(): void;
+    onModuleDestroy(): void;
+    private metricName;
+    collect(): void;
+    private collectCpuMetrics;
+    private collectMemoryMetrics;
+    private collectProcessMetrics;
+    private collectUptimeMetrics;
+    private measureEventLoopDelay;
+    private collectHandleMetrics;
+}
+
+/** Render a registry without requiring an HTTP server or Nest controller. */
+declare function renderPrometheusMetrics(registry: MetricsRegistry): string;
+/**
+ * Prometheus 格式指标导出端点
+ */
+declare class PrometheusExporter {
+    private readonly registry;
+    constructor(registry: MetricsRegistry);
+    getMetrics(): string;
+}
+
+declare const METRICS_COLLECTOR: unique symbol;
+declare class ZuckerMonitoringModule {
+}
+
+declare const HEALTH_OPTIONS: unique symbol;
+interface HealthOptions {
+    /** 自定义 /health 路径前缀，默认 'health' */
+    prefix?: string;
+}
+/**
+ * 健康检查控制器
+ *
+ * 提供以下端点：
+ * - GET /health       — 完整健康检查
+ * - GET /health/live  — K8s liveness 探针（仅检查进程存活）
+ * - GET /health/ready — K8s readiness 探针（检查所有依赖）
+ */
+declare class HealthController {
+    private readonly healthCheckService;
+    private readonly startedAtMs;
+    constructor(healthCheckService: HealthCheckService);
+    check(res: any): Promise<void>;
+    /**
+     * K8s liveness 探针 — 仅检查进程是否存活
+     */
+    live(res: any): void;
+    /**
+     * K8s readiness 探针 — 检查所有依赖是否就绪
+     */
+    ready(res: any): Promise<void>;
+    private formatChecks;
+}
+
+interface ProcessUptimeSnapshot {
+    uptimeMs: number;
+    uptimeSeconds: number;
+}
+/** Return a non-negative process duration with explicit units. */
+declare function getProcessUptime(startedAtMs: number, nowMs?: number): ProcessUptimeSnapshot;
+
+type AlertSeverity = 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL';
+type AlertStatus = 'ACTIVE' | 'ACKNOWLEDGED' | 'RESOLVED';
+interface AlertRule {
+    id: string;
+    name: string;
+    metric: string;
+    condition: '>' | '>=' | '<' | '<=' | '==' | '!=';
+    threshold: number;
+    /** 持续违规秒数，超过后触发告警 */
+    duration: number;
+    severity: AlertSeverity;
+    enabled: boolean;
+    /** 通知渠道标识列表 */
+    notifyChannels?: string[];
+}
+interface AlertRecord {
+    id: string;
+    ruleId: string;
+    ruleName: string;
+    metric: string;
+    value: number;
+    threshold: number;
+    severity: AlertSeverity;
+    status: AlertStatus;
+    message: string;
+    triggeredAt: number;
+    acknowledgedAt?: number;
+    resolvedAt?: number;
+    acknowledgedBy?: string;
+    resolvedBy?: string;
+}
+
+declare class AlertManagerService implements OnModuleInit {
+    private readonly eventEmitter?;
+    private readonly db?;
+    private readonly logger;
+    /** 已注册的告警规则 */
+    private readonly rules;
+    /** 所有告警记录（含历史） */
+    private readonly alerts;
+    /** 每条规则的持续违规状态 */
+    private readonly violations;
+    /** 活跃告警的 ruleId 索引（非 RESOLVED 状态的告警） */
+    private readonly activeRuleIds;
+    constructor(eventEmitter?: EventEmitter2, db?: any | undefined);
+    onModuleInit(): Promise<void>;
+    registerRule(rule: AlertRule): void;
+    removeRule(ruleId: string): boolean;
+    getRules(): AlertRule[];
+    getRule(ruleId: string): AlertRule | undefined;
+    /**
+     * 对一组指标快照评估所有已启用规则。
+     * 应由调度器（如 Cron / Interval）定期调用。
+     */
+    evaluate(metrics: Record<string, number>): AlertRecord[];
+    getAlerts(): AlertRecord[];
+    getActiveAlerts(): AlertRecord[];
+    getAlert(alertId: string): AlertRecord | undefined;
+    acknowledgeAlert(alertId: string, userId: string): AlertRecord | undefined;
+    resolveAlert(alertId: string, userId: string): AlertRecord | undefined;
+    private checkCondition;
+    private hasActiveAlertForRule;
+    private createAlert;
+    private autoResolveForRule;
+}
+
+/**
+ * AlertController — 告警管理接口
+ *
+ * 注意：本 Controller 不自带认证 Guard（monitoring 包不依赖 @zucker-framework/auth）。
+ * 应用层应通过以下方式之一保护这些端点：
+ * 1. 全局 APP_GUARD（推荐 — 在 main.ts 或 AppModule 中注册 JwtAuthGuard）
+ * 2. 在注册 ZuckerMonitoringModule 时，通过路由中间件添加认证
+ */
+declare class AlertController {
+    private readonly alertManager;
+    constructor(alertManager: AlertManagerService);
+    getAlerts(): AlertRecord[];
+    getRules(): AlertRule[];
+    createRule(body: AlertRule): AlertRule;
+    deleteRule(id: string): void;
+    acknowledgeAlert(id: string, userId: string): AlertRecord;
+    resolveAlert(id: string, userId: string): AlertRecord;
+}
+
+/**
+ * 请求级资源使用追踪
+ *
+ * 对标 Claude Code 的 cost-tracker.ts:
+ * 每次请求自动追踪数据库查询次数、缓存命中率、存储操作等。
+ *
+ * 用法:
+ * ```ts
+ * // 在中间件中初始化
+ * UsageTracker.runWithContext(async () => {
+ *   // 在 service 中记录
+ *   UsageTracker.track('db_query');
+ *   UsageTracker.track('cache_hit');
+ *
+ *   // 请求结束时获取汇总
+ *   const summary = UsageTracker.getSummary();
+ *   // → { db_query: 5, cache_hit: 2, cache_miss: 1, elapsed: 123 }
+ * });
+ * ```
+ */
+interface UsageMetrics {
+    [key: string]: number;
+}
+interface UsageSummary {
+    /** 各项指标的计数 */
+    metrics: UsageMetrics;
+    /** 请求开始时间 */
+    startTime: number;
+    /** 已用时间（毫秒） */
+    elapsed: number;
+}
+/**
+ * 轻量级请求级资源使用追踪器
+ */
+declare class UsageTracker {
+    private static readonly logger;
+    /**
+     * 在新的追踪上下文中执行函数
+     */
+    static runWithContext<T>(fn: () => T): T;
+    /**
+     * 记录一次资源使用
+     * @param type 资源类型（如 'db_query', 'cache_hit', 'cache_miss', 'storage_read', 'api_call'）
+     * @param amount 使用量（默认 1）
+     */
+    static track(type: string, amount?: number): void;
+    /**
+     * 获取指定类型的当前计数
+     */
+    static getCount(type: string): number;
+    /**
+     * 获取当前请求的使用汇总
+     */
+    static getSummary(): UsageSummary | undefined;
+    /**
+     * 检查是否在追踪上下文中
+     */
+    static isTracking(): boolean;
+    track(type: string, amount?: number): void;
+    getSummary(): UsageSummary | undefined;
+}
+
+export { AlertController, AlertManagerService, type AlertRecord, type AlertRule, type AlertSeverity, type AlertStatus, Counter, ERROR_REPORTER, type ErrorContext, type ErrorReporter, type ErrorReporterUser, ErrorTracker, Gauge, HEALTH_OPTIONS, type HealthCheck, HealthCheckService, HealthController, type HealthIndicator, type HealthOptions, HealthStatus, Histogram, InMemoryMetricsCollector, METRICS_COLLECTOR, type MeasurementDefinition, type MeasurementProvider, type MetricLabels, type MetricPoint, Metrics, type MetricsCollector, type MetricsOptions, MetricsRegistry, NoopErrorReporter, type ProcessUptimeSnapshot, PrometheusExporter, Summary, SystemMetricsCollector, type SystemMetricsOptions, Timer, type TrackedError, type UsageMetrics, type UsageSummary, UsageTracker, ZuckerMonitoringModule, getProcessUptime, renderPrometheusMetrics };