@plyaz/types 1.23.0 → 1.23.2

package/dist/observability/datadog-sdk.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Datadog SDK Type Declarations
+ *
+ * Type definitions for the Datadog SDK packages (dd-trace, hot-shots).
+ * These are used when the actual packages are not installed.
+ *
+ * @module observability/datadog-sdk
+ */
+/**
+ * hot-shots StatsD client configuration
+ */
+export interface HotShotsConfig {
+    host?: string;
+    port?: number;
+    prefix?: string;
+    suffix?: string;
+    globalTags?: string[] | Record<string, string>;
+    cacheDns?: boolean;
+    cacheDnsTtl?: number;
+    mock?: boolean;
+    maxBufferSize?: number;
+    bufferFlushInterval?: number;
+    telegraf?: boolean;
+    sampleRate?: number;
+    errorHandler?: (error: Error) => void;
+}
+/**
+ * hot-shots StatsD client interface
+ */
+export interface HotShotsClient {
+    increment(stat: string, value?: number, sampleRate?: number, tags?: string[], callback?: () => void): void;
+    increment(stat: string, value?: number, tags?: string[], callback?: () => void): void;
+    increment(stat: string, value?: number, callback?: () => void): void;
+    decrement(stat: string, value?: number, sampleRate?: number, tags?: string[], callback?: () => void): void;
+    decrement(stat: string, value?: number, tags?: string[], callback?: () => void): void;
+    gauge(stat: string, value: number, sampleRate?: number, tags?: string[], callback?: () => void): void;
+    gauge(stat: string, value: number, tags?: string[], callback?: () => void): void;
+    histogram(stat: string, value: number, sampleRate?: number, tags?: string[], callback?: () => void): void;
+    histogram(stat: string, value: number, tags?: string[], callback?: () => void): void;
+    timing(stat: string, time: number, sampleRate?: number, tags?: string[], callback?: () => void): void;
+    timing(stat: string, time: number, tags?: string[], callback?: () => void): void;
+    set(stat: string, value: number | string, sampleRate?: number, tags?: string[], callback?: () => void): void;
+    set(stat: string, value: number | string, tags?: string[], callback?: () => void): void;
+    distribution(stat: string, value: number, sampleRate?: number, tags?: string[], callback?: () => void): void;
+    distribution(stat: string, value: number, tags?: string[], callback?: () => void): void;
+    close(callback?: () => void): void;
+    flush(): void;
+    event(title: string, text: string, options?: Record<string, unknown>, tags?: string[], callback?: () => void): void;
+    check(name: string, status: number, options?: Record<string, unknown>, tags?: string[], callback?: () => void): void;
+}
+/**
+ * dd-trace initialization options
+ */
+export interface DDTraceConfig {
+    service?: string;
+    env?: string;
+    version?: string;
+    hostname?: string;
+    port?: number | string;
+    url?: string;
+    dogstatsd?: {
+        hostname?: string;
+        port?: number;
+    };
+    sampleRate?: number;
+    runtimeMetrics?: boolean;
+    logInjection?: boolean;
+    startupLogs?: boolean;
+    debug?: boolean;
+    tags?: Record<string, string>;
+    plugins?: boolean;
+    profiling?: boolean;
+    appsec?: boolean;
+}
+/**
+ * dd-trace span context
+ */
+export interface DDSpanContext {
+    toTraceId(): string;
+    toSpanId(): string;
+    toTraceparent(): string;
+}
+/**
+ * dd-trace span interface
+ */
+export interface DDSpan {
+    context(): DDSpanContext;
+    tracer(): DDTracer;
+    setOperationName(name: string): this;
+    setBaggageItem(key: string, value: string): this;
+    getBaggageItem(key: string): string | undefined;
+    setTag(key: string, value: unknown): this;
+    addTags(tags: Record<string, unknown>): this;
+    log(keyValuePairs: Record<string, unknown>, timestamp?: number): this;
+    finish(finishTime?: number): void;
+}
+/**
+ * dd-trace span options
+ */
+export interface DDSpanOptions {
+    childOf?: DDSpan | DDSpanContext;
+    tags?: Record<string, unknown>;
+    startTime?: number;
+    type?: string;
+    resource?: string;
+    service?: string;
+}
+/**
+ * dd-trace scope interface
+ */
+export interface DDScope {
+    active(): DDSpan | null;
+    bind<T>(target: T, span?: DDSpan | null): T;
+    activate<T>(span: DDSpan, fn: () => T): T;
+}
+/**
+ * dd-trace tracer interface
+ */
+export interface DDTracer {
+    init(options?: DDTraceConfig): this;
+    use(plugin: string, config?: Record<string, unknown>): this;
+    trace<T>(name: string, fn: (span?: DDSpan) => T): T;
+    trace<T>(name: string, options: DDSpanOptions, fn: (span?: DDSpan) => T): T;
+    wrap<T extends (...args: unknown[]) => unknown>(name: string, fn: T): T;
+    wrap<T extends (...args: unknown[]) => unknown>(name: string, options: DDSpanOptions, fn: T): T;
+    startSpan(name: string, options?: DDSpanOptions): DDSpan;
+    inject(spanContext: DDSpanContext, format: string, carrier: unknown): void;
+    extract(format: string, carrier: unknown): DDSpanContext | null;
+    scope(): DDScope;
+    setUrl(url: string): void;
+}
+/**
+ * dd-trace module interface
+ */
+export interface DDTraceModule {
+    default: DDTracer;
+    tracer: DDTracer;
+}

package/dist/observability/index.cjs

