@iii-dev/observability 0.19.4-alpha.2 → 0.19.4-alpha.3

package/dist/index.d.cts

@@ -1,244 +1 @@
-import { A as injectTraceparent, C as currentTraceId, D as getAllBaggage, E as extractTraceparent, M as setBaggageEntry, N as OtelConfig, O as getBaggageEntry, P as ReconnectionConfig, S as currentSpanId, T as extractContext, _ as recordSpanEvent, a as flushOtel, b as BaggageSpanProcessor, d as withSpan, f as REDACTED_PLACEHOLDER, g as currentSpanIsRecording, h as resolveMaxBytesFromEnv, i as Span, j as removeBaggageEntry, k as injectBaggage, l as initOtel, m as redactAndTruncate, n as Meter, o as getLogger, p as redact, r as SeverityNumber, t as Logger$1, u as shutdownOtel, v as setCurrentSpanAttribute, w as extractBaggage, x as DEFAULT_ALLOWLIST, y as setCurrentSpanError } from "./index-Cb4IHzbB.cjs";
-import { Meter as Meter$1, Tracer } from "@opentelemetry/api";
-
-//#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/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, type TracedFetchInit, type WorkerGaugesOptions, type WorkerMetrics, WorkerMetricsCollector, type WorkerMetricsCollectorOptions, currentSpanId, currentSpanIsRecording, currentTraceId, executeTracedRequest, extractBaggage, extractContext, extractTraceparent, flushOtel, getAllBaggage, getBaggageEntry, getLogger, initOtel, injectBaggage, injectTraceparent, patchGlobalFetch, recordSpanEvent, redact, redactAndTruncate, registerWorkerGauges, removeBaggageEntry, resolveMaxBytesFromEnv, safeStringify, setBaggageEntry, setCurrentSpanAttribute, setCurrentSpanError, shutdownOtel, stopWorkerGauges, unpatchGlobalFetch, withSpan };
-//# sourceMappingURL=index.d.cts.map
+export * from "@iii-dev/helpers/observability";

package/dist/index.d.mts

@@ -1,244 +1 @@
-import { A as injectTraceparent, C as currentTraceId, D as getAllBaggage, E as extractTraceparent, M as setBaggageEntry, N as OtelConfig, O as getBaggageEntry, P as ReconnectionConfig, S as currentSpanId, T as extractContext, _ as recordSpanEvent, a as flushOtel, b as BaggageSpanProcessor, d as withSpan, f as REDACTED_PLACEHOLDER, g as currentSpanIsRecording, h as resolveMaxBytesFromEnv, i as Span, j as removeBaggageEntry, k as injectBaggage, l as initOtel, m as redactAndTruncate, n as Meter, o as getLogger, p as redact, r as SeverityNumber, t as Logger$1, u as shutdownOtel, v as setCurrentSpanAttribute, w as extractBaggage, x as DEFAULT_ALLOWLIST, y as setCurrentSpanError } from "./index-opxepmJp.mjs";
-import { Meter as Meter$1, Tracer } from "@opentelemetry/api";
-
-//#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/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, type TracedFetchInit, type WorkerGaugesOptions, type WorkerMetrics, WorkerMetricsCollector, type WorkerMetricsCollectorOptions, currentSpanId, currentSpanIsRecording, currentTraceId, executeTracedRequest, extractBaggage, extractContext, extractTraceparent, flushOtel, getAllBaggage, getBaggageEntry, getLogger, initOtel, injectBaggage, injectTraceparent, patchGlobalFetch, recordSpanEvent, redact, redactAndTruncate, registerWorkerGauges, removeBaggageEntry, resolveMaxBytesFromEnv, safeStringify, setBaggageEntry, setCurrentSpanAttribute, setCurrentSpanError, shutdownOtel, stopWorkerGauges, unpatchGlobalFetch, withSpan };
-//# sourceMappingURL=index.d.mts.map
+export * from "@iii-dev/helpers/observability";