@plyaz/core 1.1.1 → 1.2.1

package/dist/base/observability/LoggerAdapter.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Logger Adapter
+ *
+ * Uses @plyaz/logger for observability output.
+ * Can be used standalone OR alongside other adapters (Datadog, Grafana)
+ * to always have console/file logging regardless of external providers.
+ *
+ * @example Standalone usage
+ * ```typescript
+ * const logger = new LoggerAdapter();
+ * await logger.initialize({ serviceName: 'my-service' });
+ * ```
+ *
+ * @example As console fallback with Datadog
+ * ```typescript
+ * const observability = new ObservabilityService({
+ *   mode: 'parallel',
+ *   adapters: [datadogAdapter, loggerAdapter], // Both receive all events
+ * });
+ * ```
+ *
+ * @module base/observability
+ */
+import type { ObservabilityAdapterConfig, Metric, SpanOptions, Span, LogEntry, ObservabilityEvent } from '@plyaz/types/observability';
+import { BaseAdapter } from './BaseAdapter';
+/**
+ * Logger adapter that uses @plyaz/logger for output.
+ *
+ * This adapter integrates observability with the existing logging infrastructure,
+ * providing structured logging for metrics, spans, and events through PackageLogger.
+ *
+ * Use this adapter:
+ * - As standalone for development/debugging
+ * - Alongside Datadog/Grafana to always have local console output
+ * - As a fallback in priority mode when external providers fail
+ */
+export declare class LoggerAdapter extends BaseAdapter {
+    readonly provider: "console";
+    readonly name = "LoggerAdapter";
+    private observabilityLogger;
+    private logMetrics;
+    private logSpans;
+    private logEvents;
+    protected doInitialize(config: ObservabilityAdapterConfig): Promise<void>;
+    protected doShutdown(): Promise<void>;
+    protected doHealthCheck(): Promise<boolean>;
+    protected doRecordMetric(metric: Metric): Promise<void>;
+    protected doStartSpan(options: SpanOptions): Span;
+    protected doGetActiveSpan(): Span | null;
+    protected doLog(entry: LogEntry): Promise<void>;
+    protected doSendEvent(event: ObservabilityEvent): Promise<void>;
+    protected doFlush(): Promise<void>;
+}
+//# sourceMappingURL=LoggerAdapter.d.ts.map

package/dist/base/observability/LoggerAdapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LoggerAdapter.d.ts","sourceRoot":"","sources":["../../../src/base/observability/LoggerAdapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAGH,OAAO,KAAK,EACV,0BAA0B,EAC1B,MAAM,EACN,WAAW,EACX,IAAI,EACJ,QAAQ,EACR,kBAAkB,EAMnB,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAM5C;;;;;;;;;;GAUG;AACH,qBAAa,aAAc,SAAQ,WAAW;IAC5C,QAAQ,CAAC,QAAQ,EAAG,SAAS,CAAU;IACvC,QAAQ,CAAC,IAAI,mBAAmB;IAEhC,OAAO,CAAC,mBAAmB,CAAiB;IAC5C,OAAO,CAAC,UAAU,CAAQ;IAC1B,OAAO,CAAC,QAAQ,CAAQ;IACxB,OAAO,CAAC,SAAS,CAAQ;cAET,YAAY,CAAC,MAAM,EAAE,0BAA0B,GAAG,OAAO,CAAC,IAAI,CAAC;cAiB/D,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;cAI3B,aAAa,IAAI,OAAO,CAAC,OAAO,CAAC;cAIjC,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAY7D,SAAS,CAAC,WAAW,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI;IA6EjD,SAAS,CAAC,eAAe,IAAI,IAAI,GAAG,IAAI;cAIxB,KAAK,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;cA4BrC,WAAW,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC;cAUrD,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAGzC"}

package/dist/base/observability/ObservabilityService.d.ts