@@ -0,0 +1,48 @@
+'use strict';
+
+// @plyaz package - Built with tsup
+
+// src/observability/types.ts
+var OBSERVABILITY_METRICS = {
+  // Service metrics
+  SERVICE_OPERATION_DURATION: "service.operation.duration",
+  SERVICE_OPERATION_COUNT: "service.operation.count",
+  SERVICE_OPERATION_ERROR: "service.operation.error",
+  // Database metrics
+  DB_QUERY_DURATION: "db.query.duration",
+  DB_QUERY_COUNT: "db.query.count",
+  DB_CONNECTION_POOL_SIZE: "db.connection.pool.size",
+  DB_CONNECTION_POOL_USED: "db.connection.pool.used",
+  // Cache metrics
+  CACHE_HIT: "cache.hit",
+  CACHE_MISS: "cache.miss",
+  CACHE_SET: "cache.set",
+  CACHE_DELETE: "cache.delete",
+  // API metrics
+  API_REQUEST_DURATION: "api.request.duration",
+  API_REQUEST_COUNT: "api.request.count",
+  API_REQUEST_ERROR: "api.request.error",
+  // Transaction metrics
+  TRANSACTION_DURATION: "transaction.duration",
+  TRANSACTION_COUNT: "transaction.count",
+  TRANSACTION_ROLLBACK: "transaction.rollback"
+};
+var OBSERVABILITY_SPANS = {
+  SERVICE_CREATE: "service.create",
+  SERVICE_UPDATE: "service.update",
+  SERVICE_DELETE: "service.delete",
+  SERVICE_GET: "service.get",
+  SERVICE_LIST: "service.list",
+  SERVICE_BULK_CREATE: "service.bulk_create",
+  SERVICE_BULK_DELETE: "service.bulk_delete",
+  SERVICE_TRANSACTION: "service.transaction",
+  DB_QUERY: "db.query",
+  CACHE_GET: "cache.get",
+  CACHE_SET: "cache.set",
+  API_REQUEST: "api.request"
+};
+
+exports.OBSERVABILITY_METRICS = OBSERVABILITY_METRICS;
+exports.OBSERVABILITY_SPANS = OBSERVABILITY_SPANS;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/observability/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/observability/types.ts"],"names":[],"mappings":";;;;;AAkpBO,IAAM,qBAAA,GAAwB;AAAA;AAAA,EAEnC,0BAAA,EAA4B,4BAAA;AAAA,EAC5B,uBAAA,EAAyB,yBAAA;AAAA,EACzB,uBAAA,EAAyB,yBAAA;AAAA;AAAA,EAGzB,iBAAA,EAAmB,mBAAA;AAAA,EACnB,cAAA,EAAgB,gBAAA;AAAA,EAChB,uBAAA,EAAyB,yBAAA;AAAA,EACzB,uBAAA,EAAyB,yBAAA;AAAA;AAAA,EAGzB,SAAA,EAAW,WAAA;AAAA,EACX,UAAA,EAAY,YAAA;AAAA,EACZ,SAAA,EAAW,WAAA;AAAA,EACX,YAAA,EAAc,cAAA;AAAA;AAAA,EAGd,oBAAA,EAAsB,sBAAA;AAAA,EACtB,iBAAA,EAAmB,mBAAA;AAAA,EACnB,iBAAA,EAAmB,mBAAA;AAAA;AAAA,EAGnB,oBAAA,EAAsB,sBAAA;AAAA,EACtB,iBAAA,EAAmB,mBAAA;AAAA,EACnB,oBAAA,EAAsB;AACxB;AAKO,IAAM,mBAAA,GAAsB;AAAA,EACjC,cAAA,EAAgB,gBAAA;AAAA,EAChB,cAAA,EAAgB,gBAAA;AAAA,EAChB,cAAA,EAAgB,gBAAA;AAAA,EAChB,WAAA,EAAa,aAAA;AAAA,EACb,YAAA,EAAc,cAAA;AAAA,EACd,mBAAA,EAAqB,qBAAA;AAAA,EACrB,mBAAA,EAAqB,qBAAA;AAAA,EACrB,mBAAA,EAAqB,qBAAA;AAAA,EACrB,QAAA,EAAU,UAAA;AAAA,EACV,SAAA,EAAW,WAAA;AAAA,EACX,SAAA,EAAW,WAAA;AAAA,EACX,WAAA,EAAa;AACf","file":"index.cjs","sourcesContent":["/**\n * Monitoring/Observability Types\n *\n * Adapter-based observability system supporting multiple providers\n * (Datadog, Grafana, OpenTelemetry, etc.) with parallel and priority modes.\n *\n * All types are prefixed with \"Monitoring\" for this dedicated module.\n *\n * @module observability/types\n */\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Monitoring Types\n// ─────────────────────────────────────────────────────────────────────────────\n\n/**\n * Supported observability providers\n * Currently implemented: 'datadog', 'console', 'noop'\n * Planned: 'grafana', 'opentelemetry', 'prometheus', 'newrelic', 'custom'\n */\nexport type MonitoringObservabilityProvider =\n  | 'datadog'\n  | 'console'\n  | 'noop'\n  // Planned providers (uncomment when implemented):\n  // | 'grafana'\n  // | 'opentelemetry'\n  // | 'prometheus'\n  // | 'newrelic'\n  | 'custom';\n\n/**\n * Metric types\n */\nexport type MonitoringMetricType = 'counter' | 'gauge' | 'histogram' | 'summary';\n\n/**\n * Span status for tracing\n */\nexport type MonitoringSpanStatus = 'ok' | 'error' | 'unset';\n\n/**\n * Log levels\n */\nexport type MonitoringLogLevel = 'debug' | 'info' | 'warn' | 'error' | 'fatal';\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Metric Types\n// ─────────────────────────────────────────────────────────────────────────────\n\n/**\n * Base metric options\n */\nexport interface MonitoringMetricOptions {\n  /** Metric name (e.g., 'http.request.duration') */\n  name: string;\n  /** Human-readable description */\n  description?: string;\n  /** Unit of measurement (e.g., 'ms', 'bytes', 'count') */\n  unit?: string;\n  /** Tags/labels for the metric */\n  tags?: Record<string, string | number | boolean>;\n}\n\n/**\n * Counter metric (monotonically increasing)\n */\nexport interface MonitoringCounterMetric extends MonitoringMetricOptions {\n  type: 'counter';\n  /** Value to increment by (default: 1) */\n  value?: number;\n}\n\n/**\n * Gauge metric (can go up or down)\n */\nexport interface MonitoringGaugeMetric extends MonitoringMetricOptions {\n  type: 'gauge';\n  /** Current value */\n  value: number;\n}\n\n/**\n * Histogram metric (distribution of values)\n */\nexport interface MonitoringHistogramMetric extends MonitoringMetricOptions {\n  type: 'histogram';\n  /** Value to record */\n  value: number;\n  /** Bucket boundaries (optional) */\n  buckets?: number[];\n}\n\n/**\n * Summary metric (percentiles)\n */\nexport interface MonitoringSummaryMetric extends MonitoringMetricOptions {\n  type: 'summary';\n  /** Value to record */\n  value: number;\n  /** Percentiles to track (e.g., [0.5, 0.9, 0.99]) */\n  percentiles?: number[];\n}\n\n/**\n * Union of all metric types\n */\nexport type MonitoringMetric =\n  | MonitoringCounterMetric\n  | MonitoringGaugeMetric\n  | MonitoringHistogramMetric\n  | MonitoringSummaryMetric;\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Tracing Types\n// ─────────────────────────────────────────────────────────────────────────────\n\n/**\n * Span context for distributed tracing\n */\nexport interface MonitoringSpanContext {\n  /** Unique trace ID */\n  traceId: string;\n  /** Unique span ID */\n  spanId: string;\n  /** Parent span ID (if any) */\n  parentSpanId?: string;\n  /** Sampling decision */\n  sampled?: boolean;\n}\n\n/**\n * Span attributes following OpenTelemetry semantic conventions.\n * Property names use dot notation as per OTel spec (e.g., 'service.name').\n */\n\nexport interface MonitoringSpanAttributes {\n  /** Service name */\n  // eslint-disable-next-line @typescript-eslint/naming-convention\n  'service.name'?: string;\n  /** Operation name */\n  // eslint-disable-next-line @typescript-eslint/naming-convention\n  'operation.name'?: string;\n  /** HTTP method */\n  // eslint-disable-next-line @typescript-eslint/naming-convention\n  'http.method'?: string;\n  /** HTTP URL */\n  // eslint-disable-next-line @typescript-eslint/naming-convention\n  'http.url'?: string;\n  /** HTTP status code */\n  // eslint-disable-next-line @typescript-eslint/naming-convention\n  'http.status_code'?: number;\n  /** Database system */\n  // eslint-disable-next-line @typescript-eslint/naming-convention\n  'db.system'?: string;\n  /** Database statement */\n  // eslint-disable-next-line @typescript-eslint/naming-convention\n  'db.statement'?: string;\n  /** Error flag */\n  error?: boolean;\n  /** Error message */\n  // eslint-disable-next-line @typescript-eslint/naming-convention\n  'error.message'?: string;\n  /** Custom attributes */\n  [key: string]: string | number | boolean | undefined;\n}\n\n/**\n * Span event (point-in-time occurrence within a span)\n */\nexport interface MonitoringSpanEvent {\n  /** Event name */\n  name: string;\n  /** Event timestamp */\n  timestamp?: number;\n  /** Event attributes */\n  attributes?: Record<string, string | number | boolean>;\n}\n\n/**\n * Options for creating a span\n */\nexport interface MonitoringSpanOptions {\n  /** Span name (operation being traced) */\n  name: string;\n  /** Span kind */\n  kind?: 'internal' | 'server' | 'client' | 'producer' | 'consumer';\n  /** Initial attributes */\n  attributes?: MonitoringSpanAttributes;\n  /** Parent span context (for distributed tracing) */\n  parentContext?: MonitoringSpanContext;\n  /** Start time (default: now) */\n  startTime?: number;\n}\n\n/**\n * Active span interface\n */\nexport interface MonitoringSpan {\n  /** Span context */\n  context: MonitoringSpanContext;\n  /** Set attribute on span */\n  setAttribute(key: string, value: string | number | boolean): void;\n  /** Set multiple attributes */\n  setAttributes(attributes: MonitoringSpanAttributes): void;\n  /** Add event to span */\n  addEvent(event: MonitoringSpanEvent): void;\n  /** Set span status */\n  setStatus(status: MonitoringSpanStatus, message?: string): void;\n  /** End the span */\n  end(endTime?: number): void;\n  /** Record exception */\n  recordException(error: Error): void;\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Logging Types\n// ─────────────────────────────────────────────────────────────────────────────\n\n/**\n * Structured log entry\n */\nexport interface MonitoringLogEntry {\n  /** Log level */\n  level: MonitoringLogLevel;\n  /** Log message */\n  message: string;\n  /** Timestamp */\n  timestamp?: number;\n  /** Service/component name */\n  service?: string;\n  /** Additional context */\n  context?: Record<string, unknown>;\n  /** Associated trace ID */\n  traceId?: string;\n  /** Associated span ID */\n  spanId?: string;\n  /** Error object (if logging an error) */\n  error?: Error;\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Event Types\n// ─────────────────────────────────────────────────────────────────────────────\n\n/**\n * Custom event for observability\n */\nexport interface MonitoringObservabilityEvent {\n  /** Event name */\n  name: string;\n  /** Event timestamp */\n  timestamp?: number;\n  /** Event properties */\n  properties?: Record<string, unknown>;\n  /** Associated tags */\n  tags?: Record<string, string>;\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Adapter Interface\n// ─────────────────────────────────────────────────────────────────────────────\n\n/**\n * Base observability adapter interface.\n *\n * All observability providers (Datadog, Grafana, OpenTelemetry, etc.)\n * must implement this interface.\n *\n * @example\n * ```typescript\n * class DatadogAdapter implements ObservabilityAdapter {\n *   readonly provider = 'datadog';\n *   readonly name = 'DatadogAdapter';\n *\n *   async initialize(config: DatadogConfig): Promise<void> {\n *     // Initialize Datadog client\n *   }\n *\n *   async recordMetric(metric: Metric): Promise<void> {\n *     // Send to Datadog\n *   }\n *\n *   // ... other methods\n * }\n * ```\n */\nexport interface MonitoringObservabilityAdapter {\n  /** Provider type */\n  readonly provider: MonitoringObservabilityProvider;\n\n  /** Adapter name for logging */\n  readonly name: string;\n\n  /** Whether the adapter is initialized */\n  readonly isInitialized: boolean;\n\n  // ─── Lifecycle ─────────────────────────────────────────────────────────────\n\n  /**\n   * Initialize the adapter with provider-specific config\n   */\n  initialize(config: MonitoringObservabilityAdapterConfig): Promise<void>;\n\n  /**\n   * Shutdown/cleanup the adapter\n   */\n  shutdown(): Promise<void>;\n\n  /**\n   * Check if adapter is healthy/connected\n   */\n  isHealthy(): Promise<boolean>;\n\n  // ─── Metrics ───────────────────────────────────────────────────────────────\n\n  /**\n   * Record a metric\n   */\n  recordMetric(metric: MonitoringMetric): Promise<void>;\n\n  /**\n   * Increment a counter\n   */\n  incrementCounter(name: string, value?: number, tags?: Record<string, string>): Promise<void>;\n\n  /**\n   * Set a gauge value\n   */\n  setGauge(name: string, value: number, tags?: Record<string, string>): Promise<void>;\n\n  /**\n   * Record a histogram value\n   */\n  recordHistogram(name: string, value: number, tags?: Record<string, string>): Promise<void>;\n\n  // ─── Tracing ───────────────────────────────────────────────────────────────\n\n  /**\n   * Start a new span\n   */\n  startSpan(options: MonitoringSpanOptions): MonitoringSpan;\n\n  /**\n   * Get current active span (if any)\n   */\n  getActiveSpan(): MonitoringSpan | null;\n\n  /**\n   * Run a function within a span\n   */\n  withSpan<T>(options: MonitoringSpanOptions, fn: (span: MonitoringSpan) => Promise<T>): Promise<T>;\n\n  // ─── Logging ───────────────────────────────────────────────────────────────\n\n  /**\n   * Send a log entry\n   */\n  log(entry: MonitoringLogEntry): Promise<void>;\n\n  // ─── Events ────────────────────────────────────────────────────────────────\n\n  /**\n   * Send a custom event\n   */\n  sendEvent(event: MonitoringObservabilityEvent): Promise<void>;\n\n  // ─── Flush ─────────────────────────────────────────────────────────────────\n\n  /**\n   * Flush any buffered data\n   */\n  flush(): Promise<void>;\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Adapter Configuration\n// ─────────────────────────────────────────────────────────────────────────────\n\n/**\n * Base adapter configuration\n */\nexport interface MonitoringObservabilityAdapterConfig {\n  /** Enable/disable the adapter */\n  enabled?: boolean;\n  /** Service name for tagging */\n  serviceName?: string;\n  /** Environment (production, staging, development) */\n  environment?: string;\n  /** Default tags to add to all metrics/spans */\n  defaultTags?: Record<string, string>;\n  /** Sampling rate for traces (0.0 to 1.0) */\n  samplingRate?: number;\n  /** Flush interval in milliseconds */\n  flushInterval?: number;\n  /** Buffer size before auto-flush */\n  bufferSize?: number;\n}\n\n/**\n * Datadog-specific configuration\n */\nexport interface MonitoringDatadogAdapterConfig extends MonitoringObservabilityAdapterConfig {\n  /** Datadog API key */\n  apiKey: string;\n  /** Datadog site (e.g., 'datadoghq.com', 'datadoghq.eu') */\n  site?: string;\n  /** Enable APM tracing */\n  apmEnabled?: boolean;\n  /** Enable RUM (Real User Monitoring) */\n  rumEnabled?: boolean;\n  /** RUM application ID */\n  rumApplicationId?: string;\n  /** RUM client token */\n  rumClientToken?: string;\n}\n\n/**\n * OpenTelemetry-specific configuration\n */\nexport interface MonitoringOpenTelemetryAdapterConfig extends MonitoringObservabilityAdapterConfig {\n  /** OTLP endpoint URL */\n  endpoint: string;\n  /** Headers for OTLP exporter */\n  headers?: Record<string, string>;\n  /** Export interval in milliseconds */\n  exportInterval?: number;\n  /** Resource attributes */\n  resourceAttributes?: Record<string, string>;\n}\n\n/**\n * Grafana/Prometheus-specific configuration\n */\nexport interface MonitoringGrafanaAdapterConfig extends MonitoringObservabilityAdapterConfig {\n  /** Push gateway URL (for Prometheus) */\n  pushGatewayUrl?: string;\n  /** Grafana Cloud user */\n  grafanaCloudUser?: string;\n  /** Grafana Cloud API key */\n  grafanaCloudApiKey?: string;\n  /** Loki endpoint for logs */\n  lokiEndpoint?: string;\n  /** Tempo endpoint for traces */\n  tempoEndpoint?: string;\n}\n\n/**\n * Console adapter configuration (for development)\n */\nexport interface MonitoringConsoleAdapterConfig extends MonitoringObservabilityAdapterConfig {\n  /** Pretty print output */\n  prettyPrint?: boolean;\n  /** Include timestamps */\n  includeTimestamps?: boolean;\n  /** Log level filter */\n  logLevel?: MonitoringLogLevel;\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Composite Adapter Types (Parallel & Priority)\n// ─────────────────────────────────────────────────────────────────────────────\n\n/**\n * Mode for composite adapter\n */\nexport type MonitoringCompositeMode = 'parallel' | 'priority';\n\n/**\n * Configuration for composite adapter\n */\nexport interface MonitoringCompositeAdapterConfig extends MonitoringObservabilityAdapterConfig {\n  /** Execution mode */\n  mode: MonitoringCompositeMode;\n\n  /**\n   * Child adapters to use.\n   * For 'parallel': all adapters receive data simultaneously\n   * For 'priority': try first adapter, fallback to next on failure\n   */\n  adapters: MonitoringObservabilityAdapter[];\n\n  /**\n   * For 'priority' mode: continue to next adapter on these error types\n   * Default: all errors trigger fallback\n   */\n  fallbackOnErrors?: string[];\n\n  /**\n   * For 'parallel' mode: fail if any adapter fails (default: false)\n   * If false, logs errors but continues\n   */\n  failOnAnyError?: boolean;\n\n  /**\n   * Timeout for each adapter operation in ms (default: 5000)\n   */\n  adapterTimeout?: number;\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Service Integration Types\n// ─────────────────────────────────────────────────────────────────────────────\n\n/**\n * Operation context for service hooks\n */\nexport interface MonitoringOperationContext {\n  /** Service name */\n  serviceName: string;\n  /** Operation name (e.g., 'create', 'update', 'delete') */\n  operation: string;\n  /** Entity type (e.g., 'user', 'topic') */\n  entityType?: string;\n  /** Entity ID (if applicable) */\n  entityId?: string;\n  /** Start timestamp */\n  startTime: number;\n  /** Custom attributes */\n  attributes?: Record<string, unknown>;\n  /** Parent trace context */\n  parentContext?: MonitoringSpanContext;\n}\n\n/**\n * Operation result for service hooks\n */\nexport interface MonitoringOperationResult {\n  /** Whether operation succeeded */\n  success: boolean;\n  /** Duration in milliseconds */\n  duration: number;\n  /** Error (if failed) */\n  error?: Error;\n  /** Result data (optional) */\n  data?: unknown;\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Service Types\n// ─────────────────────────────────────────────────────────────────────────────\n\n/**\n * Adapter with priority and failover configuration.\n * Higher priority = tried first in priority mode, executed first in parallel mode.\n */\nexport interface MonitoringAdapterWithPriority {\n  /** The adapter instance (should be pre-initialized) */\n  adapter: MonitoringObservabilityAdapter;\n  /**\n   * Priority level (higher = more important)\n   * - In priority mode: higher priority adapters are tried first\n   * - In parallel mode: higher priority adapters are executed first\n   * Default: 0\n   */\n  priority?: number;\n  /**\n   * Mark this adapter as a failover/fallback adapter.\n   * - In parallel mode: failover adapters only receive data if primary adapters fail\n   * - In priority mode: failover adapters are only tried after all primary adapters fail\n   * Default: false\n   */\n  failover?: boolean;\n}\n\n/**\n * Internal adapter entry with resolved metadata.\n * Used by ObservabilityService to track adapter configuration.\n */\nexport interface MonitoringAdapterEntry {\n  /** The adapter instance */\n  adapter: MonitoringObservabilityAdapter;\n  /** Resolved priority level */\n  priority: number;\n  /** Whether this is a failover adapter */\n  failover: boolean;\n}\n\n/**\n * Configuration for ObservabilityService.\n *\n * Note: Adapter-specific configs (apiKey, endpoints, etc.) are NOT here.\n * Each adapter is initialized separately with its own config before being passed here.\n */\nexport interface MonitoringObservabilityServiceConfig {\n  /**\n   * Execution mode\n   * - 'single': Use only one adapter (default)\n   * - 'parallel': Send to all adapters simultaneously\n   * - 'priority': Try adapters in order, use first successful\n   */\n  mode?: 'single' | 'parallel' | 'priority';\n\n  /**\n   * Single adapter (for 'single' mode).\n   * Should be pre-initialized.\n   */\n  adapter?: MonitoringObservabilityAdapter | MonitoringAdapterWithPriority;\n\n  /**\n   * Multiple adapters (for 'parallel' or 'priority' mode).\n   * Can be plain adapters or adapters with priority config.\n   * Should be pre-initialized.\n   */\n  adapters?: (MonitoringObservabilityAdapter | MonitoringAdapterWithPriority)[];\n\n  /** Timeout for adapter operations in ms (default: 5000) */\n  adapterTimeout?: number;\n\n  /** For parallel mode: fail if any adapter fails (default: false) */\n  failOnAnyError?: boolean;\n\n  /** For priority mode: error types that trigger fallback (default: all) */\n  fallbackOnErrors?: string[];\n}\n\n/**\n * Interface for ObservabilityService (for dependency injection typing)\n */\nexport interface MonitoringObservabilityServiceInterface {\n  readonly isReady: boolean;\n\n  // Metrics\n  incrementCounter(name: string, value?: number, tags?: Record<string, string>): Promise<void>;\n  setGauge(name: string, value: number, tags?: Record<string, string>): Promise<void>;\n  recordHistogram(name: string, value: number, tags?: Record<string, string>): Promise<void>;\n  recordMetric(metric: MonitoringMetric): Promise<void>;\n\n  // Tracing\n  startSpan(options: MonitoringSpanOptions): MonitoringSpan;\n  withSpan<T>(options: MonitoringSpanOptions, fn: (span: MonitoringSpan) => Promise<T>): Promise<T>;\n  getActiveSpan(): MonitoringSpan | null;\n\n  // Logging\n  log(entry: MonitoringLogEntry): Promise<void>;\n\n  // Events\n  sendEvent(event: MonitoringObservabilityEvent): Promise<void>;\n\n  // Service operation helpers\n  trackOperation<T>(\n    context: MonitoringOperationContext,\n    operation: () => Promise<T>\n  ): Promise<{ result: T; metrics: MonitoringOperationResult }>;\n\n  // Lifecycle\n  shutdown(): Promise<void>;\n  flush(): Promise<void>;\n  isHealthy(): Promise<boolean>;\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Constants\n// ─────────────────────────────────────────────────────────────────────────────\n\n/**\n * Pre-defined metric names for consistency\n */\nexport const OBSERVABILITY_METRICS = {\n  // Service metrics\n  SERVICE_OPERATION_DURATION: 'service.operation.duration',\n  SERVICE_OPERATION_COUNT: 'service.operation.count',\n  SERVICE_OPERATION_ERROR: 'service.operation.error',\n\n  // Database metrics\n  DB_QUERY_DURATION: 'db.query.duration',\n  DB_QUERY_COUNT: 'db.query.count',\n  DB_CONNECTION_POOL_SIZE: 'db.connection.pool.size',\n  DB_CONNECTION_POOL_USED: 'db.connection.pool.used',\n\n  // Cache metrics\n  CACHE_HIT: 'cache.hit',\n  CACHE_MISS: 'cache.miss',\n  CACHE_SET: 'cache.set',\n  CACHE_DELETE: 'cache.delete',\n\n  // API metrics\n  API_REQUEST_DURATION: 'api.request.duration',\n  API_REQUEST_COUNT: 'api.request.count',\n  API_REQUEST_ERROR: 'api.request.error',\n\n  // Transaction metrics\n  TRANSACTION_DURATION: 'transaction.duration',\n  TRANSACTION_COUNT: 'transaction.count',\n  TRANSACTION_ROLLBACK: 'transaction.rollback',\n} as const;\n\n/**\n * Pre-defined span names for consistency\n */\nexport const OBSERVABILITY_SPANS = {\n  SERVICE_CREATE: 'service.create',\n  SERVICE_UPDATE: 'service.update',\n  SERVICE_DELETE: 'service.delete',\n  SERVICE_GET: 'service.get',\n  SERVICE_LIST: 'service.list',\n  SERVICE_BULK_CREATE: 'service.bulk_create',\n  SERVICE_BULK_DELETE: 'service.bulk_delete',\n  SERVICE_TRANSACTION: 'service.transaction',\n  DB_QUERY: 'db.query',\n  CACHE_GET: 'cache.get',\n  CACHE_SET: 'cache.set',\n  API_REQUEST: 'api.request',\n} as const;\n"]}

