@iii-dev/observability 0.13.0-next.1

package/dist/index.d.mts

@@ -0,0 +1,409 @@
+import { Logger as Logger$1, SeverityNumber } from "@opentelemetry/api-logs";
+import { AttributeValue, Attributes, Context, Meter, Meter as Meter$1, Span, SpanKind, Tracer, Tracer as Tracer$1 } from "@opentelemetry/api";
+import { ReadableSpan, Span as Span$1, SpanProcessor } from "@opentelemetry/sdk-trace-base";
+import { Instrumentation } from "@opentelemetry/instrumentation";
+
+//#region src/logger.d.ts
+/**
+ * Structured logger that emits logs as OpenTelemetry LogRecords.
+ *
+ * Every log call automatically captures the active trace and span context,
+ * correlating your logs with distributed traces without any manual wiring.
+ * When OTel is not initialized, Logger gracefully falls back to `console.*`.
+ *
+ * Pass structured data as the second argument to any log method. Using an
+ * object of key-value pairs (instead of string interpolation) lets you
+ * filter, aggregate, and build dashboards in your observability backend.
+ *
+ * @example
+ * ```typescript
+ * import { Logger } from 'iii-sdk'
+ *
+ * const logger = new Logger()
+ *
+ * // Basic logging — trace context is injected automatically
+ * logger.info('Worker connected')
+ *
+ * // Structured context for dashboards and alerting
+ * logger.info('Order processed', { orderId: 'ord_123', amount: 49.99, currency: 'USD' })
+ * logger.warn('Retry attempt', { attempt: 3, maxRetries: 5, endpoint: '/api/charge' })
+ * logger.error('Payment failed', { orderId: 'ord_123', gateway: 'stripe', errorCode: 'card_declined' })
+ * ```
+ */
+declare class Logger {
+  private readonly traceId?;
+  private readonly serviceName?;
+  private readonly spanId?;
+  private _otelLogger;
+  private get otelLogger();
+  constructor(traceId?: string | undefined, serviceName?: string | undefined, spanId?: string | undefined);
+  private emit;
+  /**
+   * Log an info-level message.
+   *
+   * @param message - Human-readable log message.
+   * @param data - Structured context attached as OTel log attributes.
+   *   Use key-value objects to enable filtering and aggregation in your
+   *   observability backend (e.g. Grafana, Datadog, New Relic).
+   *
+   * @example
+   * ```typescript
+   * logger.info('Order processed', { orderId: 'ord_123', status: 'completed' })
+   * ```
+   */
+  info(message: string, data?: unknown): void;
+  /**
+   * Log a warning-level message.
+   *
+   * @param message - Human-readable log message.
+   * @param data - Structured context attached as OTel log attributes.
+   *   Use key-value objects to enable filtering and aggregation in your
+   *   observability backend (e.g. Grafana, Datadog, New Relic).
+   *
+   * @example
+   * ```typescript
+   * logger.warn('Retry attempt', { attempt: 3, maxRetries: 5, endpoint: '/api/charge' })
+   * ```
+   */
+  warn(message: string, data?: unknown): void;
+  /**
+   * Log an error-level message.
+   *
+   * @param message - Human-readable log message.
+   * @param data - Structured context attached as OTel log attributes.
+   *   Use key-value objects to enable filtering and aggregation in your
+   *   observability backend (e.g. Grafana, Datadog, New Relic).
+   *
+   * @example
+   * ```typescript
+   * logger.error('Payment failed', { orderId: 'ord_123', gateway: 'stripe', errorCode: 'card_declined' })
+   * ```
+   */
+  error(message: string, data?: unknown): void;
+  /**
+   * Log a debug-level message.
+   *
+   * @param message - Human-readable log message.
+   * @param data - Structured context attached as OTel log attributes.
+   *   Use key-value objects to enable filtering and aggregation in your
+   *   observability backend (e.g. Grafana, Datadog, New Relic).
+   *
+   * @example
+   * ```typescript
+   * logger.debug('Cache lookup', { key: 'user:42', hit: false })
+   * ```
+   */
+  debug(message: string, data?: unknown): void;
+}
+//#endregion
+//#region src/http-instrumentation.d.ts
+interface TracedFetchInit extends RequestInit {
+  tracer?: Tracer;
+}
+/**
+ * Execute a fetch request inside an OTel CLIENT span.
+ *
+ * Mirrors the Rust execute_traced_request shape: injects W3C traceparent into
+ * outgoing headers, records HTTP semantic-convention attributes, and sets
+ * ERROR span status for HTTP responses with status >= 400 or network errors.
+ */
+declare function executeTracedRequest(input: RequestInfo | URL, init?: TracedFetchInit): Promise<Response>;
+//#endregion
+//#region src/telemetry-system/types.d.ts
+/** Configuration for WebSocket reconnection behavior */
+interface ReconnectionConfig {
+  /** Starting delay in milliseconds (default: 1000ms) */
+  initialDelayMs: number;
+  /** Maximum delay cap in milliseconds (default: 30000ms) */
+  maxDelayMs: number;
+  /** Exponential backoff multiplier (default: 2) */
+  backoffMultiplier: number;
+  /** Random jitter factor 0-1 (default: 0.3) */
+  jitterFactor: number;
+  /** Maximum retry attempts, -1 for infinite (default: -1) */
+  maxRetries: number;
+}
+/** Configuration for OpenTelemetry initialization. */
+interface OtelConfig {
+  /** Whether OpenTelemetry export is enabled. Defaults to true. Set to false or OTEL_ENABLED=false/0/no/off to disable. */
+  enabled?: boolean;
+  /** The service name to report. Defaults to OTEL_SERVICE_NAME or "iii-node". */
+  serviceName?: string;
+  /** The service version to report. Defaults to SERVICE_VERSION env var or "unknown". */
+  serviceVersion?: string;
+  /** The service namespace to report. Defaults to SERVICE_NAMESPACE env var. */
+  serviceNamespace?: string;
+  /** The service instance ID to report. Defaults to SERVICE_INSTANCE_ID env var or auto-generated UUID. */
+  serviceInstanceId?: string;
+  /** III Engine WebSocket URL. Defaults to III_URL or "ws://localhost:49134". */
+  engineWsUrl?: string;
+  /** OpenTelemetry instrumentations to register (e.g., PrismaInstrumentation). */
+  instrumentations?: Instrumentation[];
+  /** Whether OpenTelemetry metrics export is enabled. Defaults to true. Set to false or OTEL_METRICS_ENABLED=false/0/no/off to disable. */
+  metricsEnabled?: boolean;
+  /** Metrics export interval in milliseconds. Defaults to 60000 (60 seconds). */
+  metricsExportIntervalMs?: number;
+  /** Log processor flush delay in milliseconds. Defaults to 100ms. */
+  logsFlushIntervalMs?: number;
+  /** Maximum number of log records exported per batch. Defaults to 1. */
+  logsBatchSize?: number;
+  /** Whether to auto-instrument globalThis.fetch calls. Defaults to true. Works on Node.js, Bun, and Deno. Set to false to disable. */
+  fetchInstrumentationEnabled?: boolean;
+  /** Optional reconnection configuration for the WebSocket connection. */
+  reconnectionConfig?: Partial<ReconnectionConfig>;
+}
+//#endregion
+//#region src/telemetry-system/context.d.ts
+/**
+ * Extract the current trace ID from the active span context.
+ */
+declare function currentTraceId(): string | undefined;
+/**
+ * Extract the current span ID from the active span context.
+ */
+declare function currentSpanId(): string | undefined;
+/**
+ * Inject the current trace context into a W3C traceparent header string.
+ */
+declare function injectTraceparent(): string | undefined;
+/**
+ * Extract a trace context from a W3C traceparent header string.
+ */
+declare function extractTraceparent(traceparent: string): Context;
+/**
+ * Inject the current baggage into a W3C baggage header string.
+ */
+declare function injectBaggage(): string | undefined;
+/**
+ * Extract baggage from a W3C baggage header string.
+ */
+declare function extractBaggage(baggage: string): Context;
+/**
+ * Extract both trace context and baggage from their respective headers.
+ */
+declare function extractContext(traceparent?: string, baggage?: string): Context;
+/**
+ * Get a baggage entry from the current context.
+ */
+declare function getBaggageEntry(key: string): string | undefined;
+/**
+ * Set a baggage entry in the current context.
+ */
+declare function setBaggageEntry(key: string, value: string): Context;
+/**
+ * Remove a baggage entry from the current context.
+ */
+declare function removeBaggageEntry(key: string): Context;
+/**
+ * Get all baggage entries from the current context.
+ */
+declare function getAllBaggage(): Record<string, string>;
+//#endregion
+//#region src/telemetry-system/baggage-span-processor.d.ts
+/** DEFAULT_ALLOWLIST drift across languages would break worker chains;
+ * lockstep tests in each SDK pin this constant at CI time. */
+declare const DEFAULT_ALLOWLIST: readonly string[];
+declare class BaggageSpanProcessor implements SpanProcessor {
+  private readonly allowlist;
+  constructor(allowlist?: readonly string[]);
+  onStart(span: Span$1, parentContext: Context): void;
+  onEnd(_span: ReadableSpan): void;
+  shutdown(): Promise<void>;
+  forceFlush(): Promise<void>;
+}
+//#endregion
+//#region src/telemetry-system/span-ops.d.ts
+/** Returns `false` when there is no active span or the sampler dropped it. */
+declare function currentSpanIsRecording(): boolean;
+/** No-op when the current span is not recording. */
+declare function setCurrentSpanAttribute(key: string, value: AttributeValue): void;
+/** No-op when there is no active span. */
+declare function setCurrentSpanError(message: string): void;
+/** No-op when the current span is not recording. */
+declare function recordSpanEvent(name: string, attrs?: Attributes): void;
+//#endregion
+//#region src/telemetry-system/payload.d.ts
+/** Payload redaction + truncation for invocation event capture. */
+declare const REDACTED_PLACEHOLDER = "[REDACTED]";
+declare function resolveMaxBytesFromEnv(): number | null;
+/** Recursively redact values of sensitive keys. Returns a new value. */
+declare function redact(value: unknown): unknown;
+/** Redact then serialize to JSON, optionally capped at `maxBytes`. */
+declare function redactAndTruncate(value: unknown, maxBytes?: number | null): {
+  json: string;
+  truncated: boolean;
+};
+//#endregion
+//#region src/telemetry-system/index.d.ts
+/**
+ * Initialize OpenTelemetry with the given configuration.
+ * This should be called once at application startup.
+ */
+declare function initOtel(config?: OtelConfig): void;
+/**
+ * Shutdown OpenTelemetry, flushing any pending data.
+ */
+declare function shutdownOtel(): Promise<void>;
+/**
+ * Force-flush all OTel providers without tearing them down.
+ *
+ * Counterpart to {@link shutdownOtel}. Use before short-lived process exits
+ * where you want pending spans/metrics/logs delivered but plan to keep using
+ * OTel afterwards.
+ */
+declare function flushOtel(): Promise<void>;
+/**
+ * Get the OpenTelemetry tracer instance.
+ */
+declare function getTracer(): Tracer$1 | null;
+/**
+ * Get the OpenTelemetry meter instance.
+ */
+declare function getMeter(): Meter | null;
+/**
+ * Get the OpenTelemetry logger instance.
+ */
+declare function getLogger(): Logger$1 | null;
+/**
+ * Start a new span with the given name and run the callback within it.
+ */
+declare function withSpan<T>(name: string, options: {
+  kind?: SpanKind;
+  traceparent?: string;
+}, fn: (span: Span) => Promise<T>): Promise<T>;
+//#endregion
+//#region src/telemetry-system/fetch-instrumentation.d.ts
+/**
+ * Patch globalThis.fetch to create OTel CLIENT spans for every HTTP request.
+ */
+declare function patchGlobalFetch(tracer: Tracer): void;
+/**
+ * Restore globalThis.fetch to its original implementation.
+ */
+declare function unpatchGlobalFetch(): void;
+//#endregion
+//#region src/otel-worker-gauges.d.ts
+interface WorkerGaugesOptions {
+  workerId: string;
+  workerName?: string;
+}
+declare function registerWorkerGauges(meter: Meter$1, options: WorkerGaugesOptions): void;
+declare function stopWorkerGauges(): void;
+//#endregion
+//#region src/worker-metrics.d.ts
+/**
+ * Worker metrics collection for the III Node SDK.
+ *
+ * Collects CPU, memory, and event loop metrics for worker health monitoring.
+ * Uses the Node.js built-in `monitorEventLoopDelay` API for accurate
+ * event loop lag measurements.
+ */
+/**
+ * Worker metrics data structure used internally for OTEL metric collection.
+ */
+type WorkerMetrics = {
+  memory_heap_used?: number;
+  memory_heap_total?: number;
+  memory_rss?: number;
+  memory_external?: number;
+  cpu_user_micros?: number;
+  cpu_system_micros?: number;
+  cpu_percent?: number;
+  event_loop_lag_ms?: number;
+  uptime_seconds?: number;
+  timestamp_ms: number;
+  runtime: string;
+};
+/**
+ * Configuration options for the WorkerMetricsCollector.
+ */
+interface WorkerMetricsCollectorOptions {
+  /**
+   * Event loop delay histogram resolution in milliseconds.
+   * Lower values provide more accurate measurements but use more resources.
+   * @default 20
+   */
+  eventLoopResolutionMs?: number;
+}
+/**
+ * Collects worker resource metrics including CPU, memory, and event loop lag.
+ *
+ * Uses the Node.js `monitorEventLoopDelay` API for high-precision event loop
+ * delay measurements instead of manual `setImmediate` timing.
+ *
+ * @example
+ * ```typescript
+ * const collector = new WorkerMetricsCollector()
+ *
+ * // Collect metrics periodically
+ * setInterval(() => {
+ *   const metrics = collector.collect()
+ *   console.log('CPU:', metrics.cpu_percent, '%')
+ *   console.log('Event Loop Lag:', metrics.event_loop_lag_ms, 'ms')
+ * }, 5000)
+ *
+ * // Clean up when done
+ * collector.stopMonitoring()
+ * ```
+ */
+declare class WorkerMetricsCollector {
+  private readonly startTime;
+  private lastCpuUsage;
+  private lastCpuTime;
+  private eventLoopHistogram;
+  /**
+   * Creates a new WorkerMetricsCollector instance.
+   *
+   * @param options - Configuration options
+   */
+  constructor(options?: WorkerMetricsCollectorOptions);
+  /**
+   * Starts the event loop delay histogram monitoring.
+   *
+   * @param resolutionMs - Histogram resolution in milliseconds
+   */
+  private startEventLoopMonitoring;
+  /**
+   * Stops the event loop monitoring and releases resources.
+   * Should be called when the collector is no longer needed.
+   */
+  stopMonitoring(): void;
+  /**
+   * Collects current worker metrics.
+   *
+   * This method calculates CPU usage since the last collection,
+   * reads memory usage, and gets event loop delay statistics.
+   * The event loop histogram is reset after each collection for
+   * accurate per-interval measurements.
+   *
+   * @returns Current worker metrics snapshot
+   */
+  collect(): WorkerMetrics;
+}
+//#endregion
+//#region src/types.d.ts
+/** OTEL Log Event from the engine */
+type OtelLogEvent = {
+  /** Timestamp in Unix nanoseconds */timestamp_unix_nano: number; /** Observed timestamp in Unix nanoseconds */
+  observed_timestamp_unix_nano: number; /** OTEL severity number (1-24): TRACE=1-4, DEBUG=5-8, INFO=9-12, WARN=13-16, ERROR=17-20, FATAL=21-24 */
+  severity_number: number; /** Severity text (e.g., "INFO", "WARN", "ERROR") */
+  severity_text: string; /** Log message body */
+  body: string; /** Structured attributes */
+  attributes: Record<string, unknown>; /** Trace ID for correlation (if available) */
+  trace_id?: string; /** Span ID for correlation (if available) */
+  span_id?: string; /** Resource attributes from the emitting service */
+  resource: Record<string, string>; /** Service name that emitted the log */
+  service_name: string; /** Instrumentation scope name (if available) */
+  instrumentation_scope_name?: string; /** Instrumentation scope version (if available) */
+  instrumentation_scope_version?: string;
+};
+//#endregion
+//#region src/utils.d.ts
+/**
+ * Safely stringify a value, handling circular references, BigInt, and other edge cases.
+ * Returns "[unserializable]" if serialization fails for any reason.
+ */
+declare function safeStringify(value: unknown): string;
+//#endregion
+export { BaggageSpanProcessor, DEFAULT_ALLOWLIST, Logger, type Meter, type OtelConfig, type OtelLogEvent, type Logger$1 as OtelLogger, REDACTED_PLACEHOLDER, type ReconnectionConfig, SeverityNumber, type Span, SpanKind, type TracedFetchInit, type WorkerGaugesOptions, type WorkerMetrics, WorkerMetricsCollector, type WorkerMetricsCollectorOptions, currentSpanId, currentSpanIsRecording, currentTraceId, executeTracedRequest, extractBaggage, extractContext, extractTraceparent, flushOtel, getAllBaggage, getBaggageEntry, getLogger, getMeter, getTracer, initOtel, injectBaggage, injectTraceparent, patchGlobalFetch, recordSpanEvent, redact, redactAndTruncate, registerWorkerGauges, removeBaggageEntry, resolveMaxBytesFromEnv, safeStringify, setBaggageEntry, setCurrentSpanAttribute, setCurrentSpanError, shutdownOtel, stopWorkerGauges, unpatchGlobalFetch, withSpan };
+//# sourceMappingURL=index.d.mts.map