logixia 1.10.2 → 1.11.0

package/dist/index.mjs

@@ -1,6 +1,7 @@
-import { p as internalWarn, u as safeToString } from "./transport.manager-CaL4XuLD.mjs";
-import { A as redactObject, B as LogLevel, C as setTraceId, D as registerForShutdown, E as flushOnExit, F as isError, G as createExpressContextMiddleware, H as globalPluginRegistry, I as normalizeError, K as createFastifyContextHook, L as serializeError, M as getActiveOtelContext, N as getOtelMetaFields, O as resetShutdownHandlers, P as initOtelBridge, R as DEFAULT_LOG_COLORS, S as runWithTraceId, T as deregisterFromShutdown, U as usePlugin, V as PluginRegistry, W as LogixiaContext, _ as _setActiveContextKey, b as getCurrentTraceId, c as KafkaTraceInterceptor, d as __decorateMetadata, f as LogixiaLogger, g as TraceContext, h as TRACE_CONTEXT_KEY, i as WebSocketTraceInterceptor, j as disableOtelBridge, k as applyRedaction, l as LogixiaLoggerService, m as DEFAULT_TRACE_HEADERS, n as LOGIXIA_LOGGER_PREFIX, o as resolveResponseHeader, p as createLogger$1, r as LogixiaLoggerModule, s as __decorateParam, t as LOGIXIA_LOGGER_CONFIG, u as __decorate, v as createTraceMiddleware, w as traceStorage, x as getTraceContextKey, y as extractTraceId, z as DEFAULT_LOG_LEVELS } from "./logitron-logger.module-Bt_Jei1V.mjs";
+import { d as internalError, f as internalLog, p as internalWarn, u as safeToString } from "./transport.manager-Cij_sA-b.mjs";
+import { A as redactObject, B as LogLevel, C as setTraceId, D as registerForShutdown, E as flushOnExit, F as isError, G as createExpressContextMiddleware, H as globalPluginRegistry, I as normalizeError, K as createFastifyContextHook, L as serializeError, M as getActiveOtelContext, N as getOtelMetaFields, O as resetShutdownHandlers, P as initOtelBridge, R as DEFAULT_LOG_COLORS, S as runWithTraceId, T as deregisterFromShutdown, U as usePlugin, V as PluginRegistry, W as LogixiaContext, _ as _setActiveContextKey, b as getCurrentTraceId, c as KafkaTraceInterceptor, d as __decorateMetadata, f as LogixiaLogger, g as TraceContext, h as TRACE_CONTEXT_KEY, i as WebSocketTraceInterceptor, j as disableOtelBridge, k as applyRedaction, l as LogixiaLoggerService, m as DEFAULT_TRACE_HEADERS, n as LOGIXIA_LOGGER_PREFIX, o as resolveResponseHeader, p as createLogger$1, r as LogixiaLoggerModule, s as __decorateParam, t as LOGIXIA_LOGGER_CONFIG, u as __decorate, v as createTraceMiddleware, w as traceStorage, x as getTraceContextKey, y as extractTraceId, z as DEFAULT_LOG_LEVELS } from "./logitron-logger.module-QYBy_Kkq.mjs";
 import "./search-DOvSI-mb.mjs";
+import { AsyncLocalStorage } from "node:async_hooks";
 import { Catch, Inject, Optional } from "@nestjs/common";
 
 //#region src/exceptions/exception.ts