package/dist/observability/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Observability Types
+ *
+ * Adapter-based observability system for metrics, tracing, and logging.
+ * All types use "Monitoring" prefix for this dedicated module.
+ */
+export type { MonitoringObservabilityProvider, MonitoringMetricType, MonitoringSpanStatus, MonitoringLogLevel, MonitoringMetricOptions, MonitoringCounterMetric, MonitoringGaugeMetric, MonitoringHistogramMetric, MonitoringSummaryMetric, MonitoringMetric, MonitoringSpanContext, MonitoringSpanAttributes, MonitoringSpanEvent, MonitoringSpanOptions, MonitoringSpan, MonitoringLogEntry, MonitoringObservabilityEvent, MonitoringObservabilityAdapter, MonitoringObservabilityAdapterConfig, MonitoringDatadogAdapterConfig, MonitoringOpenTelemetryAdapterConfig, MonitoringGrafanaAdapterConfig, MonitoringConsoleAdapterConfig, MonitoringCompositeMode, MonitoringCompositeAdapterConfig, MonitoringOperationContext, MonitoringOperationResult, MonitoringAdapterWithPriority, MonitoringAdapterEntry, MonitoringObservabilityServiceConfig, MonitoringObservabilityServiceInterface, } from './types';
+export { OBSERVABILITY_METRICS, OBSERVABILITY_SPANS } from './types';
+export type { MonitoringObservabilityProvider as ObservabilityProvider, MonitoringMetricType as MetricType, MonitoringSpanStatus as SpanStatus, MonitoringMetricOptions as MetricOptions, MonitoringCounterMetric as CounterMetric, MonitoringGaugeMetric as GaugeMetric, MonitoringHistogramMetric as HistogramMetric, MonitoringSummaryMetric as SummaryMetric, MonitoringMetric as Metric, MonitoringSpanContext as SpanContext, MonitoringSpanAttributes as SpanAttributes, MonitoringSpanEvent as SpanEvent, MonitoringSpanOptions as SpanOptions, MonitoringSpan as Span, MonitoringLogEntry as LogEntry, MonitoringObservabilityEvent as ObservabilityEvent, MonitoringObservabilityAdapter as ObservabilityAdapter, MonitoringObservabilityAdapterConfig as ObservabilityAdapterConfig, MonitoringDatadogAdapterConfig as DatadogAdapterConfig, MonitoringOpenTelemetryAdapterConfig as OpenTelemetryAdapterConfig, MonitoringGrafanaAdapterConfig as GrafanaAdapterConfig, MonitoringConsoleAdapterConfig as ConsoleAdapterConfig, MonitoringCompositeMode as CompositeMode, MonitoringCompositeAdapterConfig as CompositeAdapterConfig, MonitoringOperationContext as OperationContext, MonitoringAdapterWithPriority as AdapterWithPriority, MonitoringAdapterEntry as AdapterEntry, MonitoringObservabilityServiceConfig as ObservabilityServiceConfig, MonitoringObservabilityServiceInterface as ObservabilityServiceInterface, } from './types';
+export type { HotShotsConfig, HotShotsClient, DDTraceConfig, DDSpanContext, DDSpan, DDSpanOptions, DDScope, DDTracer, DDTraceModule, } from './datadog-sdk';

