@mks2508/better-logger 0.18.2-alpha.2 → 0.18.3

package/dist/index.cjs

@@ -3,12 +3,12 @@ Object.defineProperties(exports, {
 	[Symbol.toStringTag]: { value: "Module" }
 });
 const require_core = require("./chunks/core-CqS_UBzJ.cjs");
-const require_transports = require("./chunks/transports-yK6CL0Ml.cjs");
+const require_transports = require("./chunks/transports-BZ-Mc2IT.cjs");
 const require_utils = require("./chunks/utils-W_cxqriN.cjs");
 const require_styling = require("./chunks/styling-Cel2wPRy.cjs");
 const require_environment_detector = require("./chunks/environment-detector-D-tHkKWA.cjs");
 const require_spinner = require("./chunks/spinner-BHyYEXsM.cjs");
-const require_LogContext = require("./chunks/LogContext-BaMXleWj.cjs");
+const require_LogContext = require("./chunks/LogContext-DZasm_P5.cjs");
 const require_HookBridge = require("./chunks/HookBridge-C-AvXmPD.cjs");
 const require_SerializerBridge = require("./chunks/SerializerBridge-C4a9Z37F.cjs");
 const require_server_fallback = require("./chunks/server-fallback-CaCPjWby.cjs");
@@ -293,6 +293,34 @@ var ScopedLogger = class {
 		this.parent.logWithBindings(this.getBindings(), "trace", ...args);
 	}
 	/**
+	* Emite un point-span con el scope de este logger como
+	* `SpanRecord.scope`. Ver {@link Logger.event}.
+	*
+	* @param {string} name - Nombre del evento.
+	* @param {SpanAttributes} [attributes] - Attributes del span.
+	*
+	* @example
+	* logger.scope('BUILD').event('step.done', { step: 'compile' });
+	*/
+	event(name, attributes) {
+		this.parent._emitSpanEvent(name, attributes, this.getScopePrefix());
+	}
+	span(name, fnOrAttributes, maybeFn) {
+		const { attributes, fn } = resolveSpanArgs(fnOrAttributes, maybeFn);
+		return this.parent._runSpan(name, attributes, this.getScopePrefix(), fn);
+	}
+	/**
+	* Inicia un span externally-ended etiquetado con el scope de este
+	* logger. Ver {@link Logger.startSpan}.
+	*
+	* @param {string} name - Nombre de la operación.
+	* @param {SpanAttributes} [attributes] - Attributes iniciales.
+	* @returns {Span} Handle con `set`/`end`/`fail`.
+	*/
+	startSpan(name, attributes) {
+		return this.parent._startSpan(name, attributes, this.getScopePrefix());
+	}
+	/**
 	* Delegación a {@link Logger.step}: dibuja una barra de progreso discreta
 	* `current/total` para este scope.
 	*
@@ -1537,6 +1565,164 @@ function createTransportBridge() {
 	};
 }
 //#endregion
+//#region src/transports/SpanRuntime.ts
+/** ALS singleton del módulo — compartido por todas las instancias de Logger.
+*
+* Resolución por capas (global → `process.getBuiltinModule` → `require`,
+* undefined en browser) delegada al helper compartido
+* {@link resolveAsyncLocalStorage} — ver su doc para el detalle de capas.
+* `context/LogContext.ts` usa el mismo helper para su ALS de MDC. */
+const activeSpanStore = require_LogContext.resolveAsyncLocalStorage();
+/**
+* Span activo en el call stack corriente (dentro de `span(fn)`), si lo hay.
+* Lo consumen la correlación log→span (`TransportRecord.traceId/spanId`) y la
+* resolución de `parentSpanId` en spans hijos.
+*/
+function getActiveSpan() {
+	return activeSpanStore?.getStore();
+}
+/**
+* Ejecuta `fn` con `record` como span activo. Sin ALS disponible (browser),
+* ejecuta `fn` directamente — sin correlación pero funcional.
+*/
+function runWithActiveSpan(record, fn) {
+	return activeSpanStore ? activeSpanStore.run(record, fn) : fn();
+}
+/** Nanosegundos Unix actuales como string decimal (formato OTLP). */
+function nowUnixNano() {
+	return String(BigInt(Date.now()) * 1000000n);
+}
+/**
+* Hex aleatorio de `bytes` bytes. Usa `crypto.getRandomValues`; sin
+* `crypto` (runtimes exóticos) degrada a `Math.random` — suficiente para ids
+* de correlación, no para secrets.
+*/
+function randomHex(bytes) {
+	const cryptoObj = globalThis.crypto;
+	if (cryptoObj?.getRandomValues) {
+		const buf = new Uint8Array(bytes);
+		cryptoObj.getRandomValues(buf);
+		let out = "";
+		for (const b of buf) out += b.toString(16).padStart(2, "0");
+		return out;
+	}
+	let out = "";
+	for (let i = 0; i < bytes * 2; i++) out += Math.floor(Math.random() * 16).toString(16);
+	return out;
+}
+/** Trace id W3C: 16 bytes → 32 chars hex. */
+function generateTraceId() {
+	return randomHex(16);
+}
+/** Span id W3C: 8 bytes → 16 chars hex. */
+function generateSpanId() {
+	return randomHex(8);
+}
+/**
+* Registry de spans abiertos (leak-safety). Cubre tanto los de `startSpan()`
+* (externally-ended, el caso del handoff) como los de `span(fn)` en curso:
+* si un flush llega mid-flight, es mejor exportar el span incompleto que
+* tirarlo. El doble-`end()` es no-op, así que el cierre natural posterior no
+* duplica el export.
+*/
+const openSpans = /* @__PURE__ */ new Map();
+/**
+* Crea el record de span y su {@link Span} handle. El handle registra el
+* span en el registry de abiertos; `onEnd` se invoca una única vez, con el
+* record final (duración real o `incomplete: true`), para su export al
+* pipeline de transports.
+*
+* `end()` solo fija `endTimeUnixNano` si no se fijó antes — así los
+* point-spans (`event()`) pueden fijar `end = start` exacto.
+*
+* @param name - Nombre de la operación.
+* @param attributes - Attributes iniciales (copia propia del record).
+* @param scope - Scope del logger emisor.
+* @param onEnd - Callback de export; recibe el record cerrado.
+* @returns El record (para el ALS store) y el handle del span.
+*/
+function createSpan(name, attributes, scope, onEnd) {
+	const parent = getActiveSpan();
+	const record = {
+		kind: "span",
+		traceId: parent?.traceId ?? generateTraceId(),
+		spanId: generateSpanId(),
+		parentSpanId: parent?.spanId,
+		name,
+		spanKind: 1,
+		startTimeUnixNano: nowUnixNano(),
+		endTimeUnixNano: "0",
+		attributes: { ...attributes ?? {} },
+		scope
+	};
+	let ended = false;
+	const finish = () => {
+		if (ended) return;
+		ended = true;
+		openSpans.delete(record);
+		onEnd(record);
+	};
+	openSpans.set(record, {
+		record,
+		end: finish,
+		forceEnd: () => {
+			if (ended) return;
+			record.incomplete = true;
+			if (record.endTimeUnixNano === "0") record.endTimeUnixNano = nowUnixNano();
+			finish();
+		}
+	});
+	const handle = {
+		traceId: record.traceId,
+		spanId: record.spanId,
+		set(key, value) {
+			record.attributes[key] = value;
+			return handle;
+		},
+		end(attributes) {
+			if (attributes) Object.assign(record.attributes, attributes);
+			if (ended) return;
+			if (record.endTimeUnixNano === "0") record.endTimeUnixNano = nowUnixNano();
+			finish();
+		},
+		fail(err) {
+			if (ended) return;
+			record.status = {
+				code: 2,
+				message: err instanceof Error ? err.message : String(err)
+			};
+			this.end();
+		}
+	};
+	return {
+		record,
+		span: handle
+	};
+}
+/**
+* Emite un point-span (`event()`): start = end exactamente, sin registro en
+* abiertos tras el cierre — no hay leak posible. El `parentSpanId` se resuelve
+* contra el span activo si existe, pero NO fija contexto ALS.
+*/
+function emitEventSpan(name, attributes, scope, onEnd) {
+	const { record, span } = createSpan(name, attributes, scope, onEnd);
+	record.endTimeUnixNano = record.startTimeUnixNano;
+	span.end();
+}
+/**
+* Fuerza el cierre de todos los spans abiertos (`incomplete: true`) y los
+* exporta vía el `onEnd` de cada uno. Lo invocan `flushTransports()` /
+* `closeTransports()` / `cleanup()` ANTES del flush real — un span abierto
+* nunca se tira en shutdown.
+*
+* @returns Los records forzados a cerrar (para diagnóstico/tests).
+*/
+function forceCloseOpenSpans() {
+	const snapshot = [...openSpans.values()];
+	for (const entry of snapshot) entry.forceEnd();
+	return snapshot.map((entry) => entry.record);
+}
+//#endregion
 //#region src/playground/TerminalBridge.ts
 /**
 * Crea un {@link TerminalBridge} usando un getter para evitar referencias
@@ -2012,6 +2198,7 @@ var Logger = class Logger {
 			} catch {}
 			this.themeChangeListener = null;
 		}
+		forceCloseOpenSpans();
 		await this.transportBridge.closeTransports();
 		this.handlers.length = 0;
 		this.timers.clear();
@@ -2434,21 +2621,27 @@ var Logger = class Logger {
 		return this.transportBridge.removeTransport(id);
 	}
 	/**
-	* Fuerza el flush de todos los transports
+	* Fuerza el flush de todos los transports. Antes de flushear, cierra los
+	* spans aún abiertos (`incomplete: true`) y los encola para export — un
+	* span abierto nunca se tira en un flush.
 	*
 	* @returns Promise que resuelve cuando todos los buffers están vaciados
 	*
 	*/
 	async flushTransports() {
+		forceCloseOpenSpans();
 		await this.transportBridge.flushTransports();
 	}
 	/**
-	* Cierra todos los transports
+	* Cierra todos los transports. Como en {@link flushTransports}, primero
+	* fuerza el cierre de los spans abiertos para que viajen en el flush
+	* final del close.
 	*
 	* @returns Promise que resuelve cuando todos están cerrados
 	*
 	*/
 	async closeTransports() {
+		forceCloseOpenSpans();
 		await this.transportBridge.closeTransports();
 	}
 	/**
@@ -2550,6 +2743,11 @@ var Logger = class Logger {
 			resource: this.logContext._getResource() ? { ...this.logContext._getResource() } : void 0,
 			...extra
 		};
+		const activeSpan = getActiveSpan();
+		if (activeSpan && !record.traceId) {
+			record.traceId = activeSpan.traceId;
+			record.spanId = activeSpan.spanId;
+		}
 		this.transportBridge.writeRecord(record);
 	}
 	/**
@@ -2806,6 +3004,104 @@ var Logger = class Logger {
 		return this.log("critical", ...args);
 	}
 	/**
+	* Emite un **point-span**: un span con `start = end` para completion
+	* signals y eventos puntuales (una operación instantánea, un hito).
+	* No registra contexto activo ni puede leakear — se exporta de inmediato.
+	*
+	* El nombre `event` (y no `trace`) es deliberado: `trace` es un log level
+	* (el -1) y está reservado.
+	*
+	* @param {string} name - Nombre del evento (`job.completed`, `cache.flushed`, ...).
+	* @param {SpanAttributes} [attributes] - Attributes del span.
+	*
+	* @example
+	* logger.event('build.finished', { status: 'ok', durationMs: 4200 });
+	*
+	* @see {@link span} para intervalos con work-block
+	* @see {@link startSpan} para intervalos externally-ended
+	*/
+	event(name, attributes) {
+		emitEventSpan(name, attributes, this._spanScopeName(), (record) => {
+			this.transportBridge.writeRecord(record);
+		});
+	}
+	span(name, fnOrAttributes, maybeFn) {
+		const { attributes, fn } = resolveSpanArgs(fnOrAttributes, maybeFn);
+		return this._runSpan(name, attributes, this._spanScopeName(), fn);
+	}
+	/**
+	* Inicia un span de intervalo **externally-ended**: devuelve el handle y
+	* NO fija contexto ALS (el cierre ocurre fuera del bloque léxico — p.ej.
+	* un `cli.spawn` que se cierra desde un poll o callback externo).
+	*
+	* Si el span no se cierra antes de `flushTransports()` / shutdown, el
+	* flush lo fuerza a cerrar con `incomplete: true` y lo exporta — nunca
+	* se tira.
+	*
+	* @param {string} name - Nombre de la operación.
+	* @param {SpanAttributes} [attributes] - Attributes iniciales.
+	* @returns {Span} Handle con `set`/`end`/`fail` y los ids del span.
+	*
+	* @example
+	* const s = logger.startSpan('spawn.build', { cmd: 'make' });
+	* proc.on('exit', code => {
+	*   if (code === 0) s.end({ exitCode: code });
+	*   else s.fail(new Error(`exit ${code}`));
+	* });
+	*
+	* @see {@link span} para el caso con work-block
+	*/
+	startSpan(name, attributes) {
+		return this._startSpan(name, attributes, this._spanScopeName());
+	}
+	/**
+	* Scope por defecto de los spans emitidos por este logger (el
+	* `globalPrefix`, o `'root'`).
+	* @internal
+	*/
+	_spanScopeName() {
+		return this.config.globalPrefix || "root";
+	}
+	/**
+	* Emite un point-span con scope explícito. Lo consume
+	* {@link ScopedLogger.event}, que pasa su scope compuesto.
+	* @internal
+	*/
+	_emitSpanEvent(name, attributes, scope) {
+		emitEventSpan(name, attributes, scope, (record) => {
+			this.transportBridge.writeRecord(record);
+		});
+	}
+	/**
+	* Crea un span externally-ended con scope explícito. Lo consume
+	* {@link ScopedLogger.startSpan}.
+	* @internal
+	*/
+	_startSpan(name, attributes, scope) {
+		const { span } = createSpan(name, attributes, scope, (record) => {
+			this.transportBridge.writeRecord(record);
+		});
+		return span;
+	}
+	/**
+	* Corre `fn` dentro de un span activo en el ALS con scope explícito.
+	* Lo consume {@link ScopedLogger.span}.
+	* @internal
+	*/
+	async _runSpan(name, attributes, scope, fn) {
+		const { record, span } = createSpan(name, attributes, scope, (r) => {
+			this.transportBridge.writeRecord(r);
+		});
+		try {
+			const result = await runWithActiveSpan(record, () => fn(span));
+			span.end();
+			return result;
+		} catch (error) {
+			span.fail(error);
+			throw error;
+		}
+	}
+	/**
 	* Muestra datos en formato de tabla. Pasa por la pipeline completa
 	* (outputMode-respecting writeOutput + transports + hooks).
 	*
@@ -3270,6 +3566,23 @@ function toAttributeValue(value) {
 		return;
 	}
 }
+/**
+* Resuelve los argumentos del overload `span(name, fn?)` /
+* `span(name, attributes, fn)` a `{ attributes, fn }`.
+*
+* @internal Compartido con `ScopedLogger.span`; no es API pública.
+*/
+function resolveSpanArgs(fnOrAttributes, maybeFn) {
+	if (typeof fnOrAttributes === "function") return {
+		attributes: void 0,
+		fn: fnOrAttributes
+	};
+	if (typeof maybeFn === "function") return {
+		attributes: fnOrAttributes,
+		fn: maybeFn
+	};
+	throw new TypeError("span(name, …): se requiere una función fn");
+}
 //#endregion
 //#region src/index.ts
 /**
@@ -3302,6 +3615,11 @@ const group = (label, collapsed) => getLogger().group(label, collapsed);
 const groupEnd = () => getLogger().groupEnd();
 const time = (label) => getLogger().time(label);
 const timeEnd = (label) => getLogger().timeEnd(label);
+const event = (name, attributes) => getLogger().event(name, attributes);
+const startSpan = (name, attributes) => getLogger().startSpan(name, attributes);
+function span(name, fnOrAttributes, maybeFn) {
+	return getLogger().span(name, fnOrAttributes, maybeFn);
+}
 const setGlobalPrefix = (prefix) => getLogger().setGlobalPrefix(prefix);
 const scope = (name) => getLogger().scope(name);
 const component = (name) => getLogger().component(name);
@@ -3360,6 +3678,7 @@ exports.critical = critical;
 exports.debug = debug;
 exports.default = src_default;
 exports.error = error;
+exports.event = event;
 exports.flushTransports = flushTransports;
 exports.formatLogLevelANSI = require_utils.formatLogLevelANSI;
 exports.formatSuccessANSI = require_utils.formatSuccessANSI;
@@ -3390,6 +3709,8 @@ exports.setGlobalPrefix = setGlobalPrefix;
 exports.setTheme = setTheme;
 exports.setVerbosity = setVerbosity;
 exports.showBanner = showBanner;
+exports.span = span;
+exports.startSpan = startSpan;
 exports.success = success;
 exports.supportsANSI = require_environment_detector.supportsANSI;
 exports.table = table;