@@ -227,8 +228,11 @@ const InjectLogger = () => Inject(`${LOGIXIA_LOGGER_PREFIX}SERVICE`);
 /**
 * Method decorator that auto-logs entry, exit, duration, and errors.
 *
-* Works on both async and sync methods. Attaches to the logger found on the
-* class instance via a `logger` property (the conventional NestJS name).
+* Preserves the original method's sync/async contract: a synchronous method
+* stays synchronous (returns its value directly, with logs emitted
+* fire-and-forget), and an async method is awaited so exit/error logs reflect
+* the resolved result. Attaches to the logger found on the class instance via a
+* `logger` property (the conventional NestJS name).
 *
 * @example
 * ```ts
@@ -246,7 +250,23 @@ function LogMethod(options = {}) {
 		const className = ((_constructor = target.constructor) === null || _constructor === void 0 ? void 0 : _constructor.name) ?? "Unknown";
 		const label = options.label ?? `${className}.${methodName}`;
 		let _warnedNoLogger = false;
-		descriptor.value = async function(...args) {
+		const reportLogFailure = (phase, err) => {
+			process.stderr.write(`[logixia] @LogMethod(${label}) ${phase} log failed: ${String(err)}\n`);
+		};
+		const emit$1 = (logger$1, phase, message, data) => {
+			const logFnRaw = logger$1[level];
+			const p = (typeof logFnRaw === "function" ? logFnRaw : logger$1.debug).bind(logger$1)(message, data);
+			if (p && typeof p.catch === "function") p.catch((e) => reportLogFailure(phase, e));
+		};
+		const emitError = (logger$1, error, start) => {
+			const err = error instanceof Error ? error : new Error(String(error));
+			const errLog = logger$1.error(err, {
+				method: label,
+				durationMs: Date.now() - start
+			});
+			if (errLog && typeof errLog.catch === "function") errLog.catch((e) => reportLogFailure("error", e));
+		};
+		descriptor.value = function(...args) {
 			const logger$1 = this.logger ?? LogixiaLoggerModule._globalLogger ?? void 0;
 			if (!logger$1 && !_warnedNoLogger) {
 				_warnedNoLogger = true;
@@ -255,36 +275,31 @@ function LogMethod(options = {}) {
 			const start = Date.now();
 			const entry = { method: label };
 			if (logArgs && args.length > 0) entry["args"] = args;
-			const reportLogFailure = (phase, err) => {
-				process.stderr.write(`[logixia] @LogMethod(${label}) ${phase} log failed: ${String(err)}\n`);
-			};
-			if (logger$1) {
-				const logFnRaw = logger$1[level];
-				await (typeof logFnRaw === "function" ? logFnRaw : logger$1.debug).bind(logger$1)(`→ ${label}`, entry).catch((e) => reportLogFailure("entry", e));
-			}
-			try {
-				const result = await originalMethod.apply(this, args);
+			if (logger$1) emit$1(logger$1, "entry", `→ ${label}`, entry);
+			const buildExit = (result$1) => {
 				const exit = {
 					method: label,
 					durationMs: Date.now() - start
 				};
-				if (logResult) exit["result"] = result;
-				if (logger$1) {
-					const logFnRaw = logger$1[level];
-					await (typeof logFnRaw === "function" ? logFnRaw : logger$1.debug).bind(logger$1)(`← ${label}`, exit).catch((e) => reportLogFailure("exit", e));
-				}
-				return result;
+				if (logResult) exit["result"] = result$1;
+				return exit;
+			};
+			let result;
+			try {
+				result = originalMethod.apply(this, args);
 			} catch (error) {
-				if (logger$1 && logErrors) {
-					const err = error instanceof Error ? error : new Error(String(error));
-					const errLog = logger$1.error(err, {
-						method: label,
-						durationMs: Date.now() - start
-					});
-					if (errLog !== void 0 && errLog !== null && typeof errLog.catch === "function") errLog.catch((e) => reportLogFailure("error", e));
-				}
+				if (logger$1 && logErrors) emitError(logger$1, error, start);
 				throw error;
 			}
+			if (result && typeof result.then === "function") return result.then((resolved) => {
+				if (logger$1) emit$1(logger$1, "exit", `← ${label}`, buildExit(resolved));
+				return resolved;
+			}, (error) => {
+				if (logger$1 && logErrors) emitError(logger$1, error, start);
+				throw error;
+			});
+			if (logger$1) emit$1(logger$1, "exit", `← ${label}`, buildExit(result));
+			return result;
 		};
 		return descriptor;
 	};
@@ -344,6 +359,21 @@ LogixiaExceptionFilter = __decorate([
 
 //#endregion
 //#region src/formatters/json.formatter.ts
+/**
+* Build a JSON.stringify replacer that replaces circular references with the
+* string '[Circular]' instead of throwing. A fresh replacer must be created per
+* stringify call because it holds per-serialization state (the seen set).
+*/
+function createCircularReplacer() {
+	const seen = /* @__PURE__ */ new WeakSet();
+	return function(_key, value) {
+		if (typeof value === "object" && value !== null) {
+			if (seen.has(value)) return "[Circular]";
+			seen.add(value);
+		}
+		return value;
+	};
+}
 var JsonFormatter = class {
 	constructor(options = {}) {
 		this.includeTimestamp = options.includeTimestamp ?? true;
@@ -371,7 +401,8 @@ var JsonFormatter = class {
 			hostname: process.env.HOSTNAME || "unknown",
 			version: process.version
 		};
-		return this.prettyPrint ? JSON.stringify(formatted, null, 2) : JSON.stringify(formatted);
+		const replacer = createCircularReplacer();
+		return this.prettyPrint ? JSON.stringify(formatted, replacer, 2) : JSON.stringify(formatted, replacer);
 	}
 	serializePayload(payload) {
 		const serialized = {};
@@ -474,11 +505,11 @@ var TextFormatter = class TextFormatter {
 				if (typeof value === "string") return `${key}="${value}"`;
 				if (typeof value === "number" || typeof value === "boolean") return `${key}=${value}`;
 				if (value instanceof Date) return `${key}=${value.toISOString()}`;
-				if (typeof value === "object") return `${key}=${JSON.stringify(value)}`;
+				if (typeof value === "object") return `${key}=${stripControls(safeToString(value))}`;
 				return `${key}=${String(value)}`;
 			}).join(" ");
 		} catch {
-			return JSON.stringify(payload);
+			return stripControls(safeToString(payload));
 		}
 	}
 	/**
@@ -515,6 +546,234 @@ var TextFormatter = class TextFormatter {
 	}
 };
 
+//#endregion
+//#region src/utils/runtime-control.ts
+const DEFAULT_CYCLE = [
+	"error",
+	"warn",
+	"info",
+	"debug",
+	"trace",
+	"verbose"
+];
+/**
+* Register an OS-signal handler that cycles the logger's global level on each
+* signal. Returns a dispose function that removes the listener.
+*
+* Cycling (rather than jumping straight to a fixed level) means a single,
+* memorizable command (`kill -USR2 <pid>`) is enough to ratchet verbosity up
+* while chasing a bug and back down again — no value to remember.
+*/
+function registerLevelSignal(logger$1, options = {}) {
+	const signal = options.signal ?? "SIGUSR2";
+	const cycle = options.cycle && options.cycle.length > 0 ? options.cycle : [...DEFAULT_CYCLE];
+	const handler = () => {
+		const current = logger$1.getLevel();
+		const next = cycle[(cycle.indexOf(current) + 1) % cycle.length];
+		logger$1.setLevel(next);
+		internalLog(`runtime level changed via ${signal}: ${current} → ${next}`);
+	};
+	process.on(signal, handler);
+	return () => {
+		process.removeListener(signal, handler);
+	};
+}
+const VALID_LEVELS = new Set([
+	"error",
+	"warn",
+	"info",
+	"debug",
+	"trace",
+	"verbose",
+	"fatal"
+]);
+/**
+* Create an HTTP handler (Node `http`/Express-compatible) that reads and sets
+* the logger's level at runtime.
+*
+*  - `GET`  → `{ level, namespaceLevels }`
+*  - `POST` → body `{ level?, namespaceLevels? }` applies them, returns the new state
+*
+* Custom levels are accepted too: any level the logger already knows passes
+* through. Unknown levels are rejected with 400 so a typo can't silently mute
+* logging. Mount behind your own auth — this intentionally has none.
+*/
+function createLevelControlHandler(logger$1, options = {}) {
+	const allowed = options.allowedLevels && options.allowedLevels.length > 0 ? new Set(options.allowedLevels.map((l) => l.toLowerCase())) : VALID_LEVELS;
+	const snapshot = () => {
+		var _logger$getNamespaceL;
+		return {
+			level: logger$1.getLevel(),
+			namespaceLevels: ((_logger$getNamespaceL = logger$1.getNamespaceLevels) === null || _logger$getNamespaceL === void 0 ? void 0 : _logger$getNamespaceL.call(logger$1)) ?? {}
+		};
+	};
+	const send = (res, status, body) => {
+		var _res$setHeader;
+		res.statusCode = status;
+		(_res$setHeader = res.setHeader) === null || _res$setHeader === void 0 || _res$setHeader.call(res, "Content-Type", "application/json");
+		res.end(JSON.stringify(body));
+	};
+	const applyBody = (res, raw) => {
+		let parsed;
+		try {
+			parsed = raw ? JSON.parse(raw) : {};
+		} catch {
+			send(res, 400, { error: "invalid JSON body" });
+			return;
+		}
+		if (parsed.level !== void 0) {
+			const lvl = String(parsed.level).toLowerCase();
+			if (!allowed.has(lvl)) {
+				send(res, 400, {
+					error: `unknown level "${parsed.level}"`,
+					allowed: [...allowed]
+				});
+				return;
+			}
+			logger$1.setLevel(lvl);
+		}
+		if (parsed.namespaceLevels !== void 0) {
+			if (typeof parsed.namespaceLevels !== "object" || parsed.namespaceLevels === null || Array.isArray(parsed.namespaceLevels)) {
+				send(res, 400, { error: "namespaceLevels must be an object" });
+				return;
+			}
+			const nl = parsed.namespaceLevels;
+			for (const [pat, lvl] of Object.entries(nl)) if (!allowed.has(String(lvl).toLowerCase())) {
+				send(res, 400, { error: `unknown level "${String(lvl)}" for namespace "${pat}"` });
+				return;
+			}
+			if (logger$1.setNamespaceLevels) {
+				const coerced = {};
+				for (const [pat, lvl] of Object.entries(nl)) coerced[pat] = String(lvl).toLowerCase();
+				logger$1.setNamespaceLevels(coerced);
+			} else internalWarn("level control: logger does not support setNamespaceLevels — ignored");
+		}
+		send(res, 200, snapshot());
+	};
+	return function levelControlHandler(req, res) {
+		const method = (req.method ?? "GET").toUpperCase();
+		if (method === "GET") {
+			send(res, 200, snapshot());
+			return;
+		}
+		if (method === "POST" || method === "PUT" || method === "PATCH") {
+			const maybeBody = req.body;
+			if (maybeBody !== void 0 && typeof req.on !== "function") {
+				applyBody(res, typeof maybeBody === "string" ? maybeBody : JSON.stringify(maybeBody));
+				return;
+			}
+			if (typeof req.on === "function") {
+				let raw = "";
+				req.on("data", (chunk) => {
+					raw += String(chunk ?? "");
+				});
+				req.on("end", () => applyBody(res, raw));
+				return;
+			}
+			applyBody(res, "");
+			return;
+		}
+		send(res, 405, { error: `method ${method} not allowed` });
+	};
+}
+
+//#endregion
+//#region src/utils/safe-stringify.ts
+/** Build a JSONPath like `$["a"][0]["b"]` for a decycle pointer. */
+function jsonPath(parts) {
+	let path = "$";
+	for (const p of parts) path += typeof p === "number" ? `[${p}]` : `[${JSON.stringify(p)}]`;
+	return path;
+}
+/**
+* Serialize any value to JSON without throwing on circular references or BigInt.
+* Circular refs become `"[Circular]"` (or `{ $ref }` pointers when `decycle`).
+*/
+function safeStringify(value, options = {}) {
+	const { indent, deterministic = false, decycle = false, bigint = "string" } = options;
+	if (decycle) return JSON.stringify(decycleValue(value, bigint), void 0, indent);
+	const seen = /* @__PURE__ */ new WeakSet();
+	const transform = (val) => {
+		if (typeof val === "bigint") return bigint === "number" ? Number(val) : val.toString();
+		if (typeof val === "function") return `[Function: ${val.name || "anonymous"}]`;
+		if (typeof val === "symbol") return val.toString();
+		if (val === null || typeof val !== "object") return val;
+		if (seen.has(val)) return "[Circular]";
+		seen.add(val);
+		let out;
+		if (Array.isArray(val)) out = val.map((item) => transform(item));
+		else if (val instanceof Date) out = val.toISOString();
+		else {
+			const rec = val;
+			const keys = deterministic ? Object.keys(rec).sort() : Object.keys(rec);
+			const obj = {};
+			for (const k of keys) {
+				if (k === "__proto__" || k === "constructor" || k === "prototype") continue;
+				obj[k] = transform(rec[k]);
+			}
+			out = obj;
+		}
+		seen.delete(val);
+		return out;
+	};
+	return JSON.stringify(transform(value), void 0, indent);
+}
+/**
+* Replace repeated object references with round-trippable `{ "$ref": "$..." }`
+* JSONPath pointers (the classic Crockford decycle). Pair with {@link retrocycle}
+* to reconstruct the original shared/circular graph.
+*/
+function decycleValue(value, bigint = "string") {
+	const paths = /* @__PURE__ */ new WeakMap();
+	const walk = (val, path) => {
+		if (typeof val === "bigint") return bigint === "number" ? Number(val) : val.toString();
+		if (val === null || typeof val !== "object") return val;
+		if (val instanceof Date) return val.toISOString();
+		const existing = paths.get(val);
+		if (existing !== void 0) return { $ref: existing };
+		paths.set(val, jsonPath(path));
+		if (Array.isArray(val)) return val.map((item, i) => walk(item, [...path, i]));
+		const rec = val;
+		const obj = {};
+		for (const k of Object.keys(rec)) {
+			if (k === "__proto__" || k === "constructor" || k === "prototype") continue;
+			obj[k] = walk(rec[k], [...path, k]);
+		}
+		return obj;
+	};
+	return walk(value, []);
+}
+/**
+* Inverse of {@link decycleValue}: resolve `{ "$ref": "$..." }` pointers back
+* into the live object graph (mutates and returns the parsed input).
+*/
+function retrocycle(root) {
+	const refRe = /^\$(?:\[(?:\d+|"(?:[^"\\]|\\.)*")\])*$/;
+	const resolve = (path) => {
+		const segs = [];
+		const partRe = /\[(\d+|"(?:[^"\\]|\\.)*")\]/g;
+		let m;
+		while ((m = partRe.exec(path)) !== null) {
+			const raw = m[1];
+			segs.push(raw.startsWith("\"") ? JSON.parse(raw) : Number(raw));
+		}
+		let node = root;
+		for (const s of segs) node = node[s];
+		return node;
+	};
+	const walk = (val) => {
+		if (val === null || typeof val !== "object") return;
+		const rec = val;
+		for (const k of Object.keys(rec)) {
+			const child = rec[k];
+			if (child !== null && typeof child === "object" && typeof child.$ref === "string" && refRe.test(child.$ref)) rec[k] = resolve(child.$ref);
+			else walk(child);
+		}
+	};
+	walk(root);
+	return root;
+}
+
 //#endregion
 //#region src/utils/typed-logger.ts
 /**
@@ -575,6 +834,258 @@ function createTypedLogger(logger$1, schema) {
 	};
 }
 
+//#endregion
+//#region src/wide-events.ts
+const _storage = new AsyncLocalStorage();
+/**
+* Merge fields into the wide event for the current async scope. No-op (with no
+* throw) when called outside a `withWideEvent` / middleware scope, so business
+* code can call it unconditionally.
+*/
+function addEventFields(fields) {
+	const state = _storage.getStore();
+	if (!state || state.emitted) return;
+	Object.assign(state.fields, fields);
+}
+/** Set a single field on the current wide event. */
+function setEventField(key, value) {
+	addEventFields({ [key]: value });
+}
+/** Read a shallow copy of the wide event accumulated so far, or undefined. */
+function getEventFields() {
+	const state = _storage.getStore();
+	return state ? { ...state.fields } : void 0;
+}
+function emit(logger$1, state, options, extra) {
+	if (state.emitted) return;
+	state.emitted = true;
+	const level = options.level ?? "info";
+	const message = options.message ?? "request";
+	const durationField = options.durationField ?? "durationMs";
+	const includeTrace = options.includeTrace ?? true;
+	const payload = { ...state.fields };
+	if (extra) Object.assign(payload, extra);
+	payload[durationField] = Date.now() - state.startMs;
+	if (includeTrace) {
+		const traceId = getCurrentTraceId();
+		if (traceId !== void 0 && payload["traceId"] === void 0) payload["traceId"] = traceId;
+	}
+	const p = logger$1.logLevel(level, message, payload);
+	if (p && typeof p.catch === "function") p.catch(() => {});
+}
+/**
+* Run `callback` inside a wide-event scope. `addEventFields` calls anywhere in
+* the (async) call tree accumulate onto one event, which is emitted exactly once
+* when the callback settles — on success OR error (the canonical "emit in
+* finally" guarantee). On error, `error` + `errorMessage` fields are added.
+*/
+async function withWideEvent(logger$1, initialFields, callback, options = {}) {
+	const state = {
+		fields: { ...initialFields },
+		startMs: Date.now(),
+		emitted: false
+	};
+	return _storage.run(state, async () => {
+		try {
+			const result = await callback();
+			emit(logger$1, state, options);
+			return result;
+		} catch (error) {
+			emit(logger$1, state, options, {
+				error: true,
+				errorMessage: error instanceof Error ? error.message : String(error)
+			});
+			throw error;
+		}
+	});
+}
+/**
+* Express/Connect middleware that opens a wide-event scope per request and
+* emits ONE canonical event on response `finish`/`close` — even if the handler
+* throws or the client disconnects. Pre-populates method/url/ip; handlers add
+* more via `addEventFields`. The completion event includes `statusCode` and the
+* request duration.
+*/
+function wideEventMiddleware(logger$1, options = {}) {
+	return function logixiaWideEventMiddleware(req, res, next) {
+		var _options$skip, _req$socket, _res$once, _res$once2;
+		if ((_options$skip = options.skip) === null || _options$skip === void 0 ? void 0 : _options$skip.call(options, req)) {
+			next();
+			return;
+		}
+		const state = {
+			fields: {
+				method: req.method,
+				url: req.originalUrl ?? req.url,
+				ip: req.ip ?? ((_req$socket = req.socket) === null || _req$socket === void 0 ? void 0 : _req$socket.remoteAddress),
+				...options.enrich ? options.enrich(req) : {}
+			},
+			startMs: Date.now(),
+			emitted: false
+		};
+		const finalize = () => {
+			emit(logger$1, state, options, { statusCode: res.statusCode ?? 0 });
+		};
+		(_res$once = res.once) === null || _res$once === void 0 || _res$once.call(res, "finish", finalize);
+		(_res$once2 = res.once) === null || _res$once2 === void 0 || _res$once2.call(res, "close", finalize);
+		_storage.run(state, () => next());
+	};
+}
+
+//#endregion
+//#region src/transports/otlp.transport.ts
+/**
+* Map a logixia level name to an OTel SeverityNumber (1–24) and text.
+* Per the OTel logs SDK spec: TRACE=1, DEBUG=5, INFO=9, WARN=13, ERROR=17,
+* FATAL=21. Custom/unknown levels fall back to INFO (9).
+*/
+function toOtelSeverity(level) {
+	switch (level.toLowerCase()) {
+		case "trace": return {
+			number: 1,
+			text: "TRACE"
+		};
+		case "verbose": return {
+			number: 5,
+			text: "DEBUG"
+		};
+		case "debug": return {
+			number: 5,
+			text: "DEBUG"
+		};
+		case "info": return {
+			number: 9,
+			text: "INFO"
+		};
+		case "warn":
+		case "warning": return {
+			number: 13,
+			text: "WARN"
+		};
+		case "error": return {
+			number: 17,
+			text: "ERROR"
+		};
+		case "fatal": return {
+			number: 21,
+			text: "FATAL"
+		};
+		default: return {
+			number: 9,
+			text: "INFO"
+		};
+	}
+}
+/** Coerce a JS value into an OTLP AnyValue. */
+function toAnyValue(value) {
+	if (typeof value === "string") return { stringValue: value };
+	if (typeof value === "boolean") return { boolValue: value };
+	if (typeof value === "number") return Number.isInteger(value) ? { intValue: value } : { doubleValue: value };
+	if (typeof value === "bigint") return { stringValue: value.toString() };
+	if (value === null || value === void 0) return { stringValue: "" };
+	try {
+		return { stringValue: JSON.stringify(value) };
+	} catch {
+		return { stringValue: String(value) };
+	}
+}
+/** Build the OTLP KeyValue attribute list from a flat record. */
+function toAttributes(rec) {
+	return Object.entries(rec).map(([key, value]) => ({
+		key,
+		value: toAnyValue(value)
+	}));
+}
+var OtlpLogTransport = class {
+	constructor(config) {
+		this.name = "otlp";
+		this.batch = [];
+		this.flushTimer = null;
+		this.url = config.url;
+		this.headers = config.headers ?? {};
+		this.batchSize = config.batchSize ?? 100;
+		this.flushIntervalMs = config.flushIntervalMs ?? 5e3;
+		this.level = config.level;
+		this.resourceAttrs = toAttributes({
+			"service.name": config.serviceName ?? "logixia",
+			...config.serviceVersion ? { "service.version": config.serviceVersion } : {},
+			...config.environment ? { "deployment.environment": config.environment } : {},
+			...config.resourceAttributes ?? {}
+		});
+		this.flushTimer = setInterval(() => {
+			this.flush().catch(() => {});
+		}, this.flushIntervalMs);
+		if (this.flushTimer.unref) this.flushTimer.unref();
+	}
+	write(entry) {
+		this.batch.push(entry);
+		if (this.batch.length >= this.batchSize) this.flush().catch(() => {});
+	}
+	/** Convert one entry into an OTLP LogRecord. */
+	toLogRecord(entry) {
+		const sev = toOtelSeverity(entry.level);
+		const tsNanos = String(entry.timestamp.getTime() * 1e6);
+		const attrs = { ...entry.data ?? {} };
+		if (entry.context !== void 0) attrs["context"] = entry.context;
+		if (entry.appName !== void 0) attrs["app.name"] = entry.appName;
+		if (entry.environment !== void 0) attrs["deployment.environment"] = entry.environment;
+		const record = {
+			timeUnixNano: tsNanos,
+			observedTimeUnixNano: tsNanos,
+			severityNumber: sev.number,
+			severityText: sev.text,
+			body: { stringValue: entry.message },
+			attributes: toAttributes(attrs)
+		};
+		if (entry.traceId) record["traceId"] = entry.traceId;
+		return record;
+	}
+	buildPayload(entries) {
+		return JSON.stringify({ resourceLogs: [{
+			resource: { attributes: this.resourceAttrs },
+			scopeLogs: [{
+				scope: { name: "logixia" },
+				logRecords: entries.map((e) => this.toLogRecord(e))
+			}]
+		}] });
+	}
+	async flush() {
+		while (this.batch.length > 0) {
+			const entries = this.batch.splice(0, this.batchSize);
+			try {
+				await this.send(entries);
+			} catch (err) {
+				internalError("OtlpLogTransport flush error", err);
+				this.batch.unshift(...entries);
+				return;
+			}
+		}
+	}
+	async send(entries) {
+		if (typeof fetch !== "function") {
+			internalWarn("OtlpLogTransport: global fetch unavailable — cannot export logs");
+			return;
+		}
+		const res = await fetch(this.url, {
+			method: "POST",
+			headers: {
+				"Content-Type": "application/json",
+				...this.headers
+			},
+			body: this.buildPayload(entries)
+		});
+		if (!res.ok) throw new Error(`OTLP export failed: HTTP ${res.status}`);
+	}
+	async close() {
+		if (this.flushTimer) {
+			clearInterval(this.flushTimer);
+			this.flushTimer = null;
+		}
+		for (let attempt = 0; attempt < 3 && this.batch.length > 0; attempt += 1) await this.flush();
+		if (this.batch.length > 0) internalError(`OtlpLogTransport closing with ${this.batch.length} undelivered record(s)`);
+	}
+};
+
 //#endregion
 //#region src/metrics.ts
 const DEFAULT_BUCKETS = [
@@ -598,7 +1109,7 @@ function buildLabelKey(config, entry) {
 	const payload = entry.payload ?? {};
 	for (const name of labelNames) {
 		const raw = name === "level" ? entry.level : payload[name];
-		pairs[name] = raw !== void 0 && raw !== null ? String(raw) : "";
+		pairs[sanitizePromName(name)] = raw !== void 0 && raw !== null ? String(raw) : "";
 	}
 	return JSON.stringify(pairs);
 }
@@ -611,6 +1122,18 @@ function escapeLabel(value) {
 	return value.replace(/\\/g, "\\\\").replace(/"/g, "\\\"").replace(/\n/g, "\\n");
 }
 /**
+* Coerce an arbitrary string into a valid Prometheus metric or label name
+* (`[a-zA-Z_][a-zA-Z0-9_]*`). Invalid characters become underscores and a
+* leading digit is prefixed with `_`. Without this, a user-supplied name like
+* `my-metric` or a label like `status code` would emit output Prometheus cannot
+* parse, breaking the ENTIRE scrape endpoint, not just that metric.
+*/
+function sanitizePromName(name) {
+	let safe = name.replace(/\W/g, "_");
+	if (safe.length > 0 && /\d/.test(safe[0])) safe = `_${safe}`;
+	return safe.length > 0 ? safe : "_";
+}
+/**
 * A logixia plugin that extracts Prometheus-compatible metrics from log entries.
 *
 * Implements `LogixiaPlugin` — pass directly to `logger.use()`:
@@ -684,7 +1207,7 @@ var MetricsPlugin = class {
 	render() {
 		const lines = [];
 		for (const [rawName, config] of Object.entries(this.map)) {
-			const metricName = `logixia_${rawName}`;
+			const metricName = `logixia_${sanitizePromName(rawName)}`;
 			const state = this.metricState.get(rawName);
 			if (!state) continue;
 			const helpText = config.help ?? rawName.replace(/_/g, " ");
@@ -889,5 +1412,5 @@ const logger = new LogixiaLogger(DEFAULT_CONFIG);
 */
 
 //#endregion
-export { DEFAULT_CONFIG, DEFAULT_LOG_COLORS, DEFAULT_LOG_LEVELS, DEFAULT_TRACE_HEADERS, ErrorResponseBuilder, InjectLogger, JsonFormatter, KafkaTraceInterceptor, LOGIXIA_LOGGER_CONFIG, LOGIXIA_LOGGER_PREFIX, LogLevel, LogMethod, LogixiaContext, LogixiaException, LogixiaExceptionFilter, LogixiaLogger, LogixiaLoggerModule, LogixiaLoggerService, MetricsPlugin, PluginRegistry, TRACE_CONTEXT_KEY, TextFormatter, TraceContext, WebSocketTraceInterceptor, _setActiveContextKey, applyRedaction, createExpressContextMiddleware, createFastifyContextHook, createLogger, createLoggerService, createMetricsPlugin, createTraceMiddleware, createTypedLogger, defineLogSchema, deregisterFromShutdown, disableOtelBridge, extractTraceId, flushOnExit, generateRequestId, generateTraceId, getActiveOtelContext, getCurrentTraceId, getOtelMetaFields, getTraceContextKey, globalPluginRegistry, initOtelBridge, isError, isLogixiaException, logger, normalizeError, redactObject, registerForShutdown, resetShutdownHandlers, runWithTraceId, serializeError, setTraceId, traceStorage, usePlugin };
+export { DEFAULT_CONFIG, DEFAULT_LOG_COLORS, DEFAULT_LOG_LEVELS, DEFAULT_TRACE_HEADERS, ErrorResponseBuilder, InjectLogger, JsonFormatter, KafkaTraceInterceptor, LOGIXIA_LOGGER_CONFIG, LOGIXIA_LOGGER_PREFIX, LogLevel, LogMethod, LogixiaContext, LogixiaException, LogixiaExceptionFilter, LogixiaLogger, LogixiaLoggerModule, LogixiaLoggerService, MetricsPlugin, OtlpLogTransport, PluginRegistry, TRACE_CONTEXT_KEY, TextFormatter, TraceContext, WebSocketTraceInterceptor, _setActiveContextKey, addEventFields, applyRedaction, createExpressContextMiddleware, createFastifyContextHook, createLevelControlHandler, createLogger, createLoggerService, createMetricsPlugin, createTraceMiddleware, createTypedLogger, decycleValue, defineLogSchema, deregisterFromShutdown, disableOtelBridge, extractTraceId, flushOnExit, generateRequestId, generateTraceId, getActiveOtelContext, getCurrentTraceId, getEventFields, getOtelMetaFields, getTraceContextKey, globalPluginRegistry, initOtelBridge, isError, isLogixiaException, logger, normalizeError, redactObject, registerForShutdown, registerLevelSignal, resetShutdownHandlers, retrocycle, runWithTraceId, safeStringify, serializeError, setEventField, setTraceId, toOtelSeverity, traceStorage, usePlugin, wideEventMiddleware, withWideEvent };
 //# sourceMappingURL=index.mjs.map