logixia 2.0.0 → 2.0.4

package/dist/{builder-0gEzRopq.mjs → builder-D70z6kjj.mjs}

@@ -1,14 +1,14 @@
-import { t as __require } from "./chunk-DLSkYcPk.mjs";
-import { n as internalLog, r as internalWarn, t as internalError } from "./internal-log-Cm8SOWSV.mjs";
-import { i as stringifyForLog } from "./safe-stringify-DJ66tW5I.mjs";
-import { i as TraceContext } from "./trace.utils-CvXgaiQT.mjs";
-import { t as LogixiaContext } from "./async-context-BzJrbfQs.mjs";
-import { t as safeToString } from "./coerce.utils-Cu6IUTgX.mjs";
-import { d as stripControlChars, t as TransportManager } from "./transport.manager-BiuCAJd2.mjs";
-import { constants } from "node:os";
+import { t as __require } from "./rolldown-runtime-D3PmRqjj.mjs";
+import { o as TraceContext } from "./request-trace-C_fvIDv4.mjs";
+import { t as LogixiaContext } from "./async-context-B05ArHgM.mjs";
+import { n as internalLog, o as SENSITIVE_KEY_NAMES, r as internalWarn, t as internalError } from "./internal-log-uCSd1PMc.mjs";
+import { n as protectSecrets } from "./secret-config-BegMLkYl.mjs";
+import { t as safeToString } from "./coerce.utils-B_rEudCn.mjs";
+import { i as stringifyForLog } from "./safe-stringify-BMRl3EX3.mjs";
+import { d as stripControlChars, t as TransportManager } from "./transport.manager-eZ_EeC00.mjs";
 import buildFastStringify from "fast-json-stringify";
-
-//#region src/types/index.ts
+import { constants } from "node:os";
+// src/types/index.ts
 const LogLevel = {
 	ERROR: "error",
 	WARN: "warn",
@@ -33,9 +33,7 @@ const DEFAULT_LOG_COLORS = {
 	trace: "magenta",
 	verbose: "cyan"
 };
-
-//#endregion
-//#region src/core/default-config.ts
+// src/core/default-config.ts
 /**
 * Default configuration for Logixia logger
 */
@@ -79,9 +77,7 @@ const DEFAULT_CONFIG = {
 	},
 	outputs: ["console"]
 };
