@zucker-framework/monitoring 1.0.0 → 1.0.5

package/README.md

@@ -0,0 +1,11 @@
+# Monitoring
+
+## Bounded error aggregation
+
+Configure `ErrorTracker` with `retentionMs` for a fixed window starting at first occurrence, optional fingerprint/redaction functions, `logEntries: false` for silent aggregation, and `onNewError` for host alert policy. Expiry is applied on reads and writes; no recurring timer or lifecycle provider is needed. `errorFingerprint` hashes the error name/message/first stack location and endpoint. Default consumers retain the original category/message aggregation and unlimited retention. External reporting remains behind `ErrorReporter`; product classifications, critical keywords and tracking enablement stay in the host.
+
+## Optional Sentry adapter and selected health probes
+
+`SentryErrorReporter` receives explicit SDK initialization options, selected redaction fields/sections and a context mapper. It loads `@sentry/node` only when configured and initializes once. The application owns its enablement decision, DSN, sampling, tags and sensitive field list. `ERROR_REPORTER` can still use `NoopErrorReporter`.
+
+`HealthCheckService.checkAll(names?)` reuses the existing status aggregation for readiness or diagnostics subsets. A requested but unregistered probe is DOWN. HTTP paths, status field naming and business metric queries stay with the application. `MetricsRegistry` plus `renderPrometheusMetrics` provide serialization without a second text renderer.

package/dist/index.d.mts

@@ -11,10 +11,25 @@ interface TrackedError {
     lastOccurrence: Date;
     metadata?: Record<string, unknown>;
 }