package/dist/observability/index.js

@@ -0,0 +1,45 @@
+// @plyaz package - Built with tsup
+
+// src/observability/types.ts
+var OBSERVABILITY_METRICS = {
+  // Service metrics
+  SERVICE_OPERATION_DURATION: "service.operation.duration",
+  SERVICE_OPERATION_COUNT: "service.operation.count",
+  SERVICE_OPERATION_ERROR: "service.operation.error",
+  // Database metrics
+  DB_QUERY_DURATION: "db.query.duration",
+  DB_QUERY_COUNT: "db.query.count",
+  DB_CONNECTION_POOL_SIZE: "db.connection.pool.size",
+  DB_CONNECTION_POOL_USED: "db.connection.pool.used",
+  // Cache metrics
+  CACHE_HIT: "cache.hit",
+  CACHE_MISS: "cache.miss",
+  CACHE_SET: "cache.set",
+  CACHE_DELETE: "cache.delete",
+  // API metrics
+  API_REQUEST_DURATION: "api.request.duration",
+  API_REQUEST_COUNT: "api.request.count",
+  API_REQUEST_ERROR: "api.request.error",
+  // Transaction metrics
+  TRANSACTION_DURATION: "transaction.duration",
+  TRANSACTION_COUNT: "transaction.count",
+  TRANSACTION_ROLLBACK: "transaction.rollback"
+};
+var OBSERVABILITY_SPANS = {
+  SERVICE_CREATE: "service.create",
+  SERVICE_UPDATE: "service.update",
+  SERVICE_DELETE: "service.delete",
+  SERVICE_GET: "service.get",
+  SERVICE_LIST: "service.list",
+  SERVICE_BULK_CREATE: "service.bulk_create",
+  SERVICE_BULK_DELETE: "service.bulk_delete",
+  SERVICE_TRANSACTION: "service.transaction",
+  DB_QUERY: "db.query",
+  CACHE_GET: "cache.get",
+  CACHE_SET: "cache.set",
+  API_REQUEST: "api.request"
+};
+
+export { OBSERVABILITY_METRICS, OBSERVABILITY_SPANS };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/observability/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/observability/types.ts"],"names":[],"mappings":";;;AAkpBO,IAAM,qBAAA,GAAwB;AAAA;AAAA,EAEnC,0BAAA,EAA4B,4BAAA;AAAA,EAC5B,uBAAA,EAAyB,yBAAA;AAAA,EACzB,uBAAA,EAAyB,yBAAA;AAAA;AAAA,EAGzB,iBAAA,EAAmB,mBAAA;AAAA,EACnB,cAAA,EAAgB,gBAAA;AAAA,EAChB,uBAAA,EAAyB,yBAAA;AAAA,EACzB,uBAAA,EAAyB,yBAAA;AAAA;AAAA,EAGzB,SAAA,EAAW,WAAA;AAAA,EACX,UAAA,EAAY,YAAA;AAAA,EACZ,SAAA,EAAW,WAAA;AAAA,EACX,YAAA,EAAc,cAAA;AAAA;AAAA,EAGd,oBAAA,EAAsB,sBAAA;AAAA,EACtB,iBAAA,EAAmB,mBAAA;AAAA,EACnB,iBAAA,EAAmB,mBAAA;AAAA;AAAA,EAGnB,oBAAA,EAAsB,sBAAA;AAAA,EACtB,iBAAA,EAAmB,mBAAA;AAAA,EACnB,oBAAA,EAAsB;AACxB;AAKO,IAAM,mBAAA,GAAsB;AAAA,EACjC,cAAA,EAAgB,gBAAA;AAAA,EAChB,cAAA,EAAgB,gBAAA;AAAA,EAChB,cAAA,EAAgB,gBAAA;AAAA,EAChB,WAAA,EAAa,aAAA;AAAA,EACb,YAAA,EAAc,cAAA;AAAA,EACd,mBAAA,EAAqB,qBAAA;AAAA,EACrB,mBAAA,EAAqB,qBAAA;AAAA,EACrB,mBAAA,EAAqB,qBAAA;AAAA,EACrB,QAAA,EAAU,UAAA;AAAA,EACV,SAAA,EAAW,WAAA;AAAA,EACX,SAAA,EAAW,WAAA;AAAA,EACX,WAAA,EAAa;AACf","file":"index.js","sourcesContent":["/**\n * Monitoring/Observability Types\n *\n * Adapter-based observability system supporting multiple providers\n * (Datadog, Grafana, OpenTelemetry, etc.) with parallel and priority modes.\n *\n * All types are prefixed with \"Monitoring\" for this dedicated module.\n *\n * @module observability/types\n */\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Monitoring Types\n// ─────────────────────────────────────────────────────────────────────────────\n\n/**\n * Supported observability providers\n * Currently implemented: 'datadog', 'console', 'noop'\n * Planned: 'grafana', 'opentelemetry', 'prometheus', 'newrelic', 'custom'\n */\nexport type MonitoringObservabilityProvider =\n  | 'datadog'\n  | 'console'\n  | 'noop'\n  // Planned providers (uncomment when implemented):\n  // | 'grafana'\n  // | 'opentelemetry'\n  // | 'prometheus'\n  // | 'newrelic'\n  | 'custom';\n\n/**\n * Metric types\n */\nexport type MonitoringMetricType = 'counter' | 'gauge' | 'histogram' | 'summary';\n\n/**\n * Span status for tracing\n */\nexport type MonitoringSpanStatus = 'ok' | 'error' | 'unset';\n\n/**\n * Log levels\n */\nexport type MonitoringLogLevel = 'debug' | 'info' | 'warn' | 'error' | 'fatal';\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Metric Types\n// ─────────────────────────────────────────────────────────────────────────────\n\n/**\n * Base metric options\n */\nexport interface MonitoringMetricOptions {\n  /** Metric name (e.g., 'http.request.duration') */\n  name: string;\n  /** Human-readable description */\n  description?: string;\n  /** Unit of measurement (e.g., 'ms', 'bytes', 'count') */\n  unit?: string;\n  /** Tags/labels for the metric */\n  tags?: Record<string, string | number | boolean>;\n}\n\n/**\n * Counter metric (monotonically increasing)\n */\nexport interface MonitoringCounterMetric extends MonitoringMetricOptions {\n  type: 'counter';\n  /** Value to increment by (default: 1) */\n  value?: number;\n}\n\n/**\n * Gauge metric (can go up or down)\n */\nexport interface MonitoringGaugeMetric extends MonitoringMetricOptions {\n  type: 'gauge';\n  /** Current value */\n  value: number;\n}\n\n/**\n * Histogram metric (distribution of values)\n */\nexport interface MonitoringHistogramMetric extends MonitoringMetricOptions {\n  type: 'histogram';\n  /** Value to record */\n  value: number;\n  /** Bucket boundaries (optional) */\n  buckets?: number[];\n}\n\n/**\n * Summary metric (percentiles)\n */\nexport interface MonitoringSummaryMetric extends MonitoringMetricOptions {\n  type: 'summary';\n  /** Value to record */\n  value: number;\n  /** Percentiles to track (e.g., [0.5, 0.9, 0.99]) */\n  percentiles?: number[];\n}\n\n/**\n * Union of all metric types\n */\nexport type MonitoringMetric =\n  | MonitoringCounterMetric\n  | MonitoringGaugeMetric\n  | MonitoringHistogramMetric\n  | MonitoringSummaryMetric;\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Tracing Types\n// ─────────────────────────────────────────────────────────────────────────────\n\n/**\n * Span context for distributed tracing\n */\nexport interface MonitoringSpanContext {\n  /** Unique trace ID */\n  traceId: string;\n  /** Unique span ID */\n  spanId: string;\n  /** Parent span ID (if any) */\n  parentSpanId?: string;\n  /** Sampling decision */\n  sampled?: boolean;\n}\n\n/**\n * Span attributes following OpenTelemetry semantic conventions.\n * Property names use dot notation as per OTel spec (e.g., 'service.name').\n */\n\nexport interface MonitoringSpanAttributes {\n  /** Service name */\n  // eslint-disable-next-line @typescript-eslint/naming-convention\n  'service.name'?: string;\n  /** Operation name */\n  // eslint-disable-next-line @typescript-eslint/naming-convention\n  'operation.name'?: string;\n  /** HTTP method */\n  // eslint-disable-next-line @typescript-eslint/naming-convention\n  'http.method'?: string;\n  /** HTTP URL */\n  // eslint-disable-next-line @typescript-eslint/naming-convention\n  'http.url'?: string;\n  /** HTTP status code */\n  // eslint-disable-next-line @typescript-eslint/naming-convention\n  'http.status_code'?: number;\n  /** Database system */\n  // eslint-disable-next-line @typescript-eslint/naming-convention\n  'db.system'?: string;\n  /** Database statement */\n  // eslint-disable-next-line @typescript-eslint/naming-convention\n  'db.statement'?: string;\n  /** Error flag */\n  error?: boolean;\n  /** Error message */\n  // eslint-disable-next-line @typescript-eslint/naming-convention\n  'error.message'?: string;\n  /** Custom attributes */\n  [key: string]: string | number | boolean | undefined;\n}\n\n/**\n * Span event (point-in-time occurrence within a span)\n */\nexport interface MonitoringSpanEvent {\n  /** Event name */\n  name: string;\n  /** Event timestamp */\n  timestamp?: number;\n  /** Event attributes */\n  attributes?: Record<string, string | number | boolean>;\n}\n\n/**\n * Options for creating a span\n */\nexport interface MonitoringSpanOptions {\n  /** Span name (operation being traced) */\n  name: string;\n  /** Span kind */\n  kind?: 'internal' | 'server' | 'client' | 'producer' | 'consumer';\n  /** Initial attributes */\n  attributes?: MonitoringSpanAttributes;\n  /** Parent span context (for distributed tracing) */\n  parentContext?: MonitoringSpanContext;\n  /** Start time (default: now) */\n  startTime?: number;\n}\n\n/**\n * Active span interface\n */\nexport interface MonitoringSpan {\n  /** Span context */\n  context: MonitoringSpanContext;\n  /** Set attribute on span */\n  setAttribute(key: string, value: string | number | boolean): void;\n  /** Set multiple attributes */\n  setAttributes(attributes: MonitoringSpanAttributes): void;\n  /** Add event to span */\n  addEvent(event: MonitoringSpanEvent): void;\n  /** Set span status */\n  setStatus(status: MonitoringSpanStatus, message?: string): void;\n  /** End the span */\n  end(endTime?: number): void;\n  /** Record exception */\n  recordException(error: Error): void;\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Logging Types\n// ─────────────────────────────────────────────────────────────────────────────\n\n/**\n * Structured log entry\n */\nexport interface MonitoringLogEntry {\n  /** Log level */\n  level: MonitoringLogLevel;\n  /** Log message */\n  message: string;\n  /** Timestamp */\n  timestamp?: number;\n  /** Service/component name */\n  service?: string;\n  /** Additional context */\n  context?: Record<string, unknown>;\n  /** Associated trace ID */\n  traceId?: string;\n  /** Associated span ID */\n  spanId?: string;\n  /** Error object (if logging an error) */\n  error?: Error;\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Event Types\n// ─────────────────────────────────────────────────────────────────────────────\n\n/**\n * Custom event for observability\n */\nexport interface MonitoringObservabilityEvent {\n  /** Event name */\n  name: string;\n  /** Event timestamp */\n  timestamp?: number;\n  /** Event properties */\n  properties?: Record<string, unknown>;\n  /** Associated tags */\n  tags?: Record<string, string>;\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Adapter Interface\n// ─────────────────────────────────────────────────────────────────────────────\n\n/**\n * Base observability adapter interface.\n *\n * All observability providers (Datadog, Grafana, OpenTelemetry, etc.)\n * must implement this interface.\n *\n * @example\n * ```typescript\n * class DatadogAdapter implements ObservabilityAdapter {\n *   readonly provider = 'datadog';\n *   readonly name = 'DatadogAdapter';\n *\n *   async initialize(config: DatadogConfig): Promise<void> {\n *     // Initialize Datadog client\n *   }\n *\n *   async recordMetric(metric: Metric): Promise<void> {\n *     // Send to Datadog\n *   }\n *\n *   // ... other methods\n * }\n * ```\n */\nexport interface MonitoringObservabilityAdapter {\n  /** Provider type */\n  readonly provider: MonitoringObservabilityProvider;\n\n  /** Adapter name for logging */\n  readonly name: string;\n\n  /** Whether the adapter is initialized */\n  readonly isInitialized: boolean;\n\n  // ─── Lifecycle ─────────────────────────────────────────────────────────────\n\n  /**\n   * Initialize the adapter with provider-specific config\n   */\n  initialize(config: MonitoringObservabilityAdapterConfig): Promise<void>;\n\n  /**\n   * Shutdown/cleanup the adapter\n   */\n  shutdown(): Promise<void>;\n\n  /**\n   * Check if adapter is healthy/connected\n   */\n  isHealthy(): Promise<boolean>;\n\n  // ─── Metrics ───────────────────────────────────────────────────────────────\n\n  /**\n   * Record a metric\n   */\n  recordMetric(metric: MonitoringMetric): Promise<void>;\n\n  /**\n   * Increment a counter\n   */\n  incrementCounter(name: string, value?: number, tags?: Record<string, string>): Promise<void>;\n\n  /**\n   * Set a gauge value\n   */\n  setGauge(name: string, value: number, tags?: Record<string, string>): Promise<void>;\n\n  /**\n   * Record a histogram value\n   */\n  recordHistogram(name: string, value: number, tags?: Record<string, string>): Promise<void>;\n\n  // ─── Tracing ───────────────────────────────────────────────────────────────\n\n  /**\n   * Start a new span\n   */\n  startSpan(options: MonitoringSpanOptions): MonitoringSpan;\n\n  /**\n   * Get current active span (if any)\n   */\n  getActiveSpan(): MonitoringSpan | null;\n\n  /**\n   * Run a function within a span\n   */\n  withSpan<T>(options: MonitoringSpanOptions, fn: (span: MonitoringSpan) => Promise<T>): Promise<T>;\n\n  // ─── Logging ───────────────────────────────────────────────────────────────\n\n  /**\n   * Send a log entry\n   */\n  log(entry: MonitoringLogEntry): Promise<void>;\n\n  // ─── Events ────────────────────────────────────────────────────────────────\n\n  /**\n   * Send a custom event\n   */\n  sendEvent(event: MonitoringObservabilityEvent): Promise<void>;\n\n  // ─── Flush ─────────────────────────────────────────────────────────────────\n\n  /**\n   * Flush any buffered data\n   */\n  flush(): Promise<void>;\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Adapter Configuration\n// ─────────────────────────────────────────────────────────────────────────────\n\n/**\n * Base adapter configuration\n */\nexport interface MonitoringObservabilityAdapterConfig {\n  /** Enable/disable the adapter */\n  enabled?: boolean;\n  /** Service name for tagging */\n  serviceName?: string;\n  /** Environment (production, staging, development) */\n  environment?: string;\n  /** Default tags to add to all metrics/spans */\n  defaultTags?: Record<string, string>;\n  /** Sampling rate for traces (0.0 to 1.0) */\n  samplingRate?: number;\n  /** Flush interval in milliseconds */\n  flushInterval?: number;\n  /** Buffer size before auto-flush */\n  bufferSize?: number;\n}\n\n/**\n * Datadog-specific configuration\n */\nexport interface MonitoringDatadogAdapterConfig extends MonitoringObservabilityAdapterConfig {\n  /** Datadog API key */\n  apiKey: string;\n  /** Datadog site (e.g., 'datadoghq.com', 'datadoghq.eu') */\n  site?: string;\n  /** Enable APM tracing */\n  apmEnabled?: boolean;\n  /** Enable RUM (Real User Monitoring) */\n  rumEnabled?: boolean;\n  /** RUM application ID */\n  rumApplicationId?: string;\n  /** RUM client token */\n  rumClientToken?: string;\n}\n\n/**\n * OpenTelemetry-specific configuration\n */\nexport interface MonitoringOpenTelemetryAdapterConfig extends MonitoringObservabilityAdapterConfig {\n  /** OTLP endpoint URL */\n  endpoint: string;\n  /** Headers for OTLP exporter */\n  headers?: Record<string, string>;\n  /** Export interval in milliseconds */\n  exportInterval?: number;\n  /** Resource attributes */\n  resourceAttributes?: Record<string, string>;\n}\n\n/**\n * Grafana/Prometheus-specific configuration\n */\nexport interface MonitoringGrafanaAdapterConfig extends MonitoringObservabilityAdapterConfig {\n  /** Push gateway URL (for Prometheus) */\n  pushGatewayUrl?: string;\n  /** Grafana Cloud user */\n  grafanaCloudUser?: string;\n  /** Grafana Cloud API key */\n  grafanaCloudApiKey?: string;\n  /** Loki endpoint for logs */\n  lokiEndpoint?: string;\n  /** Tempo endpoint for traces */\n  tempoEndpoint?: string;\n}\n\n/**\n * Console adapter configuration (for development)\n */\nexport interface MonitoringConsoleAdapterConfig extends MonitoringObservabilityAdapterConfig {\n  /** Pretty print output */\n  prettyPrint?: boolean;\n  /** Include timestamps */\n  includeTimestamps?: boolean;\n  /** Log level filter */\n  logLevel?: MonitoringLogLevel;\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Composite Adapter Types (Parallel & Priority)\n// ─────────────────────────────────────────────────────────────────────────────\n\n/**\n * Mode for composite adapter\n */\nexport type MonitoringCompositeMode = 'parallel' | 'priority';\n\n/**\n * Configuration for composite adapter\n */\nexport interface MonitoringCompositeAdapterConfig extends MonitoringObservabilityAdapterConfig {\n  /** Execution mode */\n  mode: MonitoringCompositeMode;\n\n  /**\n   * Child adapters to use.\n   * For 'parallel': all adapters receive data simultaneously\n   * For 'priority': try first adapter, fallback to next on failure\n   */\n  adapters: MonitoringObservabilityAdapter[];\n\n  /**\n   * For 'priority' mode: continue to next adapter on these error types\n   * Default: all errors trigger fallback\n   */\n  fallbackOnErrors?: string[];\n\n  /**\n   * For 'parallel' mode: fail if any adapter fails (default: false)\n   * If false, logs errors but continues\n   */\n  failOnAnyError?: boolean;\n\n  /**\n   * Timeout for each adapter operation in ms (default: 5000)\n   */\n  adapterTimeout?: number;\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Service Integration Types\n// ─────────────────────────────────────────────────────────────────────────────\n\n/**\n * Operation context for service hooks\n */\nexport interface MonitoringOperationContext {\n  /** Service name */\n  serviceName: string;\n  /** Operation name (e.g., 'create', 'update', 'delete') */\n  operation: string;\n  /** Entity type (e.g., 'user', 'topic') */\n  entityType?: string;\n  /** Entity ID (if applicable) */\n  entityId?: string;\n  /** Start timestamp */\n  startTime: number;\n  /** Custom attributes */\n  attributes?: Record<string, unknown>;\n  /** Parent trace context */\n  parentContext?: MonitoringSpanContext;\n}\n\n/**\n * Operation result for service hooks\n */\nexport interface MonitoringOperationResult {\n  /** Whether operation succeeded */\n  success: boolean;\n  /** Duration in milliseconds */\n  duration: number;\n  /** Error (if failed) */\n  error?: Error;\n  /** Result data (optional) */\n  data?: unknown;\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Service Types\n// ─────────────────────────────────────────────────────────────────────────────\n\n/**\n * Adapter with priority and failover configuration.\n * Higher priority = tried first in priority mode, executed first in parallel mode.\n */\nexport interface MonitoringAdapterWithPriority {\n  /** The adapter instance (should be pre-initialized) */\n  adapter: MonitoringObservabilityAdapter;\n  /**\n   * Priority level (higher = more important)\n   * - In priority mode: higher priority adapters are tried first\n   * - In parallel mode: higher priority adapters are executed first\n   * Default: 0\n   */\n  priority?: number;\n  /**\n   * Mark this adapter as a failover/fallback adapter.\n   * - In parallel mode: failover adapters only receive data if primary adapters fail\n   * - In priority mode: failover adapters are only tried after all primary adapters fail\n   * Default: false\n   */\n  failover?: boolean;\n}\n\n/**\n * Internal adapter entry with resolved metadata.\n * Used by ObservabilityService to track adapter configuration.\n */\nexport interface MonitoringAdapterEntry {\n  /** The adapter instance */\n  adapter: MonitoringObservabilityAdapter;\n  /** Resolved priority level */\n  priority: number;\n  /** Whether this is a failover adapter */\n  failover: boolean;\n}\n\n/**\n * Configuration for ObservabilityService.\n *\n * Note: Adapter-specific configs (apiKey, endpoints, etc.) are NOT here.\n * Each adapter is initialized separately with its own config before being passed here.\n */\nexport interface MonitoringObservabilityServiceConfig {\n  /**\n   * Execution mode\n   * - 'single': Use only one adapter (default)\n   * - 'parallel': Send to all adapters simultaneously\n   * - 'priority': Try adapters in order, use first successful\n   */\n  mode?: 'single' | 'parallel' | 'priority';\n\n  /**\n   * Single adapter (for 'single' mode).\n   * Should be pre-initialized.\n   */\n  adapter?: MonitoringObservabilityAdapter | MonitoringAdapterWithPriority;\n\n  /**\n   * Multiple adapters (for 'parallel' or 'priority' mode).\n   * Can be plain adapters or adapters with priority config.\n   * Should be pre-initialized.\n   */\n  adapters?: (MonitoringObservabilityAdapter | MonitoringAdapterWithPriority)[];\n\n  /** Timeout for adapter operations in ms (default: 5000) */\n  adapterTimeout?: number;\n\n  /** For parallel mode: fail if any adapter fails (default: false) */\n  failOnAnyError?: boolean;\n\n  /** For priority mode: error types that trigger fallback (default: all) */\n  fallbackOnErrors?: string[];\n}\n\n/**\n * Interface for ObservabilityService (for dependency injection typing)\n */\nexport interface MonitoringObservabilityServiceInterface {\n  readonly isReady: boolean;\n\n  // Metrics\n  incrementCounter(name: string, value?: number, tags?: Record<string, string>): Promise<void>;\n  setGauge(name: string, value: number, tags?: Record<string, string>): Promise<void>;\n  recordHistogram(name: string, value: number, tags?: Record<string, string>): Promise<void>;\n  recordMetric(metric: MonitoringMetric): Promise<void>;\n\n  // Tracing\n  startSpan(options: MonitoringSpanOptions): MonitoringSpan;\n  withSpan<T>(options: MonitoringSpanOptions, fn: (span: MonitoringSpan) => Promise<T>): Promise<T>;\n  getActiveSpan(): MonitoringSpan | null;\n\n  // Logging\n  log(entry: MonitoringLogEntry): Promise<void>;\n\n  // Events\n  sendEvent(event: MonitoringObservabilityEvent): Promise<void>;\n\n  // Service operation helpers\n  trackOperation<T>(\n    context: MonitoringOperationContext,\n    operation: () => Promise<T>\n  ): Promise<{ result: T; metrics: MonitoringOperationResult }>;\n\n  // Lifecycle\n  shutdown(): Promise<void>;\n  flush(): Promise<void>;\n  isHealthy(): Promise<boolean>;\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Constants\n// ─────────────────────────────────────────────────────────────────────────────\n\n/**\n * Pre-defined metric names for consistency\n */\nexport const OBSERVABILITY_METRICS = {\n  // Service metrics\n  SERVICE_OPERATION_DURATION: 'service.operation.duration',\n  SERVICE_OPERATION_COUNT: 'service.operation.count',\n  SERVICE_OPERATION_ERROR: 'service.operation.error',\n\n  // Database metrics\n  DB_QUERY_DURATION: 'db.query.duration',\n  DB_QUERY_COUNT: 'db.query.count',\n  DB_CONNECTION_POOL_SIZE: 'db.connection.pool.size',\n  DB_CONNECTION_POOL_USED: 'db.connection.pool.used',\n\n  // Cache metrics\n  CACHE_HIT: 'cache.hit',\n  CACHE_MISS: 'cache.miss',\n  CACHE_SET: 'cache.set',\n  CACHE_DELETE: 'cache.delete',\n\n  // API metrics\n  API_REQUEST_DURATION: 'api.request.duration',\n  API_REQUEST_COUNT: 'api.request.count',\n  API_REQUEST_ERROR: 'api.request.error',\n\n  // Transaction metrics\n  TRANSACTION_DURATION: 'transaction.duration',\n  TRANSACTION_COUNT: 'transaction.count',\n  TRANSACTION_ROLLBACK: 'transaction.rollback',\n} as const;\n\n/**\n * Pre-defined span names for consistency\n */\nexport const OBSERVABILITY_SPANS = {\n  SERVICE_CREATE: 'service.create',\n  SERVICE_UPDATE: 'service.update',\n  SERVICE_DELETE: 'service.delete',\n  SERVICE_GET: 'service.get',\n  SERVICE_LIST: 'service.list',\n  SERVICE_BULK_CREATE: 'service.bulk_create',\n  SERVICE_BULK_DELETE: 'service.bulk_delete',\n  SERVICE_TRANSACTION: 'service.transaction',\n  DB_QUERY: 'db.query',\n  CACHE_GET: 'cache.get',\n  CACHE_SET: 'cache.set',\n  API_REQUEST: 'api.request',\n} as const;\n"]}