@gravito/monitor 1.0.0-beta.1

package/dist/index.d.ts

@@ -0,0 +1,516 @@
+import { GravitoContext, GravitoOrbit, PlanetCore } from 'gravito-core';
+
+/**
+ * @gravito/monitor - Configuration Types
+ */
+/**
+ * Health check result
+ */
+interface HealthCheckResult {
+    status: 'healthy' | 'unhealthy' | 'degraded';
+    message?: string;
+    latency?: number;
+    details?: Record<string, unknown>;
+}
+/**
+ * Health check function signature
+ */
+type HealthCheckFn = () => Promise<HealthCheckResult> | HealthCheckResult;
+/**
+ * Health configuration
+ */
+interface HealthConfig {
+    /** Enable health endpoints (default: true) */
+    enabled?: boolean;
+    /** Path for full health check (default: /health) */
+    path?: string;
+    /** Path for Kubernetes readiness probe (default: /ready) */
+    readyPath?: string;
+    /** Path for Kubernetes liveness probe (default: /live) */
+    livePath?: string;
+    /** Timeout for individual health checks in ms (default: 5000) */
+    timeout?: number;
+    /** Cache health check results for ms (default: 0 = no cache) */
+    cacheTtl?: number;
+}
+/**
+ * Metric definition options
+ */
+interface MetricOptions {
+    name: string;
+    help: string;
+    labels?: string[];
+    buckets?: number[];
+    percentiles?: number[];
+}
+/**
+ * Metrics configuration
+ */
+interface MetricsConfig {
+    /** Enable metrics endpoint (default: true) */
+    enabled?: boolean;
+    /** Path for metrics endpoint (default: /metrics) */
+    path?: string;
+    /** Collect default runtime metrics (default: true) */
+    defaultMetrics?: boolean;
+    /** Prefix for all metric names (default: gravito_) */
+    prefix?: string;
+    /** Custom labels to add to all metrics */
+    defaultLabels?: Record<string, string>;
+}
+/**
+ * Tracing configuration
+ */
+interface TracingConfig {
+    /** Enable tracing (default: false) */
+    enabled?: boolean;
+    /** Service name for tracing */
+    serviceName?: string;
+    /** Service version */
+    serviceVersion?: string;
+    /** OTLP endpoint URL (default: http://localhost:4318/v1/traces) */
+    endpoint?: string;
+    /** Sample rate 0.0 - 1.0 (default: 1.0) */
+    sampleRate?: number;
+    /** Additional resource attributes */
+    resourceAttributes?: Record<string, string>;
+    /** Trace HTTP requests automatically (default: true) */
+    traceHttp?: boolean;
+    /** Headers to propagate in traces */
+    propagateHeaders?: string[];
+}
+/**
+ * Monitor configuration
+ */
+interface MonitorConfig {
+    /** Health check configuration */
+    health?: HealthConfig;
+    /** Metrics configuration */
+    metrics?: MetricsConfig;
+    /** Tracing configuration */
+    tracing?: TracingConfig;
+}
+/**
+ * Define monitor configuration (type helper)
+ */
+declare function defineMonitorConfig(config: MonitorConfig): MonitorConfig;
+
+/**
+ * @gravito/monitor - Health Check Registry
+ *
+ * Manages health check registrations and executions
+ */
+
+interface HealthReport {
+    status: 'healthy' | 'unhealthy' | 'degraded';
+    timestamp: string;
+    uptime: number;
+    checks: Record<string, HealthCheckResult & {
+        name: string;
+    }>;
+}
+/**
+ * HealthRegistry manages all health checks
+ */
+declare class HealthRegistry {
+    private checks;
+    private startTime;
+    private cachedReport;
+    private cacheExpiry;
+    private timeout;
+    private cacheTtl;
+    constructor(config?: HealthConfig);
+    /**
+     * Register a health check
+     */
+    register(name: string, check: HealthCheckFn): this;
+    /**
+     * Unregister a health check
+     */
+    unregister(name: string): boolean;
+    /**
+     * Get all registered check names
+     */
+    getCheckNames(): string[];
+    /**
+     * Execute a single health check with timeout
+     */
+    private executeCheck;
+    /**
+     * Execute all health checks and generate report
+     */
+    check(): Promise<HealthReport>;
+    /**
+     * Simple liveness check (is the process running?)
+     */
+    liveness(): Promise<{
+        status: 'healthy' | 'unhealthy';
+    }>;
+    /**
+     * Readiness check (is the app ready to serve traffic?)
+     * By default, requires all checks to be healthy
+     */
+    readiness(): Promise<{
+        status: 'healthy' | 'unhealthy';
+        reason?: string;
+    }>;
+}
+
+/**
+ * @gravito/monitor - Health Controller
+ *
+ * HTTP handlers for health check endpoints
+ */
+
+/**
+ * HealthController handles health check HTTP endpoints
+ */
+declare class HealthController {
+    private registry;
+    constructor(registry: HealthRegistry);
+    /**
+     * GET /health - Full health check with all registered checks
+     */
+    health(c: GravitoContext): Promise<Response>;
+    /**
+     * GET /ready - Kubernetes readiness probe
+     * Returns 200 if ready to serve traffic, 503 otherwise
+     */
+    ready(c: GravitoContext): Promise<Response>;
+    /**
+     * GET /live - Kubernetes liveness probe
+     * Returns 200 if the process is alive
+     */
+    live(c: GravitoContext): Promise<Response>;
+}
+
+/**
+ * @gravito/monitor - Built-in Health Checks
+ */
+
+/**
+ * Create a database health check
+ */
+declare function createDatabaseCheck(connectionFn: () => Promise<boolean> | boolean): HealthCheckFn;
+/**
+ * Create a Redis health check
+ */
+declare function createRedisCheck(pingFn: () => Promise<string> | string): HealthCheckFn;
+/**
+ * Create a memory usage health check
+ */
+declare function createMemoryCheck(options?: {
+    maxHeapUsedPercent?: number;
+}): HealthCheckFn;
+/**
+ * Create a custom HTTP endpoint health check
+ */
+declare function createHttpCheck(url: string, options?: {
+    timeout?: number;
+    expectedStatus?: number;
+    method?: string;
+}): HealthCheckFn;
+/**
+ * Create a disk space health check
+ */
+declare function createDiskCheck(options?: {
+    path?: string;
+    minFreePercent?: number;
+}): HealthCheckFn;
+
+/**
+ * @gravito/monitor - Metrics Registry
+ *
+ * Manages metric collection and Prometheus exposition
+ */
+
+interface MetricValue {
+    value: number;
+    labels: Record<string, string>;
+    timestamp?: number;
+}
+/**
+ * Counter metric - monotonically increasing value
+ */
+declare class Counter {
+    readonly name: string;
+    readonly help: string;
+    readonly labelNames: string[];
+    private values;
+    constructor(name: string, help: string, labelNames?: string[]);
+    /**
+     * Increment the counter
+     */
+    inc(labels?: Record<string, string>, delta?: number): void;
+    /**
+     * Get current values
+     */
+    getValues(): MetricValue[];
+    /**
+     * Reset all values
+     */
+    reset(): void;
+    private labelsToKey;
+    private keyToLabels;
+}
+/**
+ * Gauge metric - value that can go up or down
+ */
+declare class Gauge {
+    readonly name: string;
+    readonly help: string;
+    readonly labelNames: string[];
+    private values;
+    constructor(name: string, help: string, labelNames?: string[]);
+    /**
+     * Set the gauge value
+     */
+    set(value: number, labels?: Record<string, string>): void;
+    /**
+     * Increment the gauge
+     */
+    inc(labels?: Record<string, string>, delta?: number): void;
+    /**
+     * Decrement the gauge
+     */
+    dec(labels?: Record<string, string>, delta?: number): void;
+    /**
+     * Get current values
+     */
+    getValues(): MetricValue[];
+    private labelsToKey;
+    private keyToLabels;
+}
+/**
+ * Histogram metric - tracks distribution of values
+ */
+declare class Histogram {
+    readonly name: string;
+    readonly help: string;
+    readonly labelNames: string[];
+    private bucketCounts;
+    private sums;
+    private counts;
+    readonly buckets: number[];
+    constructor(name: string, help: string, labelNames?: string[], buckets?: number[]);
+    /**
+     * Observe a value
+     */
+    observe(value: number, labels?: Record<string, string>): void;
+    /**
+     * Start a timer and return a function to stop it
+     */
+    startTimer(labels?: Record<string, string>): () => void;
+    /**
+     * Get values for Prometheus format
+     */
+    getValues(): {
+        buckets: Map<string, Map<number, number>>;
+        sums: Map<string, number>;
+        counts: Map<string, number>;
+    };
+    private labelsToKey;
+}
+/**
+ * MetricsRegistry manages all metrics
+ */
+declare class MetricsRegistry {
+    private counters;
+    private gauges;
+    private histograms;
+    private startTime;
+    private prefix;
+    private defaultLabels;
+    private collectDefaultMetrics;
+    constructor(config?: MetricsConfig);
+    /**
+     * Create or get a counter
+     */
+    counter(options: MetricOptions): Counter;
+    /**
+     * Create or get a gauge
+     */
+    gauge(options: MetricOptions): Gauge;
+    /**
+     * Create or get a histogram
+     */
+    histogram(options: MetricOptions): Histogram;
+    /**
+     * Initialize default runtime metrics
+     */
+    private initDefaultMetrics;
+    /**
+     * Update default metrics with current values
+     */
+    private updateDefaultMetrics;
+    /**
+     * Export metrics in Prometheus format
+     */
+    toPrometheus(): string;
+    private formatLabels;
+    private keyToLabels;
+}
+
+/**
+ * @gravito/monitor - Metrics Controller
+ */
+
+/**
+ * MetricsController handles the /metrics endpoint
+ */
+declare class MetricsController {
+    private registry;
+    constructor(registry: MetricsRegistry);
+    /**
+     * GET /metrics - Prometheus metrics endpoint
+     */
+    metrics(c: GravitoContext): Promise<Response>;
+}
+
+/**
+ * @gravito/monitor - HTTP Metrics Middleware
+ */
+
+/**
+ * Create middleware that collects HTTP metrics
+ */
+declare function createHttpMetricsMiddleware(registry: MetricsRegistry): (c: GravitoContext, next: () => Promise<void>) => Promise<Response | undefined>;
+
+/**
+ * @gravito/monitor - Tracing Manager
+ *
+ * OpenTelemetry OTLP tracing integration
+ */
+
+/**
+ * Span interface for tracing
+ */
+interface Span {
+    name: string;
+    traceId: string;
+    spanId: string;
+    parentSpanId?: string;
+    startTime: number;
+    endTime?: number;
+    attributes: Record<string, string | number | boolean>;
+    status: 'ok' | 'error' | 'unset';
+    events: SpanEvent[];
+}
+interface SpanEvent {
+    name: string;
+    timestamp: number;
+    attributes?: Record<string, string | number | boolean>;
+}
+/**
+ * Span context for propagation
+ */
+interface SpanContext {
+    traceId: string;
+    spanId: string;
+    traceFlags: number;
+}
+/**
+ * TracingManager handles distributed tracing
+ */
+declare class TracingManager {
+    private otelSdk;
+    private spans;
+    private isInitialized;
+    private serviceName;
+    private serviceVersion;
+    private endpoint;
+    private resourceAttributes;
+    constructor(config?: TracingConfig);
+    /**
+     * Initialize OpenTelemetry SDK if available
+     */
+    initialize(): Promise<void>;
+    /**
+     * Shutdown tracing
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Start a new span
+     */
+    startSpan(name: string, options?: {
+        attributes?: Record<string, string | number | boolean>;
+        parentSpan?: Span;
+    }): Span;
+    /**
+     * End a span
+     */
+    endSpan(span: Span, status?: 'ok' | 'error'): void;
+    /**
+     * Add an event to a span
+     */
+    addEvent(span: Span, name: string, attributes?: Record<string, string | number | boolean>): void;
+    /**
+     * Set span attribute
+     */
+    setAttribute(span: Span, key: string, value: string | number | boolean): void;
+    /**
+     * Get the currently active span
+     */
+    getActiveSpan(): Span | null;
+    /**
+     * Extract trace context from headers
+     */
+    extractContext(headers: Headers): SpanContext | null;
+    /**
+     * Inject trace context into headers
+     */
+    injectContext(headers: Headers, span: Span): void;
+    /**
+     * Get all collected spans (for debugging)
+     */
+    getSpans(): Span[];
+    /**
+     * Clear collected spans
+     */
+    clearSpans(): void;
+}
+
+/**
+ * @gravito/monitor - Tracing Middleware
+ */
+
+/**
+ * Create middleware that traces HTTP requests
+ */
+declare function createTracingMiddleware(tracer: TracingManager): (c: GravitoContext, next: () => Promise<void>) => Promise<Response | undefined>;
+
+/**
+ * @gravito/monitor - MonitorOrbit Plugin
+ *
+ * Gravito Orbit plugin for observability (Health, Metrics, Tracing)
+ */
+
+/**
+ * Monitor service container
+ */
+interface MonitorService {
+    health: HealthRegistry;
+    metrics: MetricsRegistry;
+    tracing: TracingManager;
+}
+/**
+ * MonitorOrbit - Observability plugin for Gravito
+ */
+declare class MonitorOrbit implements GravitoOrbit {
+    readonly name = "monitor";
+    private userConfig;
+    private healthRegistry;
+    private metricsRegistry;
+    private tracingManager;
+    constructor(config?: MonitorConfig);
+    /**
+     * Install the orbit (required by GravitoOrbit interface)
+     */
+    install(core: PlanetCore): Promise<void>;
+    /**
+     * Shutdown hook
+     */
+    shutdown(): Promise<void>;
+}
+
+export { Counter, Gauge, type HealthCheckFn, type HealthCheckResult, type HealthConfig, HealthController, HealthRegistry, type HealthReport, Histogram, type MetricOptions, type MetricsConfig, MetricsController, MetricsRegistry, type MonitorConfig, MonitorOrbit, type MonitorService, type Span, type SpanContext, type SpanEvent, type TracingConfig, TracingManager, createDatabaseCheck, createDiskCheck, createHttpCheck, createHttpMetricsMiddleware, createMemoryCheck, createRedisCheck, createTracingMiddleware, defineMonitorConfig };