+interface ErrorTrackerOptions {
+    /** Fixed aggregation window from the first occurrence; omitted retains existing unbounded history. */
+    retentionMs?: number;
+    logEntries?: boolean;
+    fingerprint?: (error: Error, category: string, metadata?: Record<string, unknown>) => string;
+    sanitizeText?: (value: string) => string;
+    sanitizeMetadata?: (value: Record<string, unknown>) => Record<string, unknown>;
+    onNewError?: (error: Error, record: TrackedError) => void;
+}
+declare const ERROR_TRACKER_OPTIONS: unique symbol;
+/** Fingerprint without retaining raw stack locations or request paths as cache keys. */
+declare function errorFingerprint(error: Error, endpoint?: string): string;
 declare class ErrorTracker {
+    private readonly options;
     private readonly logger;
     private errors;
     private counter;
+    constructor(options?: ErrorTrackerOptions);
+    private prune;
     track(error: Error, category?: string, metadata?: Record<string, unknown>): void;
     getErrors(): TrackedError[];
     getErrorsByCategory(category: string): TrackedError[];
@@ -46,7 +61,7 @@ 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.
+ * provider adapters may load an explicitly configured optional vendor SDK.
  */
 interface ErrorReporter {
     captureException(error: unknown, context?: ErrorContext): void;
@@ -80,7 +95,8 @@ declare class HealthCheckService {
     private indicators;
     registerIndicator(indicator: HealthIndicator): void;
     unregisterIndicator(name: string): void;
-    checkAll(): Promise<{
+    /** Select a declared subset for readiness vs. diagnostics; absent indicators fail closed. */
+    checkAll(names?: readonly string[]): Promise<{
         status: HealthStatus;
         checks: HealthCheck[];
         timestamp: Date;
@@ -499,4 +515,60 @@ declare class UsageTracker {
     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 };
+type SentryEvent = Record<string, unknown>;
+interface SentryScopeContext {
+    tags?: Record<string, string>;
+    user?: ErrorReporterUser | null;
+    extra?: Record<string, unknown>;
+}
+interface SentryScopePort {
+    setTag(key: string, value: string): unknown;
+    setUser(user: ErrorReporterUser | null): unknown;
+    setExtra(key: string, value: unknown): unknown;
+}
+/** The adapter only relies on this subset of the optional Node SDK. */
+interface SentrySdkPort {
+    init(options: {
+        dsn: string;
+        environment?: string;
+        release?: string;
+        tracesSampleRate?: number;
+        beforeSend(event: SentryEvent): SentryEvent | null;
+    }): unknown;
+    withScope(callback: (scope: SentryScopePort) => void): unknown;
+    captureException(error: unknown): unknown;
+    captureMessage(message: string): unknown;
+    setUser(user: ErrorReporterUser | null): unknown;
+}
+interface SentryErrorReporterOptions {
+    dsn?: string;
+    environment?: string;
+    release?: string;
+    tracesSampleRate?: number;
+    /** Application field/section selection; traversal never changes the source event. */
+    redaction?: {
+        fields: readonly string[];
+        sections: readonly string[];
+        replacement?: string;
+    };
+    beforeSend?: (event: SentryEvent) => SentryEvent | null;
+    mapContext?: (context: ErrorContext, kind: 'exception' | 'message') => SentryScopeContext;
+    loadSdk?: () => Promise<SentrySdkPort>;
+    onUnavailable?: () => void;
+    onInitialized?: () => void;
+}
+/** Configured once by the application. Importing monitoring does not load Sentry. */
+declare class SentryErrorReporter implements ErrorReporter {
+    private readonly options;
+    private sdk?;
+    private initializing?;
+    constructor(options: SentryErrorReporterOptions);
+    onModuleInit(): Promise<void>;
+    private initialize;
+    captureException(error: unknown, context?: ErrorContext): void;
+    captureMessage(message: string, context?: ErrorContext): void;
+    setUser(user: ErrorReporterUser | null): void;
+    private applyContext;
+}
+
+export { AlertController, AlertManagerService, type AlertRecord, type AlertRule, type AlertSeverity, type AlertStatus, Counter, ERROR_REPORTER, ERROR_TRACKER_OPTIONS, type ErrorContext, type ErrorReporter, type ErrorReporterUser, ErrorTracker, type ErrorTrackerOptions, 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, SentryErrorReporter, type SentryErrorReporterOptions, type SentryEvent, type SentryScopeContext, type SentryScopePort, type SentrySdkPort, Summary, SystemMetricsCollector, type SystemMetricsOptions, Timer, type TrackedError, type UsageMetrics, type UsageSummary, UsageTracker, ZuckerMonitoringModule, errorFingerprint, getProcessUptime, renderPrometheusMetrics };

package/dist/index.d.ts

@@ -11,10 +11,25 @@ interface TrackedError {
     lastOccurrence: Date;
     metadata?: Record<string, unknown>;
 }
+interface ErrorTrackerOptions {
+    /** Fixed aggregation window from the first occurrence; omitted retains existing unbounded history. */
+    retentionMs?: number;
+    logEntries?: boolean;
+    fingerprint?: (error: Error, category: string, metadata?: Record<string, unknown>) => string;
+    sanitizeText?: (value: string) => string;
+    sanitizeMetadata?: (value: Record<string, unknown>) => Record<string, unknown>;
+    onNewError?: (error: Error, record: TrackedError) => void;
+}
+declare const ERROR_TRACKER_OPTIONS: unique symbol;
+/** Fingerprint without retaining raw stack locations or request paths as cache keys. */
+declare function errorFingerprint(error: Error, endpoint?: string): string;
 declare class ErrorTracker {
+    private readonly options;
     private readonly logger;
     private errors;
     private counter;
+    constructor(options?: ErrorTrackerOptions);
+    private prune;
     track(error: Error, category?: string, metadata?: Record<string, unknown>): void;
     getErrors(): TrackedError[];
     getErrorsByCategory(category: string): TrackedError[];
@@ -46,7 +61,7 @@ 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.
+ * provider adapters may load an explicitly configured optional vendor SDK.
  */
 interface ErrorReporter {
     captureException(error: unknown, context?: ErrorContext): void;
@@ -80,7 +95,8 @@ declare class HealthCheckService {
     private indicators;
     registerIndicator(indicator: HealthIndicator): void;
     unregisterIndicator(name: string): void;
-    checkAll(): Promise<{
+    /** Select a declared subset for readiness vs. diagnostics; absent indicators fail closed. */
+    checkAll(names?: readonly string[]): Promise<{
         status: HealthStatus;
         checks: HealthCheck[];
         timestamp: Date;
@@ -499,4 +515,60 @@ declare class UsageTracker {
     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 };
+type SentryEvent = Record<string, unknown>;
+interface SentryScopeContext {
+    tags?: Record<string, string>;
+    user?: ErrorReporterUser | null;
+    extra?: Record<string, unknown>;
+}
+interface SentryScopePort {
+    setTag(key: string, value: string): unknown;
+    setUser(user: ErrorReporterUser | null): unknown;
+    setExtra(key: string, value: unknown): unknown;
+}
+/** The adapter only relies on this subset of the optional Node SDK. */
+interface SentrySdkPort {
+    init(options: {
+        dsn: string;
+        environment?: string;
+        release?: string;
+        tracesSampleRate?: number;
+        beforeSend(event: SentryEvent): SentryEvent | null;
+    }): unknown;
+    withScope(callback: (scope: SentryScopePort) => void): unknown;
+    captureException(error: unknown): unknown;
+    captureMessage(message: string): unknown;
+    setUser(user: ErrorReporterUser | null): unknown;
+}
+interface SentryErrorReporterOptions {
+    dsn?: string;
+    environment?: string;
+    release?: string;
+    tracesSampleRate?: number;
+    /** Application field/section selection; traversal never changes the source event. */
+    redaction?: {
+        fields: readonly string[];
+        sections: readonly string[];
+        replacement?: string;
+    };
+    beforeSend?: (event: SentryEvent) => SentryEvent | null;
+    mapContext?: (context: ErrorContext, kind: 'exception' | 'message') => SentryScopeContext;
+    loadSdk?: () => Promise<SentrySdkPort>;
+    onUnavailable?: () => void;
+    onInitialized?: () => void;
+}
+/** Configured once by the application. Importing monitoring does not load Sentry. */
+declare class SentryErrorReporter implements ErrorReporter {
+    private readonly options;
+    private sdk?;
+    private initializing?;
+    constructor(options: SentryErrorReporterOptions);
+    onModuleInit(): Promise<void>;
+    private initialize;
+    captureException(error: unknown, context?: ErrorContext): void;
+    captureMessage(message: string, context?: ErrorContext): void;
+    setUser(user: ErrorReporterUser | null): void;
+    private applyContext;
+}
+
+export { AlertController, AlertManagerService, type AlertRecord, type AlertRule, type AlertSeverity, type AlertStatus, Counter, ERROR_REPORTER, ERROR_TRACKER_OPTIONS, type ErrorContext, type ErrorReporter, type ErrorReporterUser, ErrorTracker, type ErrorTrackerOptions, 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, SentryErrorReporter, type SentryErrorReporterOptions, type SentryEvent, type SentryScopeContext, type SentryScopePort, type SentrySdkPort, Summary, SystemMetricsCollector, type SystemMetricsOptions, Timer, type TrackedError, type UsageMetrics, type UsageSummary, UsageTracker, ZuckerMonitoringModule, errorFingerprint, getProcessUptime, renderPrometheusMetrics };