loggily 0.7.0 → 0.8.0

package/dist/{core-Du3sIje6.mjs → core-B3pox577.mjs}

@@ -1,3 +1,4 @@
+import { createMetricsCollector, withMetrics } from "./metrics.mjs";
 import { closeSync, openSync, writeSync } from "node:fs";
 //#region src/colors.ts
 /**
@@ -90,6 +91,110 @@ function createFileWriter(filePath, options = {}) {
 	};
 }
 //#endregion
+//#region src/tracing.ts
+let currentIdFormat = "simple";
+/**
+* Set the ID format for new spans and traces.
+* - "simple": sp_1, sp_2, tr_1, tr_2 (default, lightweight)
+* - "w3c": 32-char hex trace ID, 16-char hex span ID (W3C Trace Context compatible)
+*
+* @deprecated Use the `TRACE_ID_FORMAT` env var or `{ idFormat: "w3c" }` in the config array instead.
+*/
+function setIdFormat(format) {
+	currentIdFormat = format;
+}
+/**
+* Get the current ID format.
+*
+* @deprecated Use the `TRACE_ID_FORMAT` env var or `{ idFormat: "w3c" }` in the config array instead.
+*/
+function getIdFormat() {
+	return currentIdFormat;
+}
+let simpleSpanCounter = 0;
+let simpleTraceCounter = 0;
+/** Generate a hex string of the given byte length using crypto.randomUUID */
+function randomHex(bytes) {
+	return crypto.randomUUID().replace(/-/g, "").slice(0, bytes * 2);
+}
+/** Generate a span ID according to the current format */
+function generateSpanId() {
+	if (currentIdFormat === "w3c") return randomHex(8);
+	return `sp_${(++simpleSpanCounter).toString(36)}`;
+}
+/** Generate a trace ID according to the current format */
+function generateTraceId() {
+	if (currentIdFormat === "w3c") return randomHex(16);
+	return `tr_${(++simpleTraceCounter).toString(36)}`;
+}
+/** Reset ID counters (for testing) */
+function resetIdCounters() {
+	simpleSpanCounter = 0;
+	simpleTraceCounter = 0;
+}
+/**
+* Format a W3C traceparent header from span data.
+*
+* Format: `{version}-{trace-id}-{span-id}-{trace-flags}`
+* - version: "00" (current W3C spec version)
+* - trace-id: 32 hex chars (128 bits)
+* - span-id: 16 hex chars (64 bits)
+* - trace-flags: "01" (sampled) or "00" (not sampled)
+*
+* Works with both simple and W3C ID formats. Simple IDs are zero-padded to spec length.
+*
+* @param spanData - Span data with id and traceId
+* @param options - Optional settings (sampled flag). Defaults to sampled=true.
+* @returns W3C traceparent header string
+*
+* @example
+* ```typescript
+* const span = log.span("http-request")
+* const header = traceparent(span.spanData)
+* // → "00-a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6-1a2b3c4d5e6f7a8b-01"
+* fetch(url, { headers: { traceparent: header } })
+* ```
+*/
+function traceparent(spanData, options) {
+	return `00-${padHex(spanData.traceId, 32)}-${padHex(spanData.id, 16)}-${options?.sampled ?? true ? "01" : "00"}`;
+}
+/** Pad or hash an ID to the specified hex length */
+function padHex(id, length) {
+	if (id.length === length && /^[0-9a-f]+$/.test(id)) return id;
+	let hex = "";
+	for (let i = 0; i < id.length; i++) hex += id.charCodeAt(i).toString(16).padStart(2, "0");
+	return hex.padStart(length, "0").slice(-length);
+}
+let sampleRate = 1;
+/**
+* Set the head-based sampling rate for new traces.
+* Applied at trace creation — all spans within a sampled trace are kept.
+*
+* @deprecated Use the `TRACE_SAMPLE_RATE` env var or `{ sampleRate: 0.1 }` in the config array instead.
+* @param rate - Sampling rate from 0.0 (sample nothing) to 1.0 (sample everything, default)
+*/
+function setSampleRate(rate) {
+	if (rate < 0 || rate > 1) throw new Error(`Sample rate must be between 0.0 and 1.0, got ${rate}`);
+	sampleRate = rate;
+}
+/**
+* Get the current sampling rate.
+*
+* @deprecated Use the `TRACE_SAMPLE_RATE` env var or `{ sampleRate: 0.1 }` in the config array instead.
+*/
+function getSampleRate() {
+	return sampleRate;
+}
+/**
+* Determine whether a new trace should be sampled.
+* Called at trace creation time (head-based sampling).
+*/
+function shouldSample() {
+	if (sampleRate >= 1) return true;
+	if (sampleRate <= 0) return false;
+	return Math.random() < sampleRate;
+}
+//#endregion
 //#region src/pipeline.ts
 const LOG_LEVEL_PRIORITY = {
 	trace: 0,
@@ -107,16 +212,36 @@ function writeStderr(text) {
 	if (_process?.stderr?.write) _process.stderr.write(text + "\n");
 	else console.error(text);
 }
+/** Serialize Error.cause chains up to a max depth */
+function serializeCause(cause, maxDepth = 3) {
+	if (maxDepth <= 0 || cause === void 0 || cause === null) return void 0;
+	if (cause instanceof Error) {
+		const result = {
+			name: cause.name,
+			message: cause.message,
+			stack: cause.stack
+		};
+		if (cause.code) result.code = cause.code;
+		if (cause.cause !== void 0) result.cause = serializeCause(cause.cause, maxDepth - 1);
+		return result;
+	}
+	return cause;
+}
 function safeStringify(value) {
 	const seen = /* @__PURE__ */ new WeakSet();
 	return JSON.stringify(value, (_key, val) => {
 		if (typeof val === "bigint") return val.toString();
 		if (typeof val === "symbol") return val.toString();
-		if (val instanceof Error) return {
-			message: val.message,
-			stack: val.stack,
-			name: val.name
-		};
+		if (val instanceof Error) {
+			const result = {
+				message: val.message,
+				stack: val.stack,
+				name: val.name
+			};
+			if (val.code) result.code = val.code;
+			if (val.cause !== void 0) result.cause = serializeCause(val.cause);
+			return result;
+		}
 		if (typeof val === "object" && val !== null) {
 			if (seen.has(val)) return "[Circular]";
 			seen.add(val);
@@ -177,6 +302,10 @@ function formatJSONEvent(event) {
 }
 function matchesPattern(namespace, pattern) {
 	if (pattern === "*") return true;
+	if (pattern.endsWith(":*")) {
+		const prefix = pattern.slice(0, -2);
+		return namespace === prefix || namespace.startsWith(prefix + ":");
+	}
 	return namespace === pattern || namespace.startsWith(pattern + ":");
 }
 function parseNsFilter(ns) {
@@ -194,30 +323,39 @@ function parseNsFilter(ns) {
 		return true;
 	};
 }
+/**
+* Write formatted text to console using the appropriate log level.
+*
+* IMPORTANT: We use Function.bind() to preserve caller source locations in
+* browser DevTools. When you click a log line in DevTools, it shows where
+* YOUR code called log.info?.(), not where pipeline.ts called console.info().
+* DO NOT replace bind() with direct console.info(text) calls — it breaks
+* source location tracking in browsers.
+*/
+function writeToConsole(text, event) {
+	if (event.kind === "span") {
+		writeStderr(text);
+		return;
+	}
+	switch (event.level) {
+		case "trace":
+		case "debug":
+			Function.prototype.bind.call(console.debug, console, text)();
+			break;
+		case "info":
+			Function.prototype.bind.call(console.info, console, text)();
+			break;
+		case "warn":
+			Function.prototype.bind.call(console.warn, console, text)();
+			break;
+		case "error":
+			Function.prototype.bind.call(console.error, console, text)();
+			break;
+	}
+}
 function createConsoleSink(format) {
 	const formatter = format === "json" ? formatJSONEvent : formatConsoleEvent;
-	return (event) => {
-		const text = formatter(event);
-		if (event.kind === "span") {
-			writeStderr(text);
-			return;
-		}
-		switch (event.level) {
-			case "trace":
-			case "debug":
-				console.debug(text);
-				break;
-			case "info":
-				console.info(text);
-				break;
-			case "warn":
-				console.warn(text);
-				break;
-			case "error":
-				console.error(text);
-				break;
-		}
-	};
+	return (event) => writeToConsole(formatter(event), event);
 }
 function createFileSink(path, format) {
 	const writer = createFileWriter(path);
@@ -227,14 +365,24 @@ function createFileSink(path, format) {
 		dispose: () => writer.close()
 	};
 }
+function isNodeStream(obj) {
+	return typeof obj === "object" && obj !== null && ("_write" in obj || "writable" in obj || "fd" in obj);
+}
 function createWritableSink(writable, format) {
-	const formatter = format === "json" ? formatJSONEvent : formatConsoleEvent;
-	return (event) => writable.write(formatter(event) + "\n");
+	if (!(writable.objectMode ?? !isNodeStream(writable))) {
+		const formatter = format === "json" ? formatJSONEvent : formatConsoleEvent;
+		return (event) => writable.write(formatter(event) + "\n");
+	}
+	return (event) => writable.write(event);
 }
 const VALID_CONFIG_KEYS = new Set([
 	"level",
 	"ns",
-	"format"
+	"format",
+	"spans",
+	"metrics",
+	"idFormat",
+	"sampleRate"
 ]);
 const SINK_KEYS = new Set(["file", "otel"]);
 function isPojo(obj) {
@@ -243,7 +391,7 @@ function isPojo(obj) {
 	return proto === Object.prototype || proto === null;
 }
 function isWritable(obj) {
-	return typeof obj === "object" && obj !== null && "write" in obj && typeof obj.write === "function" && !isPojo(obj);
+	return typeof obj === "object" && obj !== null && "write" in obj && typeof obj.write === "function";
 }
 function isValidLogLevel(val) {
 	return typeof val === "string" && val in LOG_LEVEL_PRIORITY;
@@ -254,6 +402,7 @@ function buildPipeline(elements, parentConfig) {
 		ns: parentConfig?.ns ?? readEnvNs(),
 		format: parentConfig?.format ?? readEnvFormat()
 	};
+	let spansEnabled = true;
 	const stages = [];
 	const outputs = [];
 	const branches = [];
@@ -265,11 +414,7 @@ function buildPipeline(elements, parentConfig) {
 			disposables.push(() => branch.dispose());
 			continue;
 		}
-		if (typeof element === "function" && element !== console) {
-			stages.push(element);
-			continue;
-		}
-		if (element === console) {
+		if (element === console || element === "console") {
 			outputs.push({
 				levelPriority: LOG_LEVEL_PRIORITY[config.level],
 				nsFilter: config.ns,
@@ -277,6 +422,10 @@ function buildPipeline(elements, parentConfig) {
 			});
 			continue;
 		}
+		if (typeof element === "function") {
+			stages.push(element);
+			continue;
+		}
 		if (isWritable(element)) {
 			outputs.push({
 				levelPriority: LOG_LEVEL_PRIORITY[config.level],
@@ -307,16 +456,30 @@ function buildPipeline(elements, parentConfig) {
 						dispose: sink.dispose
 					});
 				}
+				if (obj.otel !== void 0) throw new Error("loggily: OTEL sink is not yet implemented. See loggily/otel for the planned bridge.");
 				continue;
 			}
 			if (isValidLogLevel(obj.level)) config.level = obj.level;
 			if (obj.ns !== void 0) config.ns = parseNsFilter(obj.ns);
 			if (obj.format === "console" || obj.format === "json") config.format = obj.format;
+			if (obj.spans === true) spansEnabled = true;
+			if (obj.spans === false) spansEnabled = false;
+			if (obj.idFormat === "simple" || obj.idFormat === "w3c") setIdFormat(obj.idFormat);
+			if (typeof obj.sampleRate === "number") setSampleRate(obj.sampleRate);
+			continue;
+		}
+		if (element === "stderr" && typeof process !== "undefined") {
+			outputs.push({
+				levelPriority: LOG_LEVEL_PRIORITY[config.level],
+				nsFilter: config.ns,
+				write: createWritableSink(process.stderr, config.format)
+			});
 			continue;
 		}
-		throw new Error(`loggily: unsupported config element of type "${typeof element}". Config arrays accept: objects (config), arrays (branches), functions (stages), console, or writables ({ write }).`);
+		throw new Error(`loggily: unsupported config element of type "${typeof element}". Config arrays accept: objects (config), arrays (branches), functions (stages), console, "console", or writables ({ write }).`);
 	}
 	const dispatch = (event) => {
+		if (event.kind === "span" && !spansEnabled) return;
 		let e = event;
 		for (const stage of stages) {
 			const result = stage(e);
@@ -338,76 +501,27 @@ function buildPipeline(elements, parentConfig) {
 		}
 	};
 }
-const runtimeState = {
-	suppressConsole: false,
-	writers: []
-};
-function defaultPipeline() {
-	const rt = runtimeState;
-	const disposables = [];
-	let fileSink = null;
-	const logFile = getEnv("LOG_FILE");
-	if (logFile) {
-		const sink = createFileSink(logFile, "json");
-		fileSink = sink.write;
-		disposables.push(sink.dispose);
-	}
-	const dispatch = (event) => {
-		const currentLevel = readEnvLevel();
-		if (event.kind === "log") {
-			if (LOG_LEVEL_PRIORITY[event.level] < LOG_LEVEL_PRIORITY[currentLevel]) return;
-		} else if (event.kind === "span") {
-			const trace = readEnvTrace();
-			if (!trace.enabled) return;
-			if (trace.filter && !trace.filter(event.namespace)) return;
-		}
-		const currentNs = readEnvNs();
-		if (currentNs && !currentNs(event.namespace)) return;
-		const formatter = readEnvFormat() === "json" || getEnv("NODE_ENV") === "production" || getEnv("TRACE_FORMAT") === "json" ? formatJSONEvent : formatConsoleEvent;
-		if (rt.writers.length > 0) {
-			const formatted = formatter(event);
-			const lvl = event.kind === "log" ? event.level : "span";
-			for (const w of rt.writers) w(formatted, lvl);
-		}
-		if (rt.suppressConsole) {
-			fileSink?.(event);
-			return;
-		}
-		const text = formatter(event);
-		if (event.kind === "span") writeStderr(text);
-		else switch (event.level) {
-			case "trace":
-			case "debug":
-				console.debug(text);
-				break;
-			case "info":
-				console.info(text);
-				break;
-			case "warn":
-				console.warn(text);
-				break;
-			case "error":
-				console.error(text);
-				break;
-		}
-		fileSink?.(event);
-	};
-	return {
-		dispatch,
-		get level() {
-			return readEnvLevel();
-		},
-		dispose: () => {
-			for (const d of disposables) d();
-		}
-	};
-}
 function readEnvLevel() {
 	const env = getEnv("LOG_LEVEL")?.toLowerCase();
 	let level = env === "trace" || env === "debug" || env === "info" || env === "warn" || env === "error" || env === "silent" ? env : "info";
 	if (getEnv("DEBUG") && LOG_LEVEL_PRIORITY[level] > LOG_LEVEL_PRIORITY.debug) level = "debug";
 	return level;
 }
+/**
+* Namespace-aware level: only bumps to debug if the namespace matches the DEBUG filter.
+* This enables zero-overhead conditional gating — `log.debug?.()` returns undefined
+* for namespaces outside the DEBUG filter, skipping argument evaluation entirely.
+*/
+function readEnvLevelForNamespace(namespace) {
+	const env = getEnv("LOG_LEVEL")?.toLowerCase();
+	const baseLevel = env === "trace" || env === "debug" || env === "info" || env === "warn" || env === "error" || env === "silent" ? env : "info";
+	if (getEnv("DEBUG") && LOG_LEVEL_PRIORITY[baseLevel] > LOG_LEVEL_PRIORITY.debug) {
+		const nsFilter = readEnvNs();
+		if (nsFilter && nsFilter(namespace)) return "debug";
+		return baseLevel;
+	}
+	return baseLevel;
+}
 function readEnvNs() {
 	const debugEnv = getEnv("DEBUG");
 	if (!debugEnv) return null;
@@ -441,99 +555,6 @@ function readEnvTrace() {
 	};
 }
 //#endregion
-//#region src/tracing.ts
-let currentIdFormat = "simple";
-/**
-* Set the ID format for new spans and traces.
-* - "simple": sp_1, sp_2, tr_1, tr_2 (default, lightweight)
-* - "w3c": 32-char hex trace ID, 16-char hex span ID (W3C Trace Context compatible)
-*/
-function setIdFormat(format) {
-	currentIdFormat = format;
-}
-/** Get the current ID format */
-function getIdFormat() {
-	return currentIdFormat;
-}
-let simpleSpanCounter = 0;
-let simpleTraceCounter = 0;
-/** Generate a hex string of the given byte length using crypto.randomUUID */
-function randomHex(bytes) {
-	return crypto.randomUUID().replace(/-/g, "").slice(0, bytes * 2);
-}
-/** Generate a span ID according to the current format */
-function generateSpanId() {
-	if (currentIdFormat === "w3c") return randomHex(8);
-	return `sp_${(++simpleSpanCounter).toString(36)}`;
-}
-/** Generate a trace ID according to the current format */
-function generateTraceId() {
-	if (currentIdFormat === "w3c") return randomHex(16);
-	return `tr_${(++simpleTraceCounter).toString(36)}`;
-}
-/** Reset ID counters (for testing) */
-function resetIdCounters() {
-	simpleSpanCounter = 0;
-	simpleTraceCounter = 0;
-}
-/**
-* Format a W3C traceparent header from span data.
-*
-* Format: `{version}-{trace-id}-{span-id}-{trace-flags}`
-* - version: "00" (current W3C spec version)
-* - trace-id: 32 hex chars (128 bits)
-* - span-id: 16 hex chars (64 bits)
-* - trace-flags: "01" (sampled) or "00" (not sampled)
-*
-* Works with both simple and W3C ID formats. Simple IDs are zero-padded to spec length.
-*
-* @param spanData - Span data with id and traceId
-* @param options - Optional settings (sampled flag). Defaults to sampled=true.
-* @returns W3C traceparent header string
-*
-* @example
-* ```typescript
-* const span = log.span("http-request")
-* const header = traceparent(span.spanData)
-* // → "00-a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6-1a2b3c4d5e6f7a8b-01"
-* fetch(url, { headers: { traceparent: header } })
-* ```
-*/
-function traceparent(spanData, options) {
-	return `00-${padHex(spanData.traceId, 32)}-${padHex(spanData.id, 16)}-${options?.sampled ?? true ? "01" : "00"}`;
-}
-/** Pad or hash an ID to the specified hex length */
-function padHex(id, length) {
-	if (id.length === length && /^[0-9a-f]+$/.test(id)) return id;
-	let hex = "";
-	for (let i = 0; i < id.length; i++) hex += id.charCodeAt(i).toString(16).padStart(2, "0");
-	return hex.padStart(length, "0").slice(-length);
-}
-let sampleRate = 1;
-/**
-* Set the head-based sampling rate for new traces.
-* Applied at trace creation — all spans within a sampled trace are kept.
-*
-* @param rate - Sampling rate from 0.0 (sample nothing) to 1.0 (sample everything, default)
-*/
-function setSampleRate(rate) {
-	if (rate < 0 || rate > 1) throw new Error(`Sample rate must be between 0.0 and 1.0, got ${rate}`);
-	sampleRate = rate;
-}
-/** Get the current sampling rate */
-function getSampleRate() {
-	return sampleRate;
-}
-/**
-* Determine whether a new trace should be sampled.
-* Called at trace creation time (head-based sampling).
-*/
-function shouldSample() {
-	if (sampleRate >= 1) return true;
-	if (sampleRate <= 0) return false;
-	return Math.random() < sampleRate;
-}
-//#endregion
 //#region src/core.ts
 /**
 * loggily v2 — Structured logging with spans
@@ -552,11 +573,6 @@ function shouldSample() {
 * ])
 * log.info?.('server started', { port: 3000 })
 */
-/** @internal */
-let _ambientRecorder = null;
-function _setAmbientRecorder(recorder) {
-	_ambientRecorder = recorder;
-}
 function resetIds() {
 	resetIdCounters();
 }
@@ -618,30 +634,35 @@ function clearCollectedSpans() {
 function resolveMessage(msg) {
 	return typeof msg === "function" ? msg() : msg;
 }
-function createLoggerImpl(name, props, pipeline, spanMeta, parentSpanId, traceId, traceSampled = true) {
+function createLoggerImpl(name, props, pipeline) {
 	const emitLog = (level, msgOrError, dataOrMsg, extraData) => {
 		let message;
 		let data;
 		if (msgOrError instanceof Error) {
 			const err = msgOrError;
+			const contextTags = _getContextTags?.() ?? {};
 			if (typeof dataOrMsg === "string") {
 				message = dataOrMsg;
 				data = {
+					...contextTags,
 					...props,
 					...extraData,
 					error_type: err.name,
 					error_message: err.message,
 					error_stack: err.stack,
-					error_code: err.code
+					error_code: err.code,
+					error_cause: err.cause !== void 0 ? serializeCause(err.cause) : void 0
 				};
 			} else {
 				message = err.message;
 				data = {
+					...contextTags,
 					...props,
 					...dataOrMsg,
 					error_type: err.name,
 					error_stack: err.stack,
-					error_code: err.code
+					error_code: err.code,
+					error_cause: err.cause !== void 0 ? serializeCause(err.cause) : void 0
 				};
 			}
 		} else {
@@ -669,16 +690,14 @@ function createLoggerImpl(name, props, pipeline, spanMeta, parentSpanId, traceId
 	return {
 		name,
 		props: Object.freeze({ ...props }),
-		get spanData() {
-			if (!spanMeta) return null;
-			return createSpanDataProxy(() => ({
-				id: spanMeta.id,
-				traceId: spanMeta.traceId,
-				parentId: spanMeta.parentId,
-				startTime: spanMeta.startTime,
-				endTime: spanMeta.endTime,
-				duration: spanMeta.endTime !== null ? spanMeta.endTime - spanMeta.startTime : Date.now() - spanMeta.startTime
-			}), spanMeta.attrs);
+		get level() {
+			return pipeline.level;
+		},
+		dispatch(event) {
+			pipeline.dispatch(event);
+		},
+		[Symbol.dispose]() {
+			pipeline.dispose();
 		},
 		trace: (msg, data) => emitLog("trace", msg, data),
 		debug: (msg, data) => emitLog("debug", msg, data),
@@ -686,202 +705,358 @@ function createLoggerImpl(name, props, pipeline, spanMeta, parentSpanId, traceId
 		warn: (msg, data) => emitLog("warn", msg, data),
 		error: (msgOrError, dataOrMsg, extraData) => emitLog("error", msgOrError, dataOrMsg, extraData),
 		logger(namespace, childProps) {
-			return wrapConditional(createLoggerImpl(namespace ? `${name}:${namespace}` : name, {
-				...props,
-				...childProps
-			}, pipeline, null, parentSpanId, traceId, traceSampled), () => pipeline.level);
+			return this.child(namespace ?? "", childProps);
 		},
-		span(namespace, childProps) {
-			const childName = namespace ? `${name}:${namespace}` : name;
-			const resolvedChildProps = typeof childProps === "function" ? childProps() : childProps;
-			const mergedProps = {
-				...props,
-				...resolvedChildProps
-			};
-			const newSpanId = generateSpanId();
-			let resolvedParentId = parentSpanId;
-			let resolvedTraceId = traceId;
-			if (!resolvedParentId && _getContextParent) {
-				const ctxParent = _getContextParent();
-				if (ctxParent) {
-					resolvedParentId = ctxParent.spanId;
-					resolvedTraceId = resolvedTraceId || ctxParent.traceId;
-				}
-			}
-			const isNewTrace = !resolvedTraceId;
-			const finalTraceId = resolvedTraceId || generateTraceId();
-			const sampled = isNewTrace ? shouldSample() : traceSampled;
-			const newSpanData = {
-				id: newSpanId,
-				traceId: finalTraceId,
-				parentId: resolvedParentId,
-				startTime: Date.now(),
-				endTime: null,
-				duration: null,
-				attrs: {}
-			};
-			const spanLogger = createLoggerImpl(childName, mergedProps, pipeline, newSpanData, newSpanId, finalTraceId, sampled);
-			_enterContext?.(newSpanId, finalTraceId, resolvedParentId);
-			spanLogger[Symbol.dispose] = () => {
-				if (newSpanData.endTime !== null) return;
-				newSpanData.endTime = Date.now();
-				newSpanData.duration = newSpanData.endTime - newSpanData.startTime;
-				if (collectSpans) collectedSpans.push(createSpanDataProxy(() => ({
-					id: newSpanData.id,
-					traceId: newSpanData.traceId,
-					parentId: newSpanData.parentId,
-					startTime: newSpanData.startTime,
-					endTime: newSpanData.endTime,
-					duration: newSpanData.duration
-				}), { ...newSpanData.attrs }));
-				_exitContext?.(newSpanId);
-				_ambientRecorder?.recordSpan({
-					name: childName,
-					durationMs: newSpanData.duration
-				});
-				if (sampled) {
-					const spanEvent = {
-						kind: "span",
-						time: newSpanData.endTime,
-						namespace: childName,
-						name: childName,
-						duration: newSpanData.duration,
-						props: {
-							...mergedProps,
-							...newSpanData.attrs
-						},
-						spanId: newSpanData.id,
-						traceId: newSpanData.traceId,
-						parentId: newSpanData.parentId
-					};
-					pipeline.dispatch(spanEvent);
-				}
-			};
-			return spanLogger;
+		span(_namespace, _childProps) {
+			throw new Error("loggily: span() requires the withSpans() plugin. Use pipe(baseCreateLogger, withSpans()) or the default createLogger.");
 		},
-		child(context) {
-			if (typeof context === "string") return this.logger(context);
+		child(namespaceOrContext, childProps) {
+			if (typeof namespaceOrContext === "string") return wrapConditional(createLoggerImpl(namespaceOrContext ? `${name}:${namespaceOrContext}` : name, {
+				...props,
+				...childProps
+			}, pipeline), () => pipeline.level);
 			return wrapConditional(createLoggerImpl(name, {
 				...props,
-				...context
-			}, pipeline, null, parentSpanId, traceId, traceSampled), () => pipeline.level);
+				...namespaceOrContext
+			}, pipeline), () => pipeline.level);
 		},
-		end() {
-			if (spanMeta?.endTime === null) this[Symbol.dispose]?.();
-		}
+		end() {}
 	};
 }
 function wrapConditional(logger, getLevel) {
 	return new Proxy(logger, { get(target, prop) {
-		if (prop in LOG_LEVEL_PRIORITY && prop !== "silent") {
+		if (typeof prop === "string" && prop in LOG_LEVEL_PRIORITY && prop !== "silent") {
 			if (LOG_LEVEL_PRIORITY[prop] < LOG_LEVEL_PRIORITY[getLevel()]) return;
 		}
+		if (prop === "span") {
+			const val = target[prop];
+			if (val === baseSpanStub) return void 0;
+			return val;
+		}
 		return target[prop];
 	} });
 }
+const baseSpanStub = function baseSpanStub(_namespace, _childProps) {
+	throw new Error("loggily: span() requires the withSpans() plugin. Use pipe(baseCreateLogger, withSpans()) or the default createLogger.");
+};
 /**
-* Create a logger.
-*
-* @param name - Logger namespace (e.g., 'myapp', 'myapp:db')
-* @param config - Optional config array. Objects configure, arrays branch, values write.
-*
-* @example
-* // Zero config (reads LOG_LEVEL, DEBUG, LOG_FORMAT from env)
-* const log = createLogger('myapp')
-*
-* @example
-* // Configured pipeline
-* const log = createLogger('myapp', [
-*   { level: 'debug', ns: '-sql' },
-*   console,
-*   { file: '/tmp/app.log', level: 'info', format: 'json' },
-* ])
+* Plugin: adds span creation capability to loggers.
+* Without this plugin, `.span` is undefined on ConditionalLogger.
+* Included by default in `createLogger`.
 */
-function createLogger(name, config) {
-	const pipeline = config ? buildPipeline(config) : defaultPipeline();
-	return wrapConditional(createLoggerImpl(name, {}, pipeline, null, null, null), () => pipeline.level);
+function withSpans() {
+	return (factory, _ctx) => {
+		return (name, configOrProps) => {
+			return augmentWithSpans(factory(name, configOrProps), null, null, true);
+		};
+	};
+}
+function augmentWithSpans(logger, parentSpanId, traceId, traceSampled) {
+	const spanState = {
+		parentSpanId,
+		traceId,
+		traceSampled
+	};
+	return new Proxy(logger, { get(target, prop) {
+		if (prop === "span") return createSpanMethod(target, spanState);
+		if (prop === "child") return function child(namespaceOrContext, childProps) {
+			return augmentWithSpans(target.child(namespaceOrContext, childProps), spanState.parentSpanId, spanState.traceId, spanState.traceSampled);
+		};
+		if (prop === "logger") return function logger(namespace, childProps) {
+			return augmentWithSpans(target.logger(namespace, childProps), spanState.parentSpanId, spanState.traceId, spanState.traceSampled);
+		};
+		return target[prop];
+	} });
+}
+function createSpanMethod(logger, spanState) {
+	return (namespace, childProps) => {
+		const childName = namespace ? `${logger.name}:${namespace}` : logger.name;
+		const resolvedChildProps = typeof childProps === "function" ? childProps() : childProps;
+		const mergedProps = {
+			...logger.props,
+			...resolvedChildProps
+		};
+		const newSpanId = generateSpanId();
+		let resolvedParentId = spanState.parentSpanId;
+		let resolvedTraceId = spanState.traceId;
+		if (!resolvedParentId && _getContextParent) {
+			const ctxParent = _getContextParent();
+			if (ctxParent) {
+				resolvedParentId = ctxParent.spanId;
+				resolvedTraceId = resolvedTraceId || ctxParent.traceId;
+			}
+		}
+		const isNewTrace = !resolvedTraceId;
+		const finalTraceId = resolvedTraceId || generateTraceId();
+		const sampled = isNewTrace ? shouldSample() : spanState.traceSampled;
+		const newSpanData = {
+			id: newSpanId,
+			traceId: finalTraceId,
+			parentId: resolvedParentId,
+			startTime: Date.now(),
+			endTime: null,
+			duration: null,
+			attrs: {}
+		};
+		const spanAugmented = augmentWithSpans(logger.child(namespace ?? "", resolvedChildProps), newSpanId, finalTraceId, sampled);
+		_enterContext?.(newSpanId, finalTraceId, resolvedParentId);
+		const disposeSpan = () => {
+			if (newSpanData.endTime !== null) return;
+			newSpanData.endTime = Date.now();
+			newSpanData.duration = newSpanData.endTime - newSpanData.startTime;
+			if (collectSpans) collectedSpans.push(createSpanDataProxy(() => ({
+				id: newSpanData.id,
+				traceId: newSpanData.traceId,
+				parentId: newSpanData.parentId,
+				startTime: newSpanData.startTime,
+				endTime: newSpanData.endTime,
+				duration: newSpanData.duration
+			}), { ...newSpanData.attrs }));
+			_exitContext?.(newSpanId);
+			if (sampled) {
+				const spanEvent = {
+					kind: "span",
+					time: newSpanData.endTime,
+					namespace: childName,
+					name: childName,
+					duration: newSpanData.duration,
+					props: {
+						...mergedProps,
+						...newSpanData.attrs
+					},
+					spanId: newSpanData.id,
+					traceId: newSpanData.traceId,
+					parentId: newSpanData.parentId
+				};
+				logger.dispatch(spanEvent);
+			}
+		};
+		const spanDataProxy = createSpanDataProxy(() => ({
+			id: newSpanData.id,
+			traceId: newSpanData.traceId,
+			parentId: newSpanData.parentId,
+			startTime: newSpanData.startTime,
+			endTime: newSpanData.endTime,
+			duration: newSpanData.endTime !== null ? newSpanData.endTime - newSpanData.startTime : Date.now() - newSpanData.startTime
+		}), newSpanData.attrs);
+		let currentDispose = disposeSpan;
+		return new Proxy(spanAugmented, {
+			get(target, prop) {
+				if (prop === "spanData") return spanDataProxy;
+				if (prop === Symbol.dispose) return currentDispose;
+				if (prop === "end") return () => {
+					if (newSpanData.endTime === null) currentDispose();
+				};
+				if (prop === "name") return childName;
+				if (prop === "props") return Object.freeze({ ...mergedProps });
+				return target[prop];
+			},
+			set(_target, prop, value) {
+				if (prop === Symbol.dispose) {
+					currentDispose = value;
+					return true;
+				}
+				return false;
+			}
+		});
+	};
 }
 /**
-* Compose a custom createLogger with plugins.
+* Base createLogger — requires a config array.
+* Use the default `createLogger` export (with `withEnvDefaults`) for zero-config.
 *
-* @example
-* import { createLogger as base, compose } from "loggily"
-* import withSentry from "@sentry/loggily"
-*
-* const createLogger = compose(base, withSentry({ dsn: "..." }))
-* const log = createLogger("myapp")
+* Note: loggers from baseCreateLogger do NOT have `.span()` capability.
+* Use `pipe(baseCreateLogger, withSpans())` or the default `createLogger` for spans.
 */
-function compose(base, ...plugins) {
-	return plugins.reduce((factory, plugin) => plugin(factory), base);
+function baseCreateLogger(name, configOrProps) {
+	let pipeline;
+	let props = {};
+	if (Array.isArray(configOrProps)) pipeline = buildPipeline(configOrProps);
+	else if (configOrProps && typeof configOrProps === "object") {
+		props = configOrProps;
+		pipeline = buildPipeline(["console"]);
+	} else pipeline = buildPipeline(["console"]);
+	const logger = createLoggerImpl(name, props, pipeline);
+	logger.span = baseSpanStub;
+	return wrapConditional(logger, () => pipeline.level);
+}
+function pipe(base, ...plugins) {
+	const ctx = {};
+	return plugins.reduce((factory, plugin) => plugin(factory, ctx), base);
 }
 const _env = (typeof process !== "undefined" ? process : void 0)?.env ?? {};
-/** @deprecated Use createLogger config array: createLogger("x", [{ level }, console]) */
+function currentLevel() {
+	return readEnvLevel();
+}
+function currentNs() {
+	return readEnvNs();
+}
+function currentFormat() {
+	return readEnvFormat();
+}
+function currentTrace() {
+	return readEnvTrace();
+}
+const _writers = [];
+let _suppressConsole = false;
+let _logFileWriterFactory = null;
+/** @internal */
+function _setLogFileWriterFactory(factory) {
+	_logFileWriterFactory = factory;
+}
+/**
+* Plugin: read defaults from environment variables (LOG_LEVEL, DEBUG, LOG_FORMAT, TRACE, LOG_FILE).
+* Included by default. Omit to disable env-var behavior entirely.
+*
+* When no config array is given, provides console output + env-var-based config.
+* When a config array IS given, env vars are already used as defaults by buildPipeline.
+* Legacy setters (setLogLevel, addWriter, etc.) affect loggers created without explicit config.
+*/
+function withEnvDefaults() {
+	return (factory, _ctx) => (name, configOrProps) => {
+		const envIdFormat = _env.TRACE_ID_FORMAT?.toLowerCase();
+		if (envIdFormat === "simple" || envIdFormat === "w3c") setIdFormat(envIdFormat);
+		const envSampleRate = _env.TRACE_SAMPLE_RATE;
+		if (envSampleRate !== void 0) {
+			const rate = Number.parseFloat(envSampleRate);
+			if (!Number.isNaN(rate) && rate >= 0 && rate <= 1) setSampleRate(rate);
+		}
+		if (Array.isArray(configOrProps)) return factory(name, configOrProps);
+		const envPipeline = createEnvPipeline();
+		const envStage = (event) => {
+			envPipeline.dispatch(event);
+			return null;
+		};
+		if (configOrProps && typeof configOrProps === "object") return applyNamespaceGating(factory(name, [{ level: "trace" }, envStage]).child(configOrProps));
+		return applyNamespaceGating(factory(name, [{ level: "trace" }, envStage]));
+	};
+}
+/**
+* Wrap a logger so that conditional method gating is namespace-aware.
+* When DEBUG=myapp:db, only loggers whose namespace matches get debug enabled.
+* Without this, all loggers get debug because readEnvLevel() bumps globally.
+*/
+function applyNamespaceGating(logger) {
+	return new Proxy(logger, { get(target, prop) {
+		if (typeof prop === "string" && prop in LOG_LEVEL_PRIORITY && prop !== "silent") {
+			const nsLevel = readEnvLevelForNamespace(target.name);
+			if (LOG_LEVEL_PRIORITY[prop] < LOG_LEVEL_PRIORITY[nsLevel]) return;
+		}
+		return target[prop];
+	} });
+}
+function createEnvPipeline() {
+	const disposables = [];
+	const logFile = _env.LOG_FILE;
+	let fileSink = null;
+	if (logFile && _logFileWriterFactory) {
+		const writer = _logFileWriterFactory(logFile);
+		fileSink = (event) => {
+			const fmt = currentFormat() === "json" ? formatJSONEvent : formatConsoleEvent;
+			writer.write(fmt(event));
+		};
+		disposables.push(() => writer.close());
+	}
+	const dispatch = (event) => {
+		if (event.kind === "log" && LOG_LEVEL_PRIORITY[event.level] < LOG_LEVEL_PRIORITY[currentLevel()]) return;
+		if (event.kind === "span") {
+			const trace = currentTrace();
+			if (!trace.enabled) return;
+			if (trace.filter && !trace.filter(event.namespace)) return;
+		}
+		const ns = currentNs();
+		if (ns && !ns(event.namespace)) return;
+		const text = (currentFormat() === "json" ? formatJSONEvent : formatConsoleEvent)(event);
+		const lvl = event.kind === "log" ? event.level : "span";
+		for (const w of _writers) w(text, lvl);
+		if (!_suppressConsole) writeToConsole(text, event);
+		fileSink?.(event);
+	};
+	return {
+		dispatch,
+		get level() {
+			return currentLevel();
+		},
+		dispose: () => {
+			for (const d of disposables) d();
+		}
+	};
+}
+/**
+* Plugin: when `{ metrics: true }` appears in the config array, automatically
+* creates a MetricsCollector and applies withMetrics to the logger.
+* The collector is accessible via `logger.metrics`.
+*/
+function withConfigMetrics() {
+	return (factory, _ctx) => {
+		return (name, configOrProps) => {
+			const logger = factory(name, configOrProps);
+			if (!Array.isArray(configOrProps)) return logger;
+			if (!configOrProps.some((el) => typeof el === "object" && el !== null && !Array.isArray(el) && "metrics" in el && el.metrics === true)) return logger;
+			return withMetrics(createMetricsCollector())(logger);
+		};
+	};
+}
+/** Default createLogger — includes withEnvDefaults + withSpans + withConfigMetrics. */
+const createLogger = pipe(baseCreateLogger, withEnvDefaults(), withSpans(), withConfigMetrics());
+/** Test helper — all levels, console output. */
+function createTestLogger(name) {
+	return pipe(baseCreateLogger, withSpans())(name, [{ level: "trace" }, "console"]);
+}
+/** @deprecated Use config array */
 function setLogLevel(level) {
 	_env.LOG_LEVEL = level;
 }
-/** @deprecated Level is per-logger in v2 */
 function getLogLevel() {
-	return _env.LOG_LEVEL ?? "info";
+	return currentLevel();
 }
-/** @deprecated Use TRACE=1 env var */
 function enableSpans() {
 	_env.TRACE = "1";
 }
-/** @deprecated */
 function disableSpans() {
 	delete _env.TRACE;
 }
-/** @deprecated */
 function spansAreEnabled() {
 	return !!_env.TRACE;
 }
-/** @deprecated Use TRACE=namespace env var */
 function setTraceFilter(namespaces) {
 	if (!namespaces || namespaces.length === 0) delete _env.TRACE;
 	else _env.TRACE = namespaces.join(",");
 }
-/** @deprecated */
 function getTraceFilter() {
 	return _env.TRACE ? _env.TRACE.split(",") : null;
 }
-/** @deprecated Use DEBUG=namespace env var or { ns } in config array */
 function setDebugFilter(namespaces) {
 	if (!namespaces || namespaces.length === 0) delete _env.DEBUG;
 	else _env.DEBUG = namespaces.join(",");
 }
-/** @deprecated */
 function getDebugFilter() {
 	return _env.DEBUG ? _env.DEBUG.split(",") : null;
 }
-/** @deprecated Use { format } in config array */
 function setLogFormat(format) {
 	_env.LOG_FORMAT = format;
 }
-/** @deprecated */
 function getLogFormat() {
-	return _env.LOG_FORMAT ?? "console";
+	return currentFormat();
 }
-/** @deprecated Omit console from config array instead */
 function setSuppressConsole(value) {
-	runtimeState.suppressConsole = value;
+	_suppressConsole = value;
+}
+function setOutputMode(_mode) {
+	throw new Error("loggily: setOutputMode() is removed in v2. Use config arrays: omit console from array for writers-only, use \"stderr\" for stderr mode.");
 }
-/** @deprecated Use config array */
-function setOutputMode(_mode) {}
-/** @deprecated */
 function getOutputMode() {
 	return "console";
 }
-/** @deprecated Pass writers in config array instead */
 function addWriter(writer) {
-	runtimeState.writers.push(writer);
+	_writers.push(writer);
 	return () => {
-		const idx = runtimeState.writers.indexOf(writer);
-		if (idx !== -1) runtimeState.writers.splice(idx, 1);
+		const i = _writers.indexOf(writer);
+		if (i !== -1) _writers.splice(i, 1);
 	};
 }
-/** @deprecated Spans dispatch through the pipeline automatically */
 function writeSpan(namespace, duration, attrs) {
-	const event = {
+	createEnvPipeline().dispatch({
 		kind: "span",
 		time: Date.now(),
 		namespace,
@@ -891,10 +1066,9 @@ function writeSpan(namespace, duration, attrs) {
 		spanId: attrs.span_id ?? "",
 		traceId: attrs.trace_id ?? "",
 		parentId: attrs.parent_id ?? null
-	};
-	defaultPipeline().dispatch(event);
+	});
 }
 //#endregion
-export { getSampleRate as A, setSuppressConsole as C, stopCollecting as D, startCollecting as E, buildPipeline as F, defaultPipeline as I, safeStringify as L, setSampleRate as M, traceparent as N, writeSpan as O, LOG_LEVEL_PRIORITY as P, createFileWriter as R, setOutputMode as S, spansAreEnabled as T, getTraceFilter as _, addWriter as a, setLogFormat as b, createLogger as c, enableSpans as d, getCollectedSpans as f, getOutputMode as g, getLogLevel as h, _setContextHooks as i, setIdFormat as j, getIdFormat as k, createSpanDataProxy as l, getLogFormat as m, _clearContextHooks as n, clearCollectedSpans as o, getDebugFilter as p, _setAmbientRecorder as r, compose as s, _ambientRecorder as t, disableSpans as u, resetIds as v, setTraceFilter as w, setLogLevel as x, setDebugFilter as y };
+export { withEnvDefaults as A, setSampleRate as B, setOutputMode as C, startCollecting as D, spansAreEnabled as E, safeStringify as F, createFileWriter as H, serializeCause as I, getIdFormat as L, writeSpan as M, LOG_LEVEL_PRIORITY as N, stopCollecting as O, buildPipeline as P, getSampleRate as R, setLogLevel as S, setTraceFilter as T, traceparent as V, getTraceFilter as _, baseCreateLogger as a, setDebugFilter as b, createSpanDataProxy as c, enableSpans as d, getCollectedSpans as f, getOutputMode as g, getLogLevel as h, addWriter as i, withSpans as j, withConfigMetrics as k, createTestLogger as l, getLogFormat as m, _setContextHooks as n, clearCollectedSpans as o, getDebugFilter as p, _setLogFileWriterFactory as r, createLogger as s, _clearContextHooks as t, disableSpans as u, pipe as v, setSuppressConsole as w, setLogFormat as x, resetIds as y, setIdFormat as z };
 
-//# sourceMappingURL=core-Du3sIje6.mjs.map
+//# sourceMappingURL=core-B3pox577.mjs.map