@iii-dev/observability 0.19.7 → 0.20.0-alpha.1

package/README.md

@@ -1,5 +1,7 @@
 # @iii-dev/observability
 
-OpenTelemetry + Logger primitives shared across the iii SDKs.
+> **Deprecated.** This package is a thin shim. Import from `@iii-dev/helpers/observability` (public API) or `@iii-dev/helpers/observability/internal` (internal API) instead.
+
+Re-exports the public API from `@iii-dev/helpers/observability`. This package is a deprecated shim; use `@iii-dev/helpers/observability` for new code.
 
 See https://github.com/iii-hq/iii for the full project.

package/dist/index.cjs

@@ -1,490 +1,9 @@
-Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
-const require_telemetry_system = require('./telemetry-system-BFMV9aXn.cjs');
-let _opentelemetry_api_logs = require("@opentelemetry/api-logs");
-let _opentelemetry_api = require("@opentelemetry/api");
-let node_perf_hooks = require("node:perf_hooks");
 
-//#region src/logger.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' })
-* ```
-*/
-var Logger = class {
-	_otelLogger = null;
-	get otelLogger() {
-		if (!this._otelLogger) this._otelLogger = require_telemetry_system.getLogger();
-		return this._otelLogger;
-	}
-	constructor(traceId, serviceName, spanId) {
-		this.traceId = traceId;
-		this.serviceName = serviceName;
-		this.spanId = spanId;
-	}
-	emit(message, severity, data) {
-		const attributes = {};
-		const traceId = this.traceId ?? require_telemetry_system.currentTraceId();
-		const spanId = this.spanId ?? require_telemetry_system.currentSpanId();
-		if (traceId) attributes.trace_id = traceId;
-		if (spanId) attributes.span_id = spanId;
-		if (this.serviceName) attributes["service.name"] = this.serviceName;
-		if (data !== void 0) attributes["log.data"] = data;
-		if (this.otelLogger) this.otelLogger.emit({
-			severityNumber: severity,
-			body: message,
-			attributes: Object.keys(attributes).length > 0 ? attributes : void 0
-		});
-		else switch (severity) {
-			case _opentelemetry_api_logs.SeverityNumber.DEBUG:
-				console.debug(message, data);
-				break;
-			case _opentelemetry_api_logs.SeverityNumber.INFO:
-				console.info(message, data);
-				break;
-			case _opentelemetry_api_logs.SeverityNumber.WARN:
-				console.warn(message, data);
-				break;
-			case _opentelemetry_api_logs.SeverityNumber.ERROR:
-				console.error(message, data);
-				break;
-			default: console.log(message, data);
-		}
-	}
-	/**
-	* 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, data) {
-		this.emit(message, _opentelemetry_api_logs.SeverityNumber.INFO, data);
-	}
-	/**
-	* 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, data) {
-		this.emit(message, _opentelemetry_api_logs.SeverityNumber.WARN, data);
-	}
-	/**
-	* 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, data) {
-		this.emit(message, _opentelemetry_api_logs.SeverityNumber.ERROR, data);
-	}
-	/**
-	* 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, data) {
-		this.emit(message, _opentelemetry_api_logs.SeverityNumber.DEBUG, data);
-	}
-};
 
-//#endregion
-//#region src/http-instrumentation.ts
-const SAFE_REQUEST_HEADERS = ["content-type", "accept"];
-const SAFE_RESPONSE_HEADERS = ["content-type"];
-/**
-* 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.
-*/
-async function executeTracedRequest(input, init) {
-	const tracer = init?.tracer ?? _opentelemetry_api.trace.getTracer("iii-node-sdk");
-	const rawUrl = typeof input === "string" ? input : input instanceof URL ? input.toString() : input.url;
-	let url;
-	try {
-		url = new URL(rawUrl);
-	} catch {
-		url = null;
-	}
-	const method = (init?.method ?? (typeof input === "object" && "method" in input ? input.method : "GET") ?? "GET").toUpperCase();
-	const name = url?.pathname ? `${method} ${url.pathname}` : method;
-	return tracer.startActiveSpan(name, {
-		kind: _opentelemetry_api.SpanKind.CLIENT,
-		attributes: {
-			"http.request.method": method,
-			"url.full": url?.toString() ?? rawUrl,
-			"network.protocol.name": "http",
-			...url ? {
-				"server.address": url.hostname,
-				"url.scheme": url.protocol.replace(":", ""),
-				"url.path": url.pathname
-			} : {},
-			...url?.port ? { "server.port": Number(url.port) } : {},
-			...url?.search ? { "url.query": url.search.slice(1) } : {}
-		}
-	}, async (span) => {
-		try {
-			const baseHeaders = typeof input === "object" && "headers" in input ? input.headers : void 0;
-			const headers = new Headers(baseHeaders);
-			if (init?.headers) for (const [k, v] of new Headers(init.headers).entries()) headers.set(k, v);
-			const carrier = {};
-			_opentelemetry_api.propagation.inject(_opentelemetry_api.context.active(), carrier);
-			for (const [k, v] of Object.entries(carrier)) headers.set(k, v);
-			for (const h of SAFE_REQUEST_HEADERS) {
-				const v = headers.get(h);
-				if (v) span.setAttribute(`http.request.header.${h}`, v);
-			}
-			const response = await fetch(input, {
-				...init,
-				headers
-			});
-			span.setAttribute("http.response.status_code", response.status);
-			const cl = response.headers.get("content-length");
-			if (cl) span.setAttribute("http.response.body.size", Number(cl));
-			for (const h of SAFE_RESPONSE_HEADERS) {
-				const v = response.headers.get(h);
-				if (v) span.setAttribute(`http.response.header.${h}`, v);
-			}
-			if (response.status >= 400) {
-				span.setStatus({
-					code: _opentelemetry_api.SpanStatusCode.ERROR,
-					message: String(response.status)
-				});
-				span.setAttribute("error.type", String(response.status));
-			} else span.setStatus({ code: _opentelemetry_api.SpanStatusCode.OK });
-			return response;
-		} catch (err) {
-			const error = err;
-			span.recordException(error);
-			span.setStatus({
-				code: _opentelemetry_api.SpanStatusCode.ERROR,
-				message: error.message
-			});
-			span.setAttribute("error.type", error.name);
-			throw err;
-		} finally {
-			span.end();
-		}
-	});
-}
-
-//#endregion
-//#region src/worker-metrics.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.
-*/
-/**
-* 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()
-* ```
-*/
-var WorkerMetricsCollector = class {
-	startTime;
-	lastCpuUsage;
-	lastCpuTime;
-	eventLoopHistogram = null;
-	/**
-	* Creates a new WorkerMetricsCollector instance.
-	*
-	* @param options - Configuration options
-	*/
-	constructor(options = {}) {
-		this.startTime = Date.now();
-		this.lastCpuUsage = process.cpuUsage();
-		this.lastCpuTime = node_perf_hooks.performance.now();
-		this.startEventLoopMonitoring(options.eventLoopResolutionMs ?? 20);
-	}
-	/**
-	* Starts the event loop delay histogram monitoring.
-	*
-	* @param resolutionMs - Histogram resolution in milliseconds
-	*/
-	startEventLoopMonitoring(resolutionMs) {
-		this.eventLoopHistogram = (0, node_perf_hooks.monitorEventLoopDelay)({ resolution: Number.isFinite(resolutionMs) && resolutionMs > 0 ? Math.max(1, Math.floor(resolutionMs)) : 20 });
-		this.eventLoopHistogram.enable();
-	}
-	/**
-	* Stops the event loop monitoring and releases resources.
-	* Should be called when the collector is no longer needed.
-	*/
-	stopMonitoring() {
-		if (this.eventLoopHistogram) {
-			this.eventLoopHistogram.disable();
-			this.eventLoopHistogram = null;
-		}
-	}
-	/**
-	* 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() {
-		const memoryUsage = process.memoryUsage();
-		const cpuUsage = process.cpuUsage();
-		const now = node_perf_hooks.performance.now();
-		const cpuDelta = {
-			user: cpuUsage.user - this.lastCpuUsage.user,
-			system: cpuUsage.system - this.lastCpuUsage.system
-		};
-		const timeDelta = (now - this.lastCpuTime) * 1e3;
-		const cpuPercent = timeDelta > 0 ? (cpuDelta.user + cpuDelta.system) / timeDelta * 100 : 0;
-		this.lastCpuUsage = cpuUsage;
-		this.lastCpuTime = now;
-		let eventLoopLagMs = 0;
-		if (this.eventLoopHistogram) {
-			eventLoopLagMs = this.eventLoopHistogram.mean / 1e6;
-			this.eventLoopHistogram.reset();
-		}
-		return {
-			memory_heap_used: memoryUsage.heapUsed,
-			memory_heap_total: memoryUsage.heapTotal,
-			memory_rss: memoryUsage.rss,
-			memory_external: memoryUsage.external,
-			cpu_user_micros: cpuUsage.user,
-			cpu_system_micros: cpuUsage.system,
-			cpu_percent: Math.min(cpuPercent, 100),
-			event_loop_lag_ms: eventLoopLagMs,
-			uptime_seconds: Math.floor((Date.now() - this.startTime) / 1e3),
-			timestamp_ms: Date.now(),
-			runtime: "node"
-		};
-	}
-};
-
-//#endregion
-//#region src/otel-worker-gauges.ts
-let registeredGauges = false;
-let metricsCollector = null;
-let registeredMeter = null;
-let registeredBatchCallback = null;
-let registeredObservables = [];
-function registerWorkerGauges(meter, options) {
-	if (registeredGauges) return;
-	const { workerId, workerName } = options;
-	const baseAttributes = {
-		"worker.id": workerId,
-		...workerName && { "worker.name": workerName }
-	};
-	metricsCollector = new WorkerMetricsCollector();
-	const memoryHeapUsed = meter.createObservableGauge("iii.worker.memory.heap_used", {
-		description: "Worker heap memory used in bytes",
-		unit: "bytes"
-	});
-	const memoryHeapTotal = meter.createObservableGauge("iii.worker.memory.heap_total", {
-		description: "Worker total heap memory in bytes",
-		unit: "bytes"
-	});
-	const memoryRss = meter.createObservableGauge("iii.worker.memory.rss", {
-		description: "Worker resident set size in bytes",
-		unit: "bytes"
-	});
-	const memoryExternal = meter.createObservableGauge("iii.worker.memory.external", {
-		description: "Worker external memory in bytes",
-		unit: "bytes"
-	});
-	const cpuPercent = meter.createObservableGauge("iii.worker.cpu.percent", {
-		description: "Worker CPU usage percentage",
-		unit: "%"
-	});
-	const cpuUserMicros = meter.createObservableGauge("iii.worker.cpu.user_micros", {
-		description: "Worker CPU user time in microseconds",
-		unit: "us"
-	});
-	const cpuSystemMicros = meter.createObservableGauge("iii.worker.cpu.system_micros", {
-		description: "Worker CPU system time in microseconds",
-		unit: "us"
-	});
-	const eventLoopLag = meter.createObservableGauge("iii.worker.event_loop.lag_ms", {
-		description: "Worker event loop lag in milliseconds",
-		unit: "ms"
-	});
-	const uptimeSeconds = meter.createObservableGauge("iii.worker.uptime_seconds", {
-		description: "Worker uptime in seconds",
-		unit: "s"
-	});
-	const batchCallback = (observableResult) => {
-		if (!metricsCollector) return;
-		const metrics = metricsCollector.collect();
-		if (metrics.memory_heap_used !== void 0) observableResult.observe(memoryHeapUsed, metrics.memory_heap_used, baseAttributes);
-		if (metrics.memory_heap_total !== void 0) observableResult.observe(memoryHeapTotal, metrics.memory_heap_total, baseAttributes);
-		if (metrics.memory_rss !== void 0) observableResult.observe(memoryRss, metrics.memory_rss, baseAttributes);
-		if (metrics.memory_external !== void 0) observableResult.observe(memoryExternal, metrics.memory_external, baseAttributes);
-		if (metrics.cpu_percent !== void 0) observableResult.observe(cpuPercent, metrics.cpu_percent, baseAttributes);
-		if (metrics.cpu_user_micros !== void 0) observableResult.observe(cpuUserMicros, metrics.cpu_user_micros, baseAttributes);
-		if (metrics.cpu_system_micros !== void 0) observableResult.observe(cpuSystemMicros, metrics.cpu_system_micros, baseAttributes);
-		if (metrics.event_loop_lag_ms !== void 0) observableResult.observe(eventLoopLag, metrics.event_loop_lag_ms, baseAttributes);
-		if (metrics.uptime_seconds !== void 0) observableResult.observe(uptimeSeconds, metrics.uptime_seconds, baseAttributes);
-	};
-	meter.addBatchObservableCallback(batchCallback, [
-		memoryHeapUsed,
-		memoryHeapTotal,
-		memoryRss,
-		memoryExternal,
-		cpuPercent,
-		cpuUserMicros,
-		cpuSystemMicros,
-		eventLoopLag,
-		uptimeSeconds
-	]);
-	registeredMeter = meter;
-	registeredBatchCallback = batchCallback;
-	registeredObservables = [
-		memoryHeapUsed,
-		memoryHeapTotal,
-		memoryRss,
-		memoryExternal,
-		cpuPercent,
-		cpuUserMicros,
-		cpuSystemMicros,
-		eventLoopLag,
-		uptimeSeconds
-	];
-	registeredGauges = true;
-}
-function stopWorkerGauges() {
-	if (registeredMeter && registeredBatchCallback) registeredMeter.removeBatchObservableCallback(registeredBatchCallback, registeredObservables);
-	if (metricsCollector) {
-		metricsCollector.stopMonitoring();
-		metricsCollector = null;
-	}
-	registeredMeter = null;
-	registeredBatchCallback = null;
-	registeredObservables = [];
-	registeredGauges = false;
-}
-
-//#endregion
-//#region src/utils.ts
-/**
-* Safely stringify a value, handling circular references, BigInt, and other edge cases.
-* Returns "[unserializable]" if serialization fails for any reason.
-*/
-function safeStringify(value) {
-	const seen = /* @__PURE__ */ new WeakSet();
-	try {
-		return JSON.stringify(value, (_key, val) => {
-			if (typeof val === "bigint") return val.toString();
-			if (val !== null && typeof val === "object") {
-				if (seen.has(val)) return "[Circular]";
-				seen.add(val);
-			}
-			return val;
-		}) ?? "[unserializable]";
-	} catch {
-		return "[unserializable]";
-	}
-}
-
-//#endregion
-exports.BaggageSpanProcessor = require_telemetry_system.BaggageSpanProcessor;
-exports.DEFAULT_ALLOWLIST = require_telemetry_system.DEFAULT_ALLOWLIST;
-exports.Logger = Logger;
-exports.REDACTED_PLACEHOLDER = require_telemetry_system.REDACTED_PLACEHOLDER;
-exports.SeverityNumber = _opentelemetry_api_logs.SeverityNumber;
-exports.WorkerMetricsCollector = WorkerMetricsCollector;
-exports.currentSpanId = require_telemetry_system.currentSpanId;
-exports.currentSpanIsRecording = require_telemetry_system.currentSpanIsRecording;
-exports.currentTraceId = require_telemetry_system.currentTraceId;
-exports.executeTracedRequest = executeTracedRequest;
-exports.extractBaggage = require_telemetry_system.extractBaggage;
-exports.extractContext = require_telemetry_system.extractContext;
-exports.extractTraceparent = require_telemetry_system.extractTraceparent;
-exports.flushOtel = require_telemetry_system.flushOtel;
-exports.getAllBaggage = require_telemetry_system.getAllBaggage;
-exports.getBaggageEntry = require_telemetry_system.getBaggageEntry;
-exports.getLogger = require_telemetry_system.getLogger;
-exports.initOtel = require_telemetry_system.initOtel;
-exports.injectBaggage = require_telemetry_system.injectBaggage;
-exports.injectTraceparent = require_telemetry_system.injectTraceparent;
-exports.patchGlobalFetch = require_telemetry_system.patchGlobalFetch;
-exports.recordSpanEvent = require_telemetry_system.recordSpanEvent;
-exports.redact = require_telemetry_system.redact;
-exports.redactAndTruncate = require_telemetry_system.redactAndTruncate;
-exports.registerWorkerGauges = registerWorkerGauges;
-exports.removeBaggageEntry = require_telemetry_system.removeBaggageEntry;
-exports.resolveMaxBytesFromEnv = require_telemetry_system.resolveMaxBytesFromEnv;
-exports.safeStringify = safeStringify;
-exports.setBaggageEntry = require_telemetry_system.setBaggageEntry;
-exports.setCurrentSpanAttribute = require_telemetry_system.setCurrentSpanAttribute;
-exports.setCurrentSpanError = require_telemetry_system.setCurrentSpanError;
-exports.shutdownOtel = require_telemetry_system.shutdownOtel;
-exports.stopWorkerGauges = stopWorkerGauges;
-exports.unpatchGlobalFetch = require_telemetry_system.unpatchGlobalFetch;
-exports.withSpan = require_telemetry_system.withSpan;
-//# sourceMappingURL=index.cjs.map
+var _iii_dev_helpers_observability = require("@iii-dev/helpers/observability");
+Object.keys(_iii_dev_helpers_observability).forEach(function (k) {
+  if (k !== 'default' && !Object.prototype.hasOwnProperty.call(exports, k)) Object.defineProperty(exports, k, {
+    enumerable: true,
+    get: function () { return _iii_dev_helpers_observability[k]; }
+  });
+});