@loglayer/mixin-wide-events 1.0.0 → 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Theo Gravity / [Disaresta](https://disaresta.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.cjs

@@ -1,5 +1,4 @@
-Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
-
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 //#region ../../core/plugin/dist/index.js
 /**
 * List of plugin callbacks that can be called by the plugin manager.
@@ -20,17 +19,7 @@ let PluginCallbackType = /* @__PURE__ */ function(PluginCallbackType) {
 	PluginCallbackType["onContextCalled"] = "onContextCalled";
 	return PluginCallbackType;
 }({});
-
-//#endregion
-//#region ../../core/loglayer/dist/index.js
-const CALLBACK_LIST = [
-	PluginCallbackType.onBeforeDataOut,
-	PluginCallbackType.onMetadataCalled,
-	PluginCallbackType.onBeforeMessageOut,
-	PluginCallbackType.transformLogLevel,
-	PluginCallbackType.shouldSendToLogger,
-	PluginCallbackType.onContextCalled
-];
+PluginCallbackType.onBeforeDataOut, PluginCallbackType.onMetadataCalled, PluginCallbackType.onBeforeMessageOut, PluginCallbackType.transformLogLevel, PluginCallbackType.shouldSendToLogger, PluginCallbackType.onContextCalled;
 /**
 * The class that the mixin extends
 */
@@ -45,10 +34,48 @@ let LogLayerMixinAugmentType = /* @__PURE__ */ function(LogLayerMixinAugmentType
 	LogLayerMixinAugmentType["LogLayer"] = "LogLayer";
 	return LogLayerMixinAugmentType;
 }({});
-
 //#endregion
 //#region src/mixin.ts
 /**
+* Log levels that default to rate=1 (error/fatal) — can be overridden via `perLevel` or callback.
+*/
+const EXEMPT_LEVELS = new Set(["error", "fatal"]);
+/**
+* Normalize a boolean or numeric rate to a number in [0, 1].
+* `true` becomes 1, `false` becomes 0, numbers are clamped to [0, 1].
+* `NaN`, `Infinity`, and `-Infinity` are treated as 0 (drop all).
+*/
+function toRate(value) {
+	if (value === void 0) return 1;
+	if (typeof value === "boolean") return value ? 1 : 0;
+	if (typeof value !== "number" || !Number.isFinite(value)) return 0;
+	return Math.max(0, Math.min(1, value));
+}
+/**
+* Run rate-based sampling (default or per_level strategy).
+* Returns true if the rate check passes, false if dropped.
+* Returns true for error/fatal by default, unless their rate is explicitly set in `perLevel`.
+*/
+function runRateSampling(level, strategy, rate, perLevel) {
+	if (EXEMPT_LEVELS.has(level) && perLevel?.[level] === void 0) return true;
+	if (strategy === "per_level" && perLevel) {
+		const perRate = toRate(perLevel[level]);
+		if (perLevel[level] === void 0) {
+			const r = toRate(rate);
+			if (r === 1) return true;
+			if (r === 0) return false;
+			return Math.random() < r;
+		}
+		if (perRate === 1) return true;
+		if (perRate === 0) return false;
+		return Math.random() < perRate;
+	}
+	const r = toRate(rate);
+	if (r === 1) return true;
+	if (r === 0) return false;
+	return Math.random() < r;
+}
+/**
 * Creates a LogLayer mixin that adds wide event logging functionality.
 *
 * Wide events are comprehensive, self-contained log entries that capture an entire
@@ -60,7 +87,6 @@ let LogLayerMixinAugmentType = /* @__PURE__ */ function(LogLayerMixinAugmentType
 *   wide event data across async boundaries. For Node.js, use `new AsyncLocalStorage()`
 *   from `async_hooks`. For browser environments, provide your own compatible implementation.
 * @param options.includeContext - Whether to include withContext() data in emitted wide events (default: true)
-
 *
 * @returns A LogLayer mixin registration object
 *
@@ -95,6 +121,29 @@ function createWideEventMixin(options) {
 	const asyncContext = options.asyncContext;
 	const includeContext = options.includeContext ?? true;
 	const wideEventField = options.wideEventField;
+	const errorsAsArray = options.errorsAsArray ?? false;
+	const errorField = options.errorField ?? (errorsAsArray ? "errors" : "error");
+	const snapshotPerLevel = options.sampling?.perLevel ? { ...options.sampling.perLevel } : void 0;
+	const samplingConfig = options.sampling ? {
+		strategy: options.sampling.strategy ?? "default",
+		rate: options.sampling.rate,
+		perLevel: snapshotPerLevel,
+		emitLevel: options.sampling.emitLevel,
+		shouldEmit: options.sampling.shouldEmit
+	} : void 0;
+	function defaultErrorSerializer(err) {
+		if (err instanceof Error) return {
+			name: err.name,
+			message: err.message,
+			stack: err.stack
+		};
+		return { message: String(err) };
+	}
+	function getErrorSerializer(self) {
+		const config = self.getConfig?.();
+		if (config?.errorSerializer) return config.errorSerializer;
+		return defaultErrorSerializer;
+	}
 	/**
 	* Context tracker plugin - stores context in async storage
 	* for inclusion in wide events (only if includeContext is true)
@@ -160,18 +209,40 @@ function createWideEventMixin(options) {
 		return self;
 	}
 	/**
+	* Implementation for withWideEventError
+	*/
+	function withWideEventErrorImpl(error, self) {
+		const store = asyncContext.getStore();
+		if (store) {
+			const serializedError = getErrorSerializer(self)(error);
+			if (errorsAsArray) {
+				if (!store._llWideEvents) store._llWideEvents = {};
+				if (!store._llWideEvents[errorField]) store._llWideEvents[errorField] = [];
+				store._llWideEvents[errorField].push(serializedError);
+			} else withWideEventsImpl({ [errorField]: serializedError }, self);
+		}
+		return self;
+	}
+	/**
 	* Implementation for emitWideEvent
 	*/
 	function emitWideEventImpl(config, self) {
+		const defaultLevel = samplingConfig?.emitLevel ?? "info";
+		const level = config.level ?? defaultLevel;
+		if (samplingConfig && !samplingConfig.shouldEmit && !runRateSampling(level, samplingConfig.strategy, samplingConfig.rate, samplingConfig.perLevel)) return;
 		const store = asyncContext.getStore();
 		const wideEventData = {};
 		if (includeContext && store?._llContext) Object.assign(wideEventData, store._llContext);
 		if (store?._llWideEvents) Object.assign(wideEventData, store._llWideEvents);
-		if (config.metadata) Object.assign(wideEventData, config.metadata);
-		const level = config.level ?? "info";
+		if (samplingConfig?.shouldEmit) try {
+			const callbackOk = samplingConfig.shouldEmit({
+				wideData: wideEventData,
+				level
+			});
+			if (!runRateSampling(level, samplingConfig.strategy, samplingConfig.rate, samplingConfig.perLevel) || !callbackOk) return;
+		} catch {}
 		const metadataToEmit = wideEventField ? { [wideEventField]: wideEventData } : wideEventData;
 		self.withMetadata(metadataToEmit)[level](config.message);
-		return self;
 	}
 	return {
 		mixinsToAdd: [{
@@ -189,6 +260,9 @@ function createWideEventMixin(options) {
 				prototype.emitWideEvent = function(config) {
 					return emitWideEventImpl(config, this);
 				};
+				prototype.withWideEventError = function(error) {
+					return withWideEventErrorImpl(error, this);
+				};
 			},
 			augmentMock: (prototype) => {
 				prototype.withWideEvents = function(data) {
@@ -203,11 +277,13 @@ function createWideEventMixin(options) {
 				prototype.emitWideEvent = function(config) {
 					return emitWideEventImpl(config, this);
 				};
+				prototype.withWideEventError = function(error) {
+					return withWideEventErrorImpl(error, this);
+				};
 			}
 		}],
 		pluginsToAdd: [contextTrackerPlugin]
 	};
 }
-
 //#endregion
-exports.createWideEventMixin = createWideEventMixin;
+exports.createWideEventMixin = createWideEventMixin;

package/dist/index.d.cts

@@ -2060,6 +2060,121 @@ declare class LogBuilder implements ILogBuilder<LogBuilder, boolean> {
  */
 //#endregion
 //#region src/types.d.ts
+/**
+ * Parameters passed to a custom `shouldEmit` sampling callback.
+ * Provides the accumulated wide event data and the log level so the
+ * callback can make an informed keep/drop decision.
+ */
+interface WideEventSamplingParams {
+  /**
+   * The accumulated wide event data (wide events + optional context).
+   * Contains the merged data that would be emitted if kept.
+   */
+  wideData: Record<string, any>;
+  /**
+   * The log level that would be used for the emission.
+   */
+  level: LogLevelType;
+}
+/**
+ * Sampling strategy for wide events.
+ *
+ * - `"default"` — a single `rate` applies to all non-error/fatal levels.
+ * - `"per_level"` — per-level rates keyed by LogLevelType; levels not in the
+ *   map use `rate` as a fallback.
+ */
+type WideEventSamplingStrategy = "default" | "per_level";
+/**
+ * Configuration for sampling wide event emissions.
+ *
+ * "error" and "fatal" levels default to a 100% keep rate, but can be
+ * overridden by setting `perLevel` rates or via `shouldEmit`.
+ */
+interface WideEventSamplingConfig {
+  /**
+   * The sampling strategy.
+   *
+   * - `"default"` — a single `rate` applies to all non-error/fatal levels.
+   * - `"per_level"` — per-level rates from the `perLevel` map; levels not in
+   *   the map use `rate` as a fallback.
+   *
+   * @default "default"
+   */
+  strategy?: WideEventSamplingStrategy;
+  /**
+   * A rate between 0 and 1 that determines the fraction of events to keep.
+   *
+   * - `1` (or `true`) — keep 100% (sampling disabled)
+   * - `0.1` — ~10% of events kept
+   * - `0` (or `false`) — keep 0% (all dropped for sample-able levels)
+   *
+   * With `"default"` strategy this rate applies to all non-error/fatal levels.
+   * With `"per_level"` strategy this field is **ignored** — unmapped levels
+   * default to a 100% keep rate.
+   *
+   * @default 1
+   */
+  rate?: boolean | number;
+  /**
+   * Per-level sampling rates when strategy is `"per_level"`.
+   * Keys are log level strings (e.g. `"trace"`, `"info"`, `"warn"`).
+   * Levels not listed use `rate` as a fallback.
+   *
+   * **Important:** "error" and "fatal" default to a 100% keep rate, but can be
+   * explicitly overridden by setting their rate in `perLevel` or using a
+   * `shouldEmit` callback.
+   *
+   * The map is snapshotted at construction time; mutating it afterward has
+   * no effect.
+   *
+   * @example
+   * ```ts
+   * {
+   *   strategy: "per_level",
+   *   perLevel: {
+   *     trace: 0.1,
+   *     debug: 0.3,
+   *     info: 0.5,
+   *   },
+   * }
+   * // warn, error, fatal are all 100%
+   * ```
+   */
+  perLevel?: Partial<Record<LogLevelType, boolean | number>>;
+  /**
+   * A custom sampling callback that receives the wide event data and log
+   * level, allowing you to make an informed keep/drop decision.
+   *
+   * When provided, this callback is invoked **in addition to** the built-in
+   * rate-based sampling. An event is only kept when **both** the built-in
+   * check passes (if `rate`/`perLevel` are configured) **and** the callback
+   * returns `true`. If only `shouldEmit` is set (no `rate`), the callback
+   * acts as the sole gate.
+   *
+   * **Note:** "error" and "fatal" default to a 100% keep rate, but can be
+   * overridden by returning `false` from this callback.
+   *
+   * @example
+   * ```ts
+   * {
+   *   shouldEmit: ({ wideData, level }) => {
+   *     // Only emit wide events that have a userId
+   *     return !!wideData.userId;
+   *   },
+   * }
+   * ```
+   */
+  shouldEmit?: (params: WideEventSamplingParams) => boolean;
+  /**
+   * Override the default log level when no explicit `level` is passed to
+   * `emitWideEvent()`. When set, the resolved level uses this value instead
+   * of `"info"`. This **does** affect sampling decisions — with `per_level`
+   * strategy, the level from `emitLevel` determines which rate bucket applies.
+   *
+   * @default undefined (falls back to `"info"`)
+   */
+  emitLevel?: LogLevelType;
+}
 /**
  * Configuration options for creating a wide event mixin.
  */
@@ -2089,6 +2204,34 @@ interface WideEventMixinOptions {
    * { "userId": "123", "orderId": "456", "msg": "done" }
    */
   wideEventField?: string;
+  /**
+   * Optional: Field name to use for error data in wide events.
+   * @default "error" (single mode) or "errors" (array mode)
+   */
+  errorField?: string;
+  /**
+   * Optional: When true, errors are collected as an array.
+   * Each call to withWideEventError() appends to the array.
+   * When false, each call replaces the previous error.
+   * @default false
+   */
+  errorsAsArray?: boolean;
+  /**
+   * Optional: Sampling configuration for wide events.
+   * When provided, the mixin will randomly decide whether to emit or skip wide
+   * events based on the configured rate(s).
+   *
+   * "error" and "fatal" default to a 100% keep rate, but can be overridden
+   * via `perLevel` rates or the `shouldEmit` callback.
+   *
+   * @example
+   * // Keep ~10% of wide events (excluding errors/fatals)
+   * { sampling: { strategy: "default", rate: 0.1 } }
+   *
+   * // Per-level: keep all trace/debug, but sample info at 5%
+   * { sampling: { strategy: "per_level", perLevel: { info: 0.05 } } }
+   */
+  sampling?: WideEventSamplingConfig;
 }
 /**
  * Configuration for emitting a wide event.
@@ -2102,11 +2245,6 @@ interface EmitWideEventConfig {
    * Optional: Log level (defaults to "info").
    */
   level?: LogLevelType;
-  /**
-   * Optional: Additional metadata to include in this specific emission.
-   * This is merged with the accumulated wide event data.
-   */
-  metadata?: Record<string, any>;
 }
 /**
  * Interface for wide event mixin functionality.
@@ -2183,22 +2321,41 @@ interface IWideEventMixin {
    * and logs at the specified level.
    *
    * @param config - Configuration for the wide event emission
-   * @returns This logger instance for chaining
    *
    * @example
    * ```typescript
    * // Emit as info log
    * logger.emitWideEvent({ message: "Order processed" });
    *
-   * // Emit as error with additional metadata
+   * // Emit as error
    * logger.emitWideEvent({
    *   message: "Order failed",
    *   level: "error",
-   *   metadata: { reason: "payment_declined" }
    * });
    * ```
    */
-  emitWideEvent(config: EmitWideEventConfig): this;
+  emitWideEvent(config: EmitWideEventConfig): void;
+  /**
+   * Captures an error for inclusion in the wide event.
+   * Serializes the error using the configured errorSerializer (or default).
+   *
+   * @param error - The error to capture
+   * @returns This logger instance for chaining
+   *
+   * @example
+   * ```typescript
+   * try {
+   *   await doSomething();
+   * } catch (err) {
+   *   // For single error (replaces previous)
+   *   logger.withWideEventError(err);
+   *
+   *   // With errorsAsArray: true - errors accumulate
+   *   logger.withWideEventError(err).withWideEventError(otherErr);
+   * }
+   * ```
+   */
+  withWideEventError(error: any): this;
 }
 declare module "loglayer" {
   interface LogLayer extends IWideEventMixin {}
@@ -2224,7 +2381,6 @@ declare module "@loglayer/shared" {
  *   wide event data across async boundaries. For Node.js, use `new AsyncLocalStorage()`
  *   from `async_hooks`. For browser environments, provide your own compatible implementation.
  * @param options.includeContext - Whether to include withContext() data in emitted wide events (default: true)
-
  *
  * @returns A LogLayer mixin registration object
  *
@@ -2257,4 +2413,4 @@ declare module "@loglayer/shared" {
  */
 declare function createWideEventMixin(options: WideEventMixinOptions): LogLayerMixinRegistration;
 //#endregion
-export { type EmitWideEventConfig, type IWideEventMixin, type WideEventMixinOptions, createWideEventMixin };
+export { type EmitWideEventConfig, type IWideEventMixin, type WideEventMixinOptions, type WideEventSamplingConfig, type WideEventSamplingParams, type WideEventSamplingStrategy, createWideEventMixin };

package/dist/index.d.mts

@@ -2060,6 +2060,121 @@ declare class LogBuilder implements ILogBuilder<LogBuilder, boolean> {
  */
 //#endregion
 //#region src/types.d.ts
+/**
+ * Parameters passed to a custom `shouldEmit` sampling callback.
+ * Provides the accumulated wide event data and the log level so the
+ * callback can make an informed keep/drop decision.
+ */
+interface WideEventSamplingParams {
+  /**
+   * The accumulated wide event data (wide events + optional context).
+   * Contains the merged data that would be emitted if kept.
+   */
+  wideData: Record<string, any>;
+  /**
+   * The log level that would be used for the emission.
+   */
+  level: LogLevelType;
+}
+/**
+ * Sampling strategy for wide events.
+ *
+ * - `"default"` — a single `rate` applies to all non-error/fatal levels.
+ * - `"per_level"` — per-level rates keyed by LogLevelType; levels not in the
+ *   map use `rate` as a fallback.
+ */
+type WideEventSamplingStrategy = "default" | "per_level";
+/**
+ * Configuration for sampling wide event emissions.
+ *
+ * "error" and "fatal" levels default to a 100% keep rate, but can be
+ * overridden by setting `perLevel` rates or via `shouldEmit`.
+ */
+interface WideEventSamplingConfig {
+  /**
+   * The sampling strategy.
+   *
+   * - `"default"` — a single `rate` applies to all non-error/fatal levels.
+   * - `"per_level"` — per-level rates from the `perLevel` map; levels not in
+   *   the map use `rate` as a fallback.
+   *
+   * @default "default"
+   */
+  strategy?: WideEventSamplingStrategy;
+  /**
+   * A rate between 0 and 1 that determines the fraction of events to keep.
+   *
+   * - `1` (or `true`) — keep 100% (sampling disabled)
+   * - `0.1` — ~10% of events kept
+   * - `0` (or `false`) — keep 0% (all dropped for sample-able levels)
+   *
+   * With `"default"` strategy this rate applies to all non-error/fatal levels.
+   * With `"per_level"` strategy this field is **ignored** — unmapped levels
+   * default to a 100% keep rate.
+   *
+   * @default 1
+   */
+  rate?: boolean | number;
+  /**
+   * Per-level sampling rates when strategy is `"per_level"`.
+   * Keys are log level strings (e.g. `"trace"`, `"info"`, `"warn"`).
+   * Levels not listed use `rate` as a fallback.
+   *
+   * **Important:** "error" and "fatal" default to a 100% keep rate, but can be
+   * explicitly overridden by setting their rate in `perLevel` or using a
+   * `shouldEmit` callback.
+   *
+   * The map is snapshotted at construction time; mutating it afterward has
+   * no effect.
+   *
+   * @example
+   * ```ts
+   * {
+   *   strategy: "per_level",
+   *   perLevel: {
+   *     trace: 0.1,
+   *     debug: 0.3,
+   *     info: 0.5,
+   *   },
+   * }
+   * // warn, error, fatal are all 100%
+   * ```
+   */
+  perLevel?: Partial<Record<LogLevelType, boolean | number>>;
+  /**
+   * A custom sampling callback that receives the wide event data and log
+   * level, allowing you to make an informed keep/drop decision.
+   *
+   * When provided, this callback is invoked **in addition to** the built-in
+   * rate-based sampling. An event is only kept when **both** the built-in
+   * check passes (if `rate`/`perLevel` are configured) **and** the callback
+   * returns `true`. If only `shouldEmit` is set (no `rate`), the callback
+   * acts as the sole gate.
+   *
+   * **Note:** "error" and "fatal" default to a 100% keep rate, but can be
+   * overridden by returning `false` from this callback.
+   *
+   * @example
+   * ```ts
+   * {
+   *   shouldEmit: ({ wideData, level }) => {
+   *     // Only emit wide events that have a userId
+   *     return !!wideData.userId;
+   *   },
+   * }
+   * ```
+   */
+  shouldEmit?: (params: WideEventSamplingParams) => boolean;
+  /**
+   * Override the default log level when no explicit `level` is passed to
+   * `emitWideEvent()`. When set, the resolved level uses this value instead
+   * of `"info"`. This **does** affect sampling decisions — with `per_level`
+   * strategy, the level from `emitLevel` determines which rate bucket applies.
+   *
+   * @default undefined (falls back to `"info"`)
+   */
+  emitLevel?: LogLevelType;
+}
 /**
  * Configuration options for creating a wide event mixin.
  */
@@ -2089,6 +2204,34 @@ interface WideEventMixinOptions {
    * { "userId": "123", "orderId": "456", "msg": "done" }
    */
   wideEventField?: string;
+  /**
+   * Optional: Field name to use for error data in wide events.
+   * @default "error" (single mode) or "errors" (array mode)
+   */
+  errorField?: string;
+  /**
+   * Optional: When true, errors are collected as an array.
+   * Each call to withWideEventError() appends to the array.
+   * When false, each call replaces the previous error.
+   * @default false
+   */
+  errorsAsArray?: boolean;
+  /**
+   * Optional: Sampling configuration for wide events.
+   * When provided, the mixin will randomly decide whether to emit or skip wide
+   * events based on the configured rate(s).
+   *
+   * "error" and "fatal" default to a 100% keep rate, but can be overridden
+   * via `perLevel` rates or the `shouldEmit` callback.
+   *
+   * @example
+   * // Keep ~10% of wide events (excluding errors/fatals)
+   * { sampling: { strategy: "default", rate: 0.1 } }
+   *
+   * // Per-level: keep all trace/debug, but sample info at 5%
+   * { sampling: { strategy: "per_level", perLevel: { info: 0.05 } } }
+   */
+  sampling?: WideEventSamplingConfig;
 }
 /**
  * Configuration for emitting a wide event.
@@ -2102,11 +2245,6 @@ interface EmitWideEventConfig {
    * Optional: Log level (defaults to "info").
    */
   level?: LogLevelType;
-  /**
-   * Optional: Additional metadata to include in this specific emission.
-   * This is merged with the accumulated wide event data.
-   */
-  metadata?: Record<string, any>;
 }
 /**
  * Interface for wide event mixin functionality.
@@ -2183,22 +2321,41 @@ interface IWideEventMixin {
    * and logs at the specified level.
    *
    * @param config - Configuration for the wide event emission
-   * @returns This logger instance for chaining
    *
    * @example
    * ```typescript
    * // Emit as info log
    * logger.emitWideEvent({ message: "Order processed" });
    *
-   * // Emit as error with additional metadata
+   * // Emit as error
    * logger.emitWideEvent({
    *   message: "Order failed",
    *   level: "error",
-   *   metadata: { reason: "payment_declined" }
    * });
    * ```
    */
-  emitWideEvent(config: EmitWideEventConfig): this;
+  emitWideEvent(config: EmitWideEventConfig): void;
+  /**
+   * Captures an error for inclusion in the wide event.
+   * Serializes the error using the configured errorSerializer (or default).
+   *
+   * @param error - The error to capture
+   * @returns This logger instance for chaining
+   *
+   * @example
+   * ```typescript
+   * try {
+   *   await doSomething();
+   * } catch (err) {
+   *   // For single error (replaces previous)
+   *   logger.withWideEventError(err);
+   *
+   *   // With errorsAsArray: true - errors accumulate
+   *   logger.withWideEventError(err).withWideEventError(otherErr);
+   * }
+   * ```
+   */
+  withWideEventError(error: any): this;
 }
 declare module "loglayer" {
   interface LogLayer extends IWideEventMixin {}
@@ -2224,7 +2381,6 @@ declare module "@loglayer/shared" {
  *   wide event data across async boundaries. For Node.js, use `new AsyncLocalStorage()`
  *   from `async_hooks`. For browser environments, provide your own compatible implementation.
  * @param options.includeContext - Whether to include withContext() data in emitted wide events (default: true)
-
  *
  * @returns A LogLayer mixin registration object
  *
@@ -2257,4 +2413,4 @@ declare module "@loglayer/shared" {
  */
 declare function createWideEventMixin(options: WideEventMixinOptions): LogLayerMixinRegistration;
 //#endregion
-export { type EmitWideEventConfig, type IWideEventMixin, type WideEventMixinOptions, createWideEventMixin };
+export { type EmitWideEventConfig, type IWideEventMixin, type WideEventMixinOptions, type WideEventSamplingConfig, type WideEventSamplingParams, type WideEventSamplingStrategy, createWideEventMixin };

package/dist/index.mjs

@@ -18,17 +18,7 @@ let PluginCallbackType = /* @__PURE__ */ function(PluginCallbackType) {
 	PluginCallbackType["onContextCalled"] = "onContextCalled";
 	return PluginCallbackType;
 }({});
-
-//#endregion
-//#region ../../core/loglayer/dist/index.js
-const CALLBACK_LIST = [
-	PluginCallbackType.onBeforeDataOut,
-	PluginCallbackType.onMetadataCalled,
-	PluginCallbackType.onBeforeMessageOut,
-	PluginCallbackType.transformLogLevel,
-	PluginCallbackType.shouldSendToLogger,
-	PluginCallbackType.onContextCalled
-];
+PluginCallbackType.onBeforeDataOut, PluginCallbackType.onMetadataCalled, PluginCallbackType.onBeforeMessageOut, PluginCallbackType.transformLogLevel, PluginCallbackType.shouldSendToLogger, PluginCallbackType.onContextCalled;
 /**
 * The class that the mixin extends
 */
@@ -43,10 +33,48 @@ let LogLayerMixinAugmentType = /* @__PURE__ */ function(LogLayerMixinAugmentType
 	LogLayerMixinAugmentType["LogLayer"] = "LogLayer";
 	return LogLayerMixinAugmentType;
 }({});
-
 //#endregion
 //#region src/mixin.ts
 /**
+* Log levels that default to rate=1 (error/fatal) — can be overridden via `perLevel` or callback.
+*/
+const EXEMPT_LEVELS = new Set(["error", "fatal"]);
+/**
+* Normalize a boolean or numeric rate to a number in [0, 1].
+* `true` becomes 1, `false` becomes 0, numbers are clamped to [0, 1].
+* `NaN`, `Infinity`, and `-Infinity` are treated as 0 (drop all).
+*/
+function toRate(value) {
+	if (value === void 0) return 1;
+	if (typeof value === "boolean") return value ? 1 : 0;
+	if (typeof value !== "number" || !Number.isFinite(value)) return 0;
+	return Math.max(0, Math.min(1, value));
+}
+/**
+* Run rate-based sampling (default or per_level strategy).
+* Returns true if the rate check passes, false if dropped.
+* Returns true for error/fatal by default, unless their rate is explicitly set in `perLevel`.
+*/
+function runRateSampling(level, strategy, rate, perLevel) {
+	if (EXEMPT_LEVELS.has(level) && perLevel?.[level] === void 0) return true;
+	if (strategy === "per_level" && perLevel) {
+		const perRate = toRate(perLevel[level]);
+		if (perLevel[level] === void 0) {
+			const r = toRate(rate);
+			if (r === 1) return true;
+			if (r === 0) return false;
+			return Math.random() < r;
+		}
+		if (perRate === 1) return true;
+		if (perRate === 0) return false;
+		return Math.random() < perRate;
+	}
+	const r = toRate(rate);
+	if (r === 1) return true;
+	if (r === 0) return false;
+	return Math.random() < r;
+}
+/**
 * Creates a LogLayer mixin that adds wide event logging functionality.
 *
 * Wide events are comprehensive, self-contained log entries that capture an entire
@@ -58,7 +86,6 @@ let LogLayerMixinAugmentType = /* @__PURE__ */ function(LogLayerMixinAugmentType
 *   wide event data across async boundaries. For Node.js, use `new AsyncLocalStorage()`
 *   from `async_hooks`. For browser environments, provide your own compatible implementation.
 * @param options.includeContext - Whether to include withContext() data in emitted wide events (default: true)
-
 *
 * @returns A LogLayer mixin registration object
 *
@@ -93,6 +120,29 @@ function createWideEventMixin(options) {
 	const asyncContext = options.asyncContext;
 	const includeContext = options.includeContext ?? true;
 	const wideEventField = options.wideEventField;
+	const errorsAsArray = options.errorsAsArray ?? false;
+	const errorField = options.errorField ?? (errorsAsArray ? "errors" : "error");
+	const snapshotPerLevel = options.sampling?.perLevel ? { ...options.sampling.perLevel } : void 0;
+	const samplingConfig = options.sampling ? {
+		strategy: options.sampling.strategy ?? "default",
+		rate: options.sampling.rate,
+		perLevel: snapshotPerLevel,
+		emitLevel: options.sampling.emitLevel,
+		shouldEmit: options.sampling.shouldEmit
+	} : void 0;
+	function defaultErrorSerializer(err) {
+		if (err instanceof Error) return {
+			name: err.name,
+			message: err.message,
+			stack: err.stack
+		};
+		return { message: String(err) };
+	}
+	function getErrorSerializer(self) {
+		const config = self.getConfig?.();
+		if (config?.errorSerializer) return config.errorSerializer;
+		return defaultErrorSerializer;
+	}
 	/**
 	* Context tracker plugin - stores context in async storage
 	* for inclusion in wide events (only if includeContext is true)
@@ -158,18 +208,40 @@ function createWideEventMixin(options) {
 		return self;
 	}
 	/**
+	* Implementation for withWideEventError
+	*/
+	function withWideEventErrorImpl(error, self) {
+		const store = asyncContext.getStore();
+		if (store) {
+			const serializedError = getErrorSerializer(self)(error);
+			if (errorsAsArray) {
+				if (!store._llWideEvents) store._llWideEvents = {};
+				if (!store._llWideEvents[errorField]) store._llWideEvents[errorField] = [];
+				store._llWideEvents[errorField].push(serializedError);
+			} else withWideEventsImpl({ [errorField]: serializedError }, self);
+		}
+		return self;
+	}
+	/**
 	* Implementation for emitWideEvent
 	*/
 	function emitWideEventImpl(config, self) {
+		const defaultLevel = samplingConfig?.emitLevel ?? "info";
+		const level = config.level ?? defaultLevel;
+		if (samplingConfig && !samplingConfig.shouldEmit && !runRateSampling(level, samplingConfig.strategy, samplingConfig.rate, samplingConfig.perLevel)) return;
 		const store = asyncContext.getStore();
 		const wideEventData = {};
 		if (includeContext && store?._llContext) Object.assign(wideEventData, store._llContext);
 		if (store?._llWideEvents) Object.assign(wideEventData, store._llWideEvents);
-		if (config.metadata) Object.assign(wideEventData, config.metadata);
-		const level = config.level ?? "info";
+		if (samplingConfig?.shouldEmit) try {
+			const callbackOk = samplingConfig.shouldEmit({
+				wideData: wideEventData,
+				level
+			});
+			if (!runRateSampling(level, samplingConfig.strategy, samplingConfig.rate, samplingConfig.perLevel) || !callbackOk) return;
+		} catch {}
 		const metadataToEmit = wideEventField ? { [wideEventField]: wideEventData } : wideEventData;
 		self.withMetadata(metadataToEmit)[level](config.message);
-		return self;
 	}
 	return {
 		mixinsToAdd: [{
@@ -187,6 +259,9 @@ function createWideEventMixin(options) {
 				prototype.emitWideEvent = function(config) {
 					return emitWideEventImpl(config, this);
 				};
+				prototype.withWideEventError = function(error) {
+					return withWideEventErrorImpl(error, this);
+				};
 			},
 			augmentMock: (prototype) => {
 				prototype.withWideEvents = function(data) {
@@ -201,11 +276,13 @@ function createWideEventMixin(options) {
 				prototype.emitWideEvent = function(config) {
 					return emitWideEventImpl(config, this);
 				};
+				prototype.withWideEventError = function(error) {
+					return withWideEventErrorImpl(error, this);
+				};
 			}
 		}],
 		pluginsToAdd: [contextTrackerPlugin]
 	};
 }
-
 //#endregion
-export { createWideEventMixin };
+export { createWideEventMixin };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@loglayer/mixin-wide-events",
   "description": "Adds wide event logging functionality to LogLayer for comprehensive, self-contained log entries.",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",
@@ -32,22 +32,14 @@
     "wide-events",
     "canonical-log-lines"
   ],
-  "scripts": {
-    "build": "tsdown src/index.ts",
-    "test": "vitest --run",
-    "clean": "rm -rf .turbo node_modules dist",
-    "lint": "biome check --no-errors-on-unmatched --write --unsafe src",
-    "lint:staged": "biome check --no-errors-on-unmatched --write --unsafe --staged src",
-    "verify-types": "tsc --noEmit"
-  },
   "devDependencies": {
-    "@internal/tsconfig": "workspace:*",
-    "@loglayer/shared": "workspace:*",
-    "@types/node": "25.2.3",
-    "loglayer": "workspace:*",
-    "tsdown": "0.20.3",
-    "typescript": "5.9.3",
-    "vitest": "4.0.18"
+    "@types/node": "25.9.1",
+    "tsdown": "0.22.0",
+    "typescript": "6.0.3",
+    "vitest": "4.1.7",
+    "@loglayer/shared": "4.2.0",
+    "loglayer": "9.2.0",
+    "@internal/tsconfig": "2.1.0"
   },
   "peerDependencies": {},
   "bugs": "https://github.com/loglayer/loglayer/issues",
@@ -55,5 +47,12 @@
     "dist"
   ],
   "homepage": "https://loglayer.dev",
-  "packageManager": "pnpm@10.20.0"
-}
+  "scripts": {
+    "build": "tsdown src/index.ts",
+    "test": "vitest --run",
+    "clean": "rm -rf .turbo node_modules dist",
+    "lint": "biome check --no-errors-on-unmatched --write --unsafe src",
+    "lint:staged": "biome check --no-errors-on-unmatched --write --unsafe --staged src",
+    "verify-types": "tsc --noEmit"
+  }
+}