@@ -0,0 +1,160 @@
+/**
+ * Observability Service
+ *
+ * Injectable service for observability (metrics, tracing, logging).
+ * Works like CacheManager, DatabaseService, and ApiClient - can be injected into domain services.
+ *
+ * Adapters are initialized separately with their own configs.
+ * This service only orchestrates - it doesn't know about adapter-specific configs.
+ *
+ * @module base/observability
+ */
+import type { ObservabilityAdapter, ObservabilityAdapterConfig, Metric, SpanOptions, Span, LogEntry, ObservabilityEvent, OperationContext, MonitoringOperationResult, ObservabilityServiceConfig, ObservabilityServiceInterface } from '@plyaz/types/observability';
+/**
+ * ObservabilityService - Main observability service that implements ObservabilityAdapter.
+ *
+ * This service orchestrates multiple adapters and can be injected into domain services.
+ * Logger adapter is always included by default for console output.
+ *
+ * ```typescript
+ * // 1. Initialize adapters separately
+ * const datadogAdapter = new DatadogAdapter();
+ * await datadogAdapter.initialize({ apiKey: '...', serviceName: 'my-service' });
+ *
+ * // 2. Create service - logger is auto-added by default
+ * const observability = new ObservabilityService();
+ * await observability.initialize({
+ *   mode: 'parallel',
+ *   adapters: [datadogAdapter], // Logger added automatically
+ *   serviceName: 'my-service',
+ * });
+ *
+ * // 3. Use in domain services (implements ObservabilityAdapter)
+ * await observability.incrementCounter('api.requests', 1);
+ * ```
+ */
+export declare class ObservabilityService implements ObservabilityAdapter, ObservabilityServiceInterface {
+    readonly provider: "custom";
+    readonly name = "ObservabilityService";
+    private _isInitialized;
+    private _config;
+    private readonly logger;
+    private readonly adapterEntries;
+    private mode;
+    private readonly noopAdapter;
+    private loggerAdapter;
+    constructor();
+    get isInitialized(): boolean;
+    /**
+     * Check if service has at least one working adapter
+     */
+    get isReady(): boolean;
+    /**
+     * Get all adapters (for compatibility)
+     */
+    private get adapters();
+    /**
+     * Get initialized adapter entries
+     */
+    private get initializedEntries();
+    /**
+     * Get primary (non-failover) initialized adapters
+     */
+    private get primaryEntries();
+    /**
+     * Get failover initialized adapters
+     */
+    private get failoverEntries();
+    /**
+     * Check if input is an adapter with priority config
+     */
+    private isAdapterWithPriority;
+    /**
+     * Normalize adapter input to adapter with priority and failover config
+     */
+    private normalizeAdapter;
+    /**
+     * Initialize the observability service.
+     * Logger adapter is always added by default unless explicitly disabled.
+     * Adapters are sorted by priority (higher = first), with failover adapters after primary.
+     */
+    initialize(config: ObservabilityAdapterConfig & ObservabilityServiceConfig): Promise<void>;
+    shutdown(): Promise<void>;
+    isHealthy(): Promise<boolean>;
+    flush(): Promise<void>;
+    private get config();
+    private executeOnAdapters;
+    private executeSingle;
+    /**
+     * Execute on primary adapters in parallel.
+     * If all primary adapters fail, execute on failover adapters.
+     */
+    private executeParallelWithFailover;
+    private executeParallel;
+    /**
+     * Execute on primary adapters in priority order.
+     * If all primary adapters fail, try failover adapters.
+     */
+    private executePriorityWithFailover;
+    private withTimeout;
+    recordMetric(metric: Metric): Promise<void>;
+    incrementCounter(name: string, value?: number, tags?: Record<string, string>): Promise<void>;
+    setGauge(name: string, value: number, tags?: Record<string, string>): Promise<void>;
+    recordHistogram(name: string, value: number, tags?: Record<string, string>): Promise<void>;
+    startSpan(options: SpanOptions): Span;
+    withSpan<T>(options: SpanOptions, fn: (span: Span) => Promise<T>): Promise<T>;
+    getActiveSpan(): Span | null;
+    log(entry: LogEntry): Promise<void>;
+    sendEvent(event: ObservabilityEvent): Promise<void>;
+    /**
+     * Track a service operation with automatic metrics and tracing.
+     *
+     * @example
+     * ```typescript
+     * const { result, metrics } = await observability.trackOperation(
+     *   {
+     *     serviceName: 'UserService',
+     *     operation: 'create',
+     *     entityType: 'user',
+     *     startTime: Date.now(),
+     *   },
+     *   async () => {
+     *     return await this.repository.create(userData);
+     *   }
+     * );
+     * ```
+     */
+    trackOperation<T>(context: OperationContext, operation: () => Promise<T>): Promise<{
+        result: T;
+        metrics: MonitoringOperationResult;
+    }>;
+}
+/**
+ * Create an ObservabilityService with pre-initialized adapters.
+ *
+ * @example
+ * ```typescript
+ * // Initialize adapters first
+ * const datadogAdapter = new DatadogAdapter();
+ * await datadogAdapter.initialize({ apiKey: '...', serviceName: 'my-service' });
+ *
+ * // Create and initialize service (logger auto-added)
+ * const observability = await createObservabilityService({
+ *   mode: 'parallel',
+ *   adapters: [datadogAdapter],
+ *   serviceName: 'my-service',
+ * });
+ *
+ * // Priority mode (fallback chain)
+ * const observability = await createObservabilityService({
+ *   mode: 'priority',
+ *   adapters: [datadogAdapter, grafanaAdapter],
+ *   serviceName: 'my-service',
+ * });
+ * ```
+ */
+export declare function createObservabilityService(config?: ObservabilityServiceConfig & {
+    serviceName?: string;
+    environment?: string;
+}): Promise<ObservabilityService>;
+//# sourceMappingURL=ObservabilityService.d.ts.map

