@bsb/base 9.0.0

package/lib/serviceBase/observable.d.ts

@@ -0,0 +1,249 @@
+/**
+ * BSB (Better-Service-Base) is an event-bus based microservice framework.
+ * Copyright (C) 2016 - 2025 BetterCorp (PTY) Ltd
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published
+ * by the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * Alternatively, you may obtain a commercial license for this program.
+ * The commercial license allows you to use the Program in a closed-source manner,
+ * including the right to create derivative works that are not subject to the terms
+ * of the AGPL.
+ *
+ * To obtain a commercial license, please contact the copyright holders at
+ * https://www.bettercorp.dev. The terms and conditions of the commercial license
+ * will be provided upon request.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ */
+import { EventEmitter } from "node:events";
+import { BSBError } from "../base";
+import { DEBUG_MODE, LogMeta } from "../interfaces";
+import { DTrace } from "../interfaces/metrics";
+import { SBConfig } from "./config";
+import { SBPlugins } from "./plugins";
+/**
+ * BSB Observable Controller - Unified logging, metrics, and tracing
+ *
+ * This class is responsible for managing all observability in the BSB framework.
+ * It coordinates observable plugins (like OpenTelemetry, Prometheus, etc.) and
+ * routes events from the Observable API to the configured backends.
+ *
+ * If you have a specific way of managing observability, you can extend this class
+ * and use your own class when creating the ServiceBase instance.
+ *
+ * @group Observable
+ * @category Core
+ * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/SBObservable.html | API: SBObservable}
+ *
+ * @example
+ * ```typescript
+ * // Custom observable controller
+ * class MyObservable extends SBObservable {
+ *   // Override methods as needed
+ * }
+ *
+ * // Use custom controller
+ * const serviceBase = new ServiceBase(appId, {
+ *   observableClass: MyObservable
+ * });
+ * ```
+ */
+export declare class SBObservable {
+    private observablePlugins;
+    observableBus: EventEmitter;
+    private mode;
+    private appId;
+    private cwd;
+    private sbPlugins;
+    private observableBackend;
+    private _ready;
+    /**
+     * Check if observable plugins are ready
+     * @returns true if all plugins have been initialized
+     */
+    get isReady(): boolean;
+    /**
+     * Create an SBObservable instance
+     * @param appId - Application ID
+     * @param mode - Debug mode (development, production, production-debug)
+     * @param cwd - Current working directory
+     * @param sbPlugins - Plugin manager instance
+     */
+    constructor(appId: string, mode: DEBUG_MODE, cwd: string, sbPlugins: SBPlugins);
+    private setupCounterEvents;
+    private setupGaugeEvents;
+    private setupHistogramEvents;
+    private setupSpanEvents;
+    private triggerEvent;
+    private triggerMetricEvent;
+    private triggerSpanEvent;
+    private shouldTriggerForPlugin;
+    private determineFilterType;
+    /**
+     * Setup and load observable plugins from configuration
+     *
+     * Loads configured observable plugins and initializes their filters.
+     * This is called during ServiceBase initialization.
+     *
+     * @param sbConfig - Configuration manager instance
+     */
+    setupObservablePlugins(sbConfig: SBConfig): Promise<void>;
+    /**
+     * Initialize all observable plugins
+     *
+     * Calls the init lifecycle method on all loaded observable plugins.
+     * This is called during ServiceBase initialization.
+     *
+     * @param trace - DTrace for tracking initialization
+     * @param sbConfig - Configuration manager instance
+     */
+    init(trace: DTrace, sbConfig: SBConfig): Promise<void>;
+    /**
+     * Run all observable plugins
+     *
+     * Calls the run lifecycle method on all loaded observable plugins.
+     * This is called during ServiceBase startup.
+     *
+     * @param trace - DTrace for tracking the run phase
+     */
+    run(trace: DTrace): Promise<void>;
+    /**
+     * Dispose all observable plugins
+     *
+     * Calls the dispose lifecycle method on all loaded observable plugins
+     * and clears the plugin list. This is called during ServiceBase shutdown.
+     */
+    dispose(): Promise<void>;
+    /**
+     * Emit a debug log event
+     * @param plugin - Plugin name
+     * @param trace - DTrace object
+     * @param message - Log message
+     * @param meta - Log metadata
+     */
+    debug(plugin: string, trace: DTrace, message: string, meta: LogMeta<any>): void;
+    /**
+     * Emit an info log event
+     * @param plugin - Plugin name
+     * @param trace - DTrace object
+     * @param message - Log message
+     * @param meta - Log metadata
+     */
+    info(plugin: string, trace: DTrace, message: string, meta: LogMeta<any>): void;
+    /**
+     * Emit a warn log event
+     * @param plugin - Plugin name
+     * @param trace - DTrace object
+     * @param message - Log message
+     * @param meta - Log metadata
+     */
+    warn(plugin: string, trace: DTrace, message: string, meta: LogMeta<any>): void;
+    /**
+     * Emit an error log event
+     * @param plugin - Plugin name
+     * @param trace - DTrace object
+     * @param message - Log message or BSBError
+     * @param meta - Log metadata (optional)
+     */
+    error(plugin: string, trace: DTrace, message: string | BSBError<any>, meta?: LogMeta<any>): void;
+    /**
+     * Emit counter creation event
+     * @param timestamp - Event timestamp
+     * @param pluginName - Plugin name
+     * @param name - Metric name
+     * @param description - Short description
+     * @param help - Detailed help text
+     * @param labels - Optional label names
+     */
+    createCounter(timestamp: number, pluginName: string, name: string, description: string, help: string, labels?: string[]): void;
+    /**
+     * Emit counter increment event
+     * @param timestamp - Event timestamp
+     * @param pluginName - Plugin name
+     * @param name - Metric name
+     * @param value - Increment value
+     * @param labels - Optional label values
+     */
+    incrementCounter(timestamp: number, pluginName: string, name: string, value: number, labels?: Record<string, string>): void;
+    /**
+     * Emit gauge creation event
+     * @param timestamp - Event timestamp
+     * @param pluginName - Plugin name
+     * @param name - Metric name
+     * @param description - Short description
+     * @param help - Detailed help text
+     * @param labels - Optional label names
+     */
+    createGauge(timestamp: number, pluginName: string, name: string, description: string, help: string, labels?: string[]): void;
+    /**
+     * Emit gauge set event
+     * @param timestamp - Event timestamp
+     * @param pluginName - Plugin name
+     * @param name - Metric name
+     * @param value - New gauge value
+     * @param labels - Optional label values
+     */
+    setGauge(timestamp: number, pluginName: string, name: string, value: number, labels?: Record<string, string>): void;
+    /**
+     * Emit histogram creation event
+     * @param timestamp - Event timestamp
+     * @param pluginName - Plugin name
+     * @param name - Metric name
+     * @param description - Short description
+     * @param help - Detailed help text
+     * @param boundaries - Optional histogram boundaries
+     * @param labels - Optional label names
+     */
+    createHistogram(timestamp: number, pluginName: string, name: string, description: string, help: string, boundaries?: number[], labels?: string[]): void;
+    /**
+     * Emit histogram observation event
+     * @param timestamp - Event timestamp
+     * @param pluginName - Plugin name
+     * @param name - Metric name
+     * @param value - Observed value
+     * @param labels - Optional label values
+     */
+    observeHistogram(timestamp: number, pluginName: string, name: string, value: number, labels?: Record<string, string>): void;
+    /**
+     * Emit span start event
+     * @param timestamp - Event timestamp
+     * @param appId - Application ID
+     * @param pluginName - Plugin name
+     * @param traceId - Trace ID
+     * @param parentSpanId - Parent span ID (null for root spans)
+     * @param spanId - This span's ID
+     * @param name - Span name
+     * @param attributes - Optional span attributes
+     */
+    startSpan(timestamp: number, appId: string, pluginName: string, traceId: string, parentSpanId: string | null, spanId: string, name: string, attributes?: Record<string, string | number | boolean>): void;
+    /**
+     * Emit span end event
+     * @param timestamp - Event timestamp
+     * @param appId - Application ID
+     * @param pluginName - Plugin name
+     * @param traceId - Trace ID
+     * @param spanId - Span ID
+     * @param attributes - Optional final attributes
+     */
+    endSpan(timestamp: number, appId: string, pluginName: string, traceId: string, spanId: string, attributes?: Record<string, string | number | boolean>): void;
+    /**
+     * Emit span error event
+     * @param timestamp - Event timestamp
+     * @param appId - Application ID
+     * @param pluginName - Plugin name
+     * @param traceId - Trace ID
+     * @param spanId - Span ID
+     * @param error - Error to record
+     * @param attributes - Optional error attributes
+     */
+    errorSpan(timestamp: number, appId: string, pluginName: string, traceId: string, spanId: string, error: Error, attributes?: Record<string, string | number | boolean>): void;
+}