-
-//#endregion
-//#region src/plugin.ts
+// src/plugin.ts
 /**
 * Holds an ordered list of `LogixiaPlugin` instances and dispatches lifecycle
 * events to them. One registry is created per logger instance; a global
@@ -186,9 +182,7 @@ const globalPluginRegistry = new PluginRegistry();
 function usePlugin(plugin) {
 	globalPluginRegistry.register(plugin);
 }
-
-//#endregion
-//#region src/utils/error.utils.ts
+// src/utils/error.utils.ts
 const EXTRA_FIELDS = [
 	"code",
 	"statusCode",
@@ -230,13 +224,15 @@ function _serializeError(error, includeStack, maxDepth, excludeFields, depth, se
 	};
 	if (includeStack && error.stack) serialized.stack = error.stack;
 	const errorWithCause = error;
-	if (errorWithCause.cause !== void 0) if (errorWithCause.cause instanceof Error) serialized.cause = _serializeError(errorWithCause.cause, includeStack, maxDepth, excludeFields, depth + 1, seen);
-	else serialized.cause = serializeValue(errorWithCause.cause, maxDepth - depth - 1, seen);
+	if (errorWithCause.cause !== void 0) {
+		if (errorWithCause.cause instanceof Error) serialized.cause = _serializeError(errorWithCause.cause, includeStack, maxDepth, excludeFields, depth + 1, seen);
+		else serialized.cause = serializeValue(errorWithCause.cause, maxDepth - depth - 1, seen);
+	}
 	const aggregateError = error;
 	if (Array.isArray(aggregateError.errors)) serialized.errors = aggregateError.errors.map((e) => e instanceof Error ? _serializeError(e, includeStack, maxDepth, excludeFields, depth + 1, seen) : serializeValue(e, maxDepth - depth - 1, seen));
 	const errorRecord = error;
 	for (const field of EXTRA_FIELDS) if (!excludeFields.includes(field) && field in error && errorRecord[field] !== void 0) serialized[field] = errorRecord[field];
-	const skip = new Set([
+	const skip = /* @__PURE__ */ new Set([
 		"name",
 		"message",
 		"stack",
@@ -318,9 +314,7 @@ function normalizeError(error) {
 	}
 	return new Error(String(error));
 }
-
-//#endregion
-//#region src/utils/otel.ts
+// src/utils/otel.ts
 let _otelApi;
 function tryLoadOtelApi() {
 	if (_otelApi !== void 0) return _otelApi;
@@ -425,9 +419,7 @@ function _getOtelPayloadIfEnabled() {
 function disableOtelBridge() {
 	_bridgeOptions = null;
 }
-
-//#endregion
-//#region src/utils/redact.utils.ts
+// src/utils/redact.utils.ts
 const DEFAULT_CENSOR = "[REDACTED]";
 /** Maximum nesting depth walked; deeper values are replaced with a marker. */
 const MAX_DEPTH = 32;
@@ -456,34 +448,7 @@ const PII_CONSERVATIVE_PATTERNS = [
 /**
 * Conservative field-name paths auto-redacted by name regardless of value.
 */
-const PII_CONSERVATIVE_PATHS = [
-	"**.password",
-	"**.passwd",
-	"**.secret",
-	"**.token",
-	"**.apiKey",
-	"**.api_key",
-	"**.accessToken",
-	"**.access_token",
-	"**.refreshToken",
-	"**.refresh_token",
-	"**.authorization",
-	"**.credentials",
-	"**.privateKey",
-	"**.private_key",
-	"**.clientSecret",
-	"**.client_secret",
-	"**.cookie",
-	"**.set-cookie",
-	"**.x-api-key",
-	"**.session",
-	"**.proxy-authorization",
-	"**.x-auth-token",
-	"**.x-access-token",
-	"**.aws_secret_access_key",
-	"**.awsSecretAccessKey",
-	"**.secretAccessKey"
-];
+const PII_CONSERVATIVE_PATHS = SENSITIVE_KEY_NAMES.map((name) => `**.${name}`);
 /**
 * Aggressive patterns: also catch personal data that could identify a person.
 * Applied when `autoDetect: 'aggressive'`.
@@ -695,7 +660,7 @@ function walkToJSON(obj, state, fullPath, bare, depth) {
 function redactObject(obj, config, _currentPath = "") {
 	const result = walkRecord(obj, {
 		config,
-		ancestors: new Set([obj]),
+		ancestors: /* @__PURE__ */ new Set([obj]),
 		nodes: 0
 	}, _currentPath, _currentPath, 0);
 	return result === obj ? { ...obj } : result;
@@ -744,10 +709,8 @@ function isPlainObject(value) {
 	if (ArrayBuffer.isView(value)) return false;
 	return !OPAQUE_BUILTINS.some((ctor) => value instanceof ctor);
 }
-
-//#endregion
-//#region src/utils/sampling.utils.ts
-const ALWAYS_EMIT_LEVELS = new Set([
+// src/utils/sampling.utils.ts
+const ALWAYS_EMIT_LEVELS = /* @__PURE__ */ new Set([
 	"error",
 	"warn",
 	"fatal"
@@ -765,8 +728,8 @@ var Sampler = class {
 	constructor(config, onStats) {
 		this.traceDecisions = /* @__PURE__ */ new Map();
 		this.maxTrackedTraces = 1e5;
-		this.traceTtlMs = 5 * 6e4;
-		this.traceMaxLifetimeMs = 60 * 6e4;
+		this.traceTtlMs = 3e5;
+		this.traceMaxLifetimeMs = 36e5;
 		this._tokenBucket = 0;
 		this._lastRefillMs = Date.now();
 		this._adaptiveWindow = [];
@@ -945,9 +908,14 @@ var Sampler = class {
 		this._stats.dropped++;
 	}
 };
-
-//#endregion
-//#region src/utils/shutdown.utils.ts
+// src/utils/shutdown.utils.ts
+/**
+* Graceful shutdown utilities for Logixia
+*
+* Ensures all in-flight logs are flushed to every transport before the process
+* exits on SIGTERM / SIGINT — solving the "last N seconds of logs are lost on
+* deployment" problem reported in Pino issue #2002 and LogDNA issue #15.
+*/
 const MAX_BEFORE_EXIT_FLUSHES = 5;
 /** Module-level registry of all logger instances that have opted into graceful shutdown */
 const registry = /* @__PURE__ */ new Set();
@@ -1067,9 +1035,17 @@ function resetShutdownHandlers() {
 	shutdownHandlerRegistered = false;
 	shutdownInProgress = false;
 }
-
-//#endregion
-//#region src/core/logitron-logger.ts
+// src/core/logitron-logger.ts
+/**
+* Core Logixia Logger implementation
+*
+* v1.1 additions:
+*  - Feature 1: Graceful shutdown / flushOnExit (auto-registered via config)
+*  - Feature 2: Built-in log redaction (path-based + regex)
+*  - Feature 3: Per-namespace log levels + LOGIXIA_LEVEL* ENV overrides
+*  - Feature 4: Cause-chain error serialization (handled in error.utils)
+*  - Feature 5: Adaptive log level based on NODE_ENV / CI detection
+*/
 const _fastStringifyEntry = buildFastStringify({
 	type: "object",
 	properties: {
@@ -1099,7 +1075,7 @@ function nowIso() {
 }
 function namespacePatternToRegex(pattern) {
 	const escaped = pattern.split(".").map((s) => s === "*" ? "[^.]+" : s.replace(/[$()*+.?[\\\]^{|}]/g, "\\$&")).join("\\.");
-	return /* @__PURE__ */ new RegExp(`^${escaped}$`);
+	return new RegExp(`^${escaped}$`);
 }
 /** Max compiled patterns to keep in memory. Oldest entry is evicted when full. */
 const _NS_CACHE_MAX = 1e3;
@@ -1141,7 +1117,7 @@ function canonicalLevel(level, known) {
 function resolveInitialLevel(config) {
 	var _config$levelOptions, _config$levelOptions2;
 	const envLevel = process.env["LOGIXIA_LEVEL"];
-	const knownLevels = new Set([...Object.values(LogLevel), ...Object.keys(((_config$levelOptions = config.levelOptions) === null || _config$levelOptions === void 0 ? void 0 : _config$levelOptions.levels) ?? {})]);
+	const knownLevels = /* @__PURE__ */ new Set([...Object.values(LogLevel), ...Object.keys(((_config$levelOptions = config.levelOptions) === null || _config$levelOptions === void 0 ? void 0 : _config$levelOptions.levels) ?? {})]);
 	if (envLevel && canonicalLevel(envLevel, knownLevels)) return envLevel;
 	if ((_config$levelOptions2 = config.levelOptions) === null || _config$levelOptions2 === void 0 ? void 0 : _config$levelOptions2.level) return config.levelOptions.level;
 	const nodeEnv = process.env["NODE_ENV"];
@@ -1151,6 +1127,19 @@ function resolveInitialLevel(config) {
 	if (process.env["CI"]) return LogLevel.INFO;
 	return LogLevel.INFO;
 }
+/**
+* The logixia logger. Create instances with {@link createLogger} so that custom
+* levels from `levelOptions.levels` also become methods.
+*
+* @example
+* ```ts
+* const logger = createLogger({ appName: 'api', environment: 'production' });
+* await logger.info('Server started', { port: 3000 });
+* const req = logger.child('RequestHandler', { requestId: 'r-1' });
+* await req.error(new Error('boom'));
+* await logger.close(); // flush buffered transports before exit
+* ```
+*/
 var LogixiaLogger = class LogixiaLogger {
 	constructor(config, context, parent) {
 		this.timers = /* @__PURE__ */ new Map();
@@ -1168,7 +1157,7 @@ var LogixiaLogger = class LogixiaLogger {
 		this._hasRedact = false;
 		this._parent = parent;
 		this._pluginRegistry = parent ? parent._pluginRegistry : new PluginRegistry();
-		this.config = {
+		const defaultConfig = {
 			appName: "App",
 			environment: "development",
 			traceId: true,
@@ -1196,7 +1185,10 @@ var LogixiaLogger = class LogixiaLogger {
 					[LogLevel.TRACE]: "gray",
 					[LogLevel.VERBOSE]: "cyan"
 				}
-			},
+			}
+		};
+		this.config = {
+			...defaultConfig,
 			...config
 		};
 		const resolvedLevel = resolveInitialLevel(this.config);
@@ -1214,6 +1206,7 @@ var LogixiaLogger = class LogixiaLogger {
 			timeTaken: "[time_taken_MS]"
 		};
 		this.context = context ?? "";
+		protectSecrets(this, ["config"]);
 		if (parent) {
 			this.transportManager = parent.transportManager;
 			this._sampler = parent._sampler;
@@ -1279,7 +1272,7 @@ var LogixiaLogger = class LogixiaLogger {
 		this.config.levelOptions.level = this._validLevel(this.config.levelOptions.level, "levelOptions.level") ?? LogLevel.INFO;
 		const effectiveLevel = this.resolveEffectiveLevel();
 		this._minLevelValue = this._levelValues.get(effectiveLevel) ?? 2;
-		this._colorMap = new Map([
+		this._colorMap = /* @__PURE__ */ new Map([
 			["black", "\x1B[30m"],
 			["red", "\x1B[31m"],
 			["green", "\x1B[32m"],
@@ -1322,7 +1315,7 @@ var LogixiaLogger = class LogixiaLogger {
 			"green",
 			"blue"
 		];
-		const _BUILTIN_LEVELS = new Set([
+		const _BUILTIN_LEVELS = /* @__PURE__ */ new Set([
 			"error",
 			"warn",
 			"info",
@@ -1336,10 +1329,12 @@ var LogixiaLogger = class LogixiaLogger {
 			if (colorize && this._fieldCache.get("level") !== false) {
 				var _this$config$levelOpt4;
 				let colorName = (_this$config$levelOpt4 = this.config.levelOptions) === null || _this$config$levelOpt4 === void 0 || (_this$config$levelOpt4 = _this$config$levelOpt4.colors) === null || _this$config$levelOpt4 === void 0 ? void 0 : _this$config$levelOpt4[lvl];
-				if (!colorName) if (_BUILTIN_LEVELS.has(lvl)) colorName = "white";
-				else {
-					colorName = _AUTO_PALETTE[_paletteIdx % _AUTO_PALETTE.length];
-					_paletteIdx++;
+				if (!colorName) {
+					if (_BUILTIN_LEVELS.has(lvl)) colorName = "white";
+					else {
+						colorName = _AUTO_PALETTE[_paletteIdx % _AUTO_PALETTE.length];
+						_paletteIdx++;
+					}
 				}
 				const code = this._colorMap.get(colorName.toLowerCase()) ?? this._colorMap.get("white");
 				const reset = this._colorMap.get("reset");
@@ -1351,6 +1346,11 @@ var LogixiaLogger = class LogixiaLogger {
 		else this._formattedAppName = colorize ? `${this._colorMap.get("gray")}${appNameRaw}${this._colorMap.get("reset")} ` : `${appNameRaw} `;
 		this._hasRedact = !!(this.config.redact && ((((_this$config$redact$p = this.config.redact.paths) === null || _this$config$redact$p === void 0 ? void 0 : _this$config$redact$p.length) ?? 0) > 0 || (((_this$config$redact$p2 = this.config.redact.patterns) === null || _this$config$redact$p2 === void 0 ? void 0 : _this$config$redact$p2.length) ?? 0) > 0 || !!this.config.redact.autoDetect));
 	}
+	/**
+	* Log at `error` level. An `Error` is logged with its message and serialized
+	* (name, message, stack) under `data.error`; a string is logged as-is.
+	* `data` is merged into the entry payload.
+	*/
 	async error(messageOrError, data) {
 		if (isError(messageOrError)) await this.log("error", messageOrError.message, {
 			...data,
@@ -1358,30 +1358,53 @@ var LogixiaLogger = class LogixiaLogger {
 		});
 		else await this.log("error", messageOrError, data);
 	}
+	/** Log `message` at `warn` level; `data` is merged into the entry payload. */
 	async warn(message, data) {
 		await this.log("warn", message, data);
 	}
+	/** Log `message` at `info` level; `data` is merged into the entry payload. */
 	async info(message, data) {
 		await this.log("info", message, data);
 	}
+	/** Log `message` at `debug` level; `data` is merged into the entry payload. */
 	async debug(message, data) {
 		await this.log("debug", message, data);
 	}
+	/** Log `message` at `trace` level; `data` is merged into the entry payload. */
 	async trace(message, data) {
 		await this.log("trace", message, data);
 	}
+	/** Log `message` at `verbose` level; `data` is merged into the entry payload. */
 	async verbose(message, data) {
 		await this.log("verbose", message, data);
 	}
+	/**
+	* Log at an arbitrary level name, including custom levels. Levels below the
+	* active threshold are dropped, as are level names that are not registered
+	* in `levelOptions.levels` (and are not built-in).
+	*/
 	async logLevel(level, message, data) {
 		await this.log(level, message, data);
 	}
+	/** Start a named timer; finish it with {@link timeEnd}. Reusing a label restarts it. */
 	time(label) {
 		this.timers.set(label, {
 			label,
 			startTime: Date.now()
 		});
 	}
+	/**
+	* Stop the timer `label`, log its duration at `info` level, and return the
+	* elapsed milliseconds. Logs a `warn` and returns `undefined` if the timer
+	* does not exist.
+	*
+	* @example
+	* ```ts
+	* logger.time('db');
+	* await query();
+	* const ms = await logger.timeEnd('db');
+	* ```
+	*/
 	async timeEnd(label) {
 		const timer = this.timers.get(label);
 		if (!timer) {
@@ -1411,6 +1434,17 @@ var LogixiaLogger = class LogixiaLogger {
 			throw error;
 		}
 	}
+	/**
+	* Change the minimum log level at runtime. The override outranks
+	* `LOGIXIA_LEVEL`, `LOGIXIA_LEVEL_<NS>` and `namespaceLevels`, and survives
+	* later changes to fields or namespace levels. Unknown level names are
+	* ignored with a warning and the current level is kept.
+	*
+	* @example
+	* ```ts
+	* logger.setLevel('debug');
+	* ```
+	*/
 	setLevel(level) {
 		const canonical = canonicalLevel(level, this._levelValues);
 		if (canonical === void 0) {
@@ -1419,9 +1453,14 @@ var LogixiaLogger = class LogixiaLogger {
 		}
 		this.config.levelOptions = this.config.levelOptions ?? {};
 		this.config.levelOptions.level = canonical;
-		this._minLevelValue = this._levelValues.get(canonical) ?? this._minLevelValue;
+		this._runtimeLevel = canonical;
 		this._buildPerfCaches();
 	}
+	/**
+	* Return the configured minimum log level, not the per-namespace effective
+	* one. Without `setLevel()` it is `LOGIXIA_LEVEL`, else `levelOptions.level`,
+	* else a `NODE_ENV` default (`debug` in development, `warn` in test), else `info`.
+	*/
 	getLevel() {
 		var _this$config$levelOpt5;
 		return ((_this$config$levelOpt5 = this.config.levelOptions) === null || _this$config$levelOpt5 === void 0 ? void 0 : _this$config$levelOpt5.level) ?? LogLevel.INFO;
@@ -1475,30 +1514,36 @@ var LogixiaLogger = class LogixiaLogger {
 	getNamespaceLevels() {
 		return { ...this.config.namespaceLevels };
 	}
+	/** Set the context label (e.g. a class or module name) attached to every subsequent entry. */
 	setContext(context) {
 		this.context = typeof context === "string" ? context : safeToString(context);
 	}
+	/** Return the current context label, or `undefined` if none is set. */
 	getContext() {
 		return this.context;
 	}
+	/** Show `fieldName` in log output, overriding the config for this logger instance. */
 	enableField(fieldName) {
 		this.fieldState.set(fieldName, true);
 		this._fieldCache.set(fieldName, true);
 		if (fieldName === "level" || fieldName === "appName") this._buildPerfCaches();
 		internalLog(`Field '${fieldName}' enabled`);
 	}
+	/** Hide `fieldName` from log output, overriding the config for this logger instance. */
 	disableField(fieldName) {
 		this.fieldState.set(fieldName, false);
 		this._fieldCache.set(fieldName, false);
 		if (fieldName === "level" || fieldName === "appName") this._buildPerfCaches();
 		internalLog(`Field '${fieldName}' disabled`);
 	}
+	/** Whether `fieldName` is currently shown: runtime override first, then config, default `true`. */
 	isFieldEnabled(fieldName) {
 		var _this$config$fields2;
 		if (this.fieldState.has(fieldName)) return this.fieldState.get(fieldName);
 		if (((_this$config$fields2 = this.config.fields) === null || _this$config$fields2 === void 0 ? void 0 : _this$config$fields2[fieldName]) !== void 0) return this.config.fields[fieldName] !== false;
 		return true;
 	}
+	/** Return the visibility (`true` = shown) of every standard log field. */
 	getFieldState() {
 		return Object.fromEntries([
 			"timestamp",
@@ -1515,6 +1560,7 @@ var LogixiaLogger = class LogixiaLogger {
 			"environment"
 		].map((f) => [f, this.isFieldEnabled(f)]));
 	}
+	/** Drop all runtime enable/disable overrides so field visibility follows the config again. */
 	resetFieldState() {
 		this.fieldState.clear();
 		internalLog("Field state reset to configuration defaults");
@@ -1529,10 +1575,12 @@ var LogixiaLogger = class LogixiaLogger {
 		if (this.transportManager) this.transportManager.disableLevelPrompting();
 		else internalWarn("Transport manager not initialized");
 	}
+	/** Restrict `transportId` to only the given `levels`. Warns if no transports are configured. */
 	setTransportLevels(transportId, levels) {
 		if (this.transportManager) this.transportManager.setTransportLevels(transportId, levels);
 		else internalWarn("Transport manager not initialized");
 	}
+	/** Return the levels `transportId` is restricted to, or `undefined` if it has none. */
 	getTransportLevels(transportId) {
 		if (this.transportManager) return this.transportManager.getTransportLevels(transportId);
 		internalWarn("Transport manager not initialized");
@@ -1541,10 +1589,23 @@ var LogixiaLogger = class LogixiaLogger {
 		if (this.transportManager) this.transportManager.clearTransportLevelPreferences();
 		else internalWarn("Transport manager not initialized");
 	}
+	/** Return the identifiers of the configured transports (empty if none). */
 	getAvailableTransports() {
 		var _this$transportManage;
 		return ((_this$transportManage = this.transportManager) === null || _this$transportManage === void 0 ? void 0 : _this$transportManage.getTransports()) ?? [];
 	}
+	/**
+	* Create a child logger with its own `context` that shares this logger's
+	* configuration and transports. `data` is merged into the bound fields
+	* inherited from this logger and added to every entry the child writes.
+	* Closing a child does not close the shared transports.
+	*
+	* @example
+	* ```ts
+	* const req = logger.child('Checkout', { requestId: 'r-42' });
+	* await req.info('started'); // entry includes requestId
+	* ```
+	*/
 	child(context, data) {
 		const childLogger = new LogixiaLogger(this.config, context, this);
 		const mergedContextData = {
@@ -1580,9 +1641,11 @@ var LogixiaLogger = class LogixiaLogger {
 		this._pluginRegistry.unregister(pluginName);
 		return this;
 	}
+	/** Flush buffered entries in all transports without closing them. */
 	async flush() {
 		if (this.transportManager) await this.transportManager.flush();
 	}
+	/** Report whether the transports are healthy; `healthy: false` if no transport manager exists. */
 	async healthCheck() {
 		if (!this.transportManager) return {
 			healthy: false,
@@ -1590,6 +1653,20 @@ var LogixiaLogger = class LogixiaLogger {
 		};
 		return this.transportManager.healthCheck();
 	}
+	/**
+	* Warn about timers that were never ended, then flush and close all transports,
+	* stop the sampler and run plugin shutdown hooks. On a child logger only the
+	* timer warnings run; the shared transports stay open.
+	*
+	* To flush on SIGTERM/SIGINT, set the `gracefulShutdown` config option rather
+	* than writing your own signal handler; do not combine it with a manual
+	* handler that calls `process.exit`, which can cut the flush short.
+	*
+	* @example
+	* ```ts
+	* await logger.close(); // e.g. at the end of a script or a test
+	* ```
+	*/
 	async close() {
 		var _this$_sampler;
 		for (const [label, timer] of this.timers) await this.warn(`Timer '${label}' was not ended properly`, {
@@ -1606,11 +1683,13 @@ var LogixiaLogger = class LogixiaLogger {
 	async log(level, message, data) {
 		if (this.config.silent) return;
 		if (!this.shouldLog(level)) return;
-		if (this._sampler) {
-			const traceId$1 = this.config.traceId ? TraceContext.instance.getCurrentTraceId() : void 0;
-			if (!this._sampler.shouldEmit(level, traceId$1)) return;
-		}
 		const alsContext = LogixiaContext.get();
+		let activeTraceId;
+		if (this.config.traceId) {
+			const ctxTraceId = alsContext === null || alsContext === void 0 ? void 0 : alsContext.traceId;
+			activeTraceId = TraceContext.instance.getCurrentTraceId() ?? (typeof ctxTraceId === "string" ? ctxTraceId : void 0);
+		}
+		if (this._sampler && !this._sampler.shouldEmit(level, activeTraceId)) return;
 		const hasAls = alsContext !== void 0 && Object.keys(alsContext).length > 0;
 		const otelFields = _isOtelBridgeEnabled() ? _getOtelPayloadIfEnabled() : void 0;
 		const hasOtel = otelFields !== void 0 && Object.keys(otelFields).length > 0;
@@ -1630,14 +1709,16 @@ var LogixiaLogger = class LogixiaLogger {
 			...mergedData
 		} : mergedData;
 		let payload;
-		if (rawPayload !== void 0 && rawPayload !== null) if (this._hasRedact) try {
-			payload = applyRedaction(rawPayload, this.config.redact) ?? rawPayload;
-		} catch (error) {
-			internalError("Redaction failed", error);
-			payload = { redaction: REDACTION_FAILED };
+		if (rawPayload !== void 0 && rawPayload !== null) {
+			if (this._hasRedact) try {
+				payload = applyRedaction(rawPayload, this.config.redact) ?? rawPayload;
+			} catch (error) {
+				internalError("Redaction failed", error);
+				payload = { redaction: REDACTION_FAILED };
+			}
+			else payload = rawPayload;
 		}
-		else payload = rawPayload;
-		const traceId = this.config.traceId ? TraceContext.instance.getCurrentTraceId() ?? this.fallbackTraceId : void 0;
+		const traceId = this.config.traceId ? activeTraceId ?? this.fallbackTraceId : void 0;
 		let safeMessage = message;
 		if (this._hasRedact) try {
 			safeMessage = applyRedactionToString(message, this.config.redact);
@@ -1675,12 +1756,14 @@ var LogixiaLogger = class LogixiaLogger {
 	* Feature 3: Resolve the effective log level for this logger instance.
 	*
 	* Priority:
+	*  0. A level set at runtime with `setLevel()` (explicit programmatic call, wins over all below)
 	*  1. ENV `LOGIXIA_LEVEL_<NS_UPPER>` (e.g. LOGIXIA_LEVEL_DB for ns "db" or "db.queries")
 	*  2. Matching `namespaceLevels` config entry (longer pattern = more specific, wins)
 	*  3. Global `LOGIXIA_LEVEL` ENV override
 	*  4. `levelOptions.level` (resolved via Feature 5 in constructor)
 	*/
 	resolveEffectiveLevel() {
+		if (this._runtimeLevel) return this._runtimeLevel;
 		const ns = this.context;
 		if (ns) {
 			const nsKey = ns.split(".")[0].toUpperCase();
@@ -1754,6 +1837,22 @@ var LogixiaLogger = class LogixiaLogger {
 		(level === LogLevel.ERROR ? process.stderr : process.stdout).write(this.formatLog(entry) + "\n");
 	}
 };
+/**
+* Create a logger from `config`, with an optional default `context` label.
+*
+* Every key of `levelOptions.levels` that is not already a method becomes an
+* async method on the returned logger, typed through the config, and routes to
+* {@link LogixiaLogger.logLevel}.
+*
+* @example
+* ```ts
+* const logger = createLogger({
+*   appName: 'api',
+*   levelOptions: { level: 'info', levels: { error: 0, warn: 1, info: 2, audit: 2 } },
+* });
+* await logger.audit('user exported data', { userId: 'u1' });
+* ```
+*/
 function createLogger(config, context) {
 	var _config$levelOptions3;
 	const logger = new LogixiaLogger(config, context);
@@ -1765,9 +1864,7 @@ function createLogger(config, context) {
 	}
 	return logger;
 }
-
-//#endregion
-//#region src/exceptions/exception.ts
+// src/exceptions/exception.ts
 var LogixiaException = class extends Error {
 	constructor(options) {
 		super(options.message, { cause: options.cause });
@@ -1798,9 +1895,21 @@ var LogixiaException = class extends Error {
 function isLogixiaException(value) {
 	return value instanceof LogixiaException;
 }
-
-//#endregion
-//#region src/exceptions/builder.ts
+// src/exceptions/builder.ts
+/**
+* ErrorResponseBuilder — turns any exception into a `LogixiaErrorResponse`.
+*
+* Priority order:
+*  1. `LogixiaException`      — typed fields used directly
+*  2. NestJS `HttpException`  — duck-typed; status + message extracted
+*  3. Plain `Error` / unknown — falls back to 500 `server_error`
+*
+* The builder **always** populates `debug` when possible.
+* Your exception filter is responsible for stripping it in production:
+* ```ts
+* if (process.env.NODE_ENV === 'production') delete response.debug;
+* ```
+*/
 /**
 * Generates a trace ID via the shared {@link TraceContext} generator.
 *
@@ -1902,7 +2011,7 @@ var ErrorResponseBuilder = class {
 		const timestamp = (/* @__PURE__ */ new Date()).toISOString();
 		const durationMs = startTime !== void 0 ? Date.now() - startTime : void 0;
 		if (isLogixiaException(exception)) {
-			const debug$1 = buildDebug(exception, service, durationMs, expose);
+			const debug = buildDebug(exception, service, durationMs, expose);
 			const errorBlock = {
 				type: exception.errorType,
 				code: exception.errorCode,
@@ -1921,7 +2030,7 @@ var ErrorResponseBuilder = class {
 						path,
 						status: exception.httpStatus
 					},
-					...debug$1 !== void 0 ? { debug: debug$1 } : {}
+					...debug !== void 0 ? { debug } : {}
 				},
 				httpStatus: exception.httpStatus
 			};
@@ -1937,7 +2046,7 @@ var ErrorResponseBuilder = class {
 			} else message = exception.message;
 			const type = httpStatusToType(status);
 			const code = `HTTP_${status}`;
-			const debug$1 = buildDebug(exception, service, durationMs, expose);
+			const debug = buildDebug(exception, service, durationMs, expose);
 			return {
 				response: {
 					success: false,
@@ -1952,7 +2061,7 @@ var ErrorResponseBuilder = class {
 						path,
 						status
 					},
-					...debug$1 !== void 0 ? { debug: debug$1 } : {}
+					...debug !== void 0 ? { debug } : {}
 				},
 				httpStatus: status
 			};
@@ -1978,7 +2087,6 @@ var ErrorResponseBuilder = class {
 		};
 	}
 };
-
-//#endregion
 export { globalPluginRegistry as C, DEFAULT_LOG_LEVELS as D, DEFAULT_LOG_COLORS as E, LogLevel as O, PluginRegistry as S, DEFAULT_CONFIG as T, getOtelMetaFields as _, isLogixiaException as a, normalizeError as b, _shutdownRegistrySize as c, registerForShutdown as d, resetShutdownHandlers as f, getActiveOtelContext as g, disableOtelBridge as h, LogixiaException as i, deregisterFromShutdown as l, redactObject as m, generateRequestId as n, LogixiaLogger as o, applyRedaction as p, generateTraceId as r, createLogger as s, ErrorResponseBuilder as t, flushOnExit as u, initOtelBridge as v, usePlugin as w, serializeError as x, isError as y };
-//# sourceMappingURL=builder-0gEzRopq.mjs.map
+
+//# sourceMappingURL=builder-D70z6kjj.mjs.map