package/dist/base/observability/ObservabilityService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ObservabilityService.d.ts","sourceRoot":"","sources":["../../../src/base/observability/ObservabilityService.ts"],"names":[],"mappings":"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"}

package/dist/base/observability/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Observability Module
+ *
+ * Adapter-based observability system supporting multiple providers
+ * (Datadog, Grafana, OpenTelemetry, etc.) with parallel and priority modes.
+ *
+ * @module base/observability
+ */
+export { BaseAdapter, NoopAdapter } from './BaseAdapter';
+export { LoggerAdapter } from './LoggerAdapter';
+export { CompositeAdapter } from './CompositeAdapter';
+export { DatadogAdapter } from './DatadogAdapter';
+export type { DatadogApiClient, DatadogMetricPayload, DatadogLogPayload, DatadogEventPayload, DatadogAdapterConfigExtended, } from './DatadogAdapter';
+export { ObservabilityService, createObservabilityService } from './ObservabilityService';
+export type { ObservabilityAdapter, ObservabilityAdapterConfig, ObservabilityProvider, Metric, SpanOptions, Span, LogEntry, ObservabilityEvent, SpanContext, SpanAttributes, SpanEvent, SpanStatus, DatadogAdapterConfig, OpenTelemetryAdapterConfig, GrafanaAdapterConfig, ConsoleAdapterConfig, CompositeMode, CompositeAdapterConfig, OperationContext, MonitoringOperationResult, AdapterWithPriority, AdapterEntry, ObservabilityServiceConfig, ObservabilityServiceInterface, } from '@plyaz/types/observability';
+export { OBSERVABILITY_METRICS, OBSERVABILITY_SPANS } from '@plyaz/types/observability';
+//# sourceMappingURL=index.d.ts.map

package/dist/base/observability/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/base/observability/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACzD,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,YAAY,EACV,gBAAgB,EAChB,oBAAoB,EACpB,iBAAiB,EACjB,mBAAmB,EACnB,4BAA4B,GAC7B,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EAAE,oBAAoB,EAAE,0BAA0B,EAAE,MAAM,wBAAwB,CAAC;AAG1F,YAAY,EACV,oBAAoB,EACpB,0BAA0B,EAC1B,qBAAqB,EACrB,MAAM,EACN,WAAW,EACX,IAAI,EACJ,QAAQ,EACR,kBAAkB,EAClB,WAAW,EACX,cAAc,EACd,SAAS,EACT,UAAU,EACV,oBAAoB,EACpB,0BAA0B,EAC1B,oBAAoB,EACpB,oBAAoB,EACpB,aAAa,EACb,sBAAsB,EACtB,gBAAgB,EAChB,yBAAyB,EACzB,mBAAmB,EACnB,YAAY,EACZ,0BAA0B,EAC1B,6BAA6B,GAC9B,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC"}