@loglayer/mixin-wide-events 1.0.1 → 1.1.1

package/README.md

@@ -1,9 +1,19 @@
-# @loglayer/mixin-wide-events
+# wide-events mixin for LogLayer
 
-[![npm version](https://img.shields.io/npm/v/@loglayer/mixin-wide-events.svg)](https://www.npmjs.com/package/@loglayer/mixin-wide-events)
-[![npm downloads](https://img.shields.io/npm/dm/@loglayer/mixin-wide-events.svg)](https://www.npmjs.com/package/@loglayer/mixin-wide-events)
+[![NPM Version](https://img.shields.io/npm/v/%40loglayer%2Fmixin-wide-events)](https://www.npmjs.com/package/@loglayer/mixin-wide-events)
+[![NPM Downloads](https://img.shields.io/npm/dm/%40loglayer%2Fmixin-wide-events)](https://www.npmjs.com/package/@loglayer/mixin-wide-events)
 [![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074c1.svg)](http://www.typescriptlang.org/)
 
-Adds wide event logging functionality to LogLayer for comprehensive, self-contained log entries.
+Adds wide event logging functionality to the [LogLayer](https://loglayer.dev) logging library, enabling comprehensive, self-contained log entries that capture an entire operation's context using Node.js `AsyncLocalStorage`.
 
-[Documentation](https://loglayer.dev/mixins/wide-events) | [API Reference](https://loglayer.dev/mixins/wide-events)
+The mixin provides methods to accumulate data across async boundaries and emit it as a single log entry, along with built-in sampling support.
+
+## Installation
+
+```bash
+npm install loglayer @loglayer/mixin-wide-events
+```
+
+## Documentation
+
+For more details, visit [https://loglayer.dev/mixins/wide-events](https://loglayer.dev/mixins/wide-events).

package/dist/index.cjs

@@ -37,6 +37,45 @@ let LogLayerMixinAugmentType = /* @__PURE__ */ function(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
@@ -48,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
 *
@@ -85,6 +123,14 @@ function createWideEventMixin(options) {
 	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,
@@ -181,11 +227,20 @@ function createWideEventMixin(options) {
 	* 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);
-		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);
 	}

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.
  */
@@ -2101,6 +2216,22 @@ interface WideEventMixinOptions {
    * @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.
@@ -2250,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
  *
@@ -2283,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.
  */
@@ -2101,6 +2216,22 @@ interface WideEventMixinOptions {
    * @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.
@@ -2250,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
  *
@@ -2283,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

@@ -36,6 +36,45 @@ let LogLayerMixinAugmentType = /* @__PURE__ */ function(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
@@ -47,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
 *
@@ -84,6 +122,14 @@ function createWideEventMixin(options) {
 	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,
@@ -180,11 +226,20 @@ function createWideEventMixin(options) {
 	* 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);
-		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);
 	}

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.1",
+  "version": "1.1.1",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",
@@ -37,8 +37,8 @@
     "tsdown": "0.22.0",
     "typescript": "6.0.3",
     "vitest": "4.1.7",
-    "@loglayer/shared": "4.2.0",
     "@internal/tsconfig": "2.1.0",
+    "@loglayer/shared": "4.2.0",
     "loglayer": "9.2.0"
   },
   "peerDependencies": {},