evlog 1.0.1 → 1.1.0

package/README.md

@@ -94,7 +94,6 @@ export default defineNuxtConfig({
   evlog: {
     env: {
       service: 'my-app',
-      environment: process.env.NODE_ENV,
     },
     // Optional: only log specific routes (supports glob patterns)
     include: ['/api/**'],
@@ -102,6 +101,17 @@ export default defineNuxtConfig({
 })
 ```
 
+> **Tip:** Use `$production` to enable [sampling](#sampling) only in production:
+> ```typescript
+> export default defineNuxtConfig({
+>   modules: ['evlog/nuxt'],
+>   evlog: { env: { service: 'my-app' } },
+>   $production: {
+>     evlog: { sampling: { rates: { info: 10, warn: 50, debug: 0 } } },
+>   },
+> })
+> ```
+
 That's it. Now use `useLogger(event)` in any API route:
 
 ```typescript
@@ -353,6 +363,77 @@ initLogger({
   },
   pretty?: boolean       // Pretty print (default: true in dev)
   include?: string[]     // Route patterns to log (glob), e.g. ['/api/**']
+  sampling?: {
+    rates?: {            // Head sampling (random per level)
+      info?: number      // 0-100, default 100
+      warn?: number      // 0-100, default 100
+      debug?: number     // 0-100, default 100
+      error?: number     // 0-100, default 100 (always logged unless set to 0)
+    }
+    keep?: Array<{       // Tail sampling (force keep based on outcome)
+      status?: number    // Keep if status >= value
+      duration?: number  // Keep if duration >= value (ms)
+      path?: string      // Keep if path matches glob pattern
+    }>
+  }
+})
+```
+
+### Sampling
+
+At scale, logging everything can become expensive. evlog supports two sampling strategies:
+
+#### Head Sampling (rates)
+
+Random sampling based on log level, decided before the request completes:
+
+```typescript
+initLogger({
+  sampling: {
+    rates: {
+      info: 10,   // Keep 10% of info logs
+      warn: 50,   // Keep 50% of warning logs
+      debug: 0,   // Disable debug logs
+      // error defaults to 100% (always logged)
+    },
+  },
+})
+```
+
+#### Tail Sampling (keep)
+
+Force-keep logs based on request outcome, evaluated after the request completes. Useful to always capture slow requests or critical paths:
+
+```typescript
+// nuxt.config.ts
+export default defineNuxtConfig({
+  modules: ['evlog/nuxt'],
+  evlog: {
+    sampling: {
+      rates: { info: 10 },  // Only 10% of info logs
+      keep: [
+        { duration: 1000 },           // Always keep if duration >= 1000ms
+        { status: 400 },              // Always keep if status >= 400
+        { path: '/api/critical/**' }, // Always keep critical paths
+      ],
+    },
+  },
+})
+```
+
+#### Custom Tail Sampling Hook
+
+For business-specific conditions (premium users, feature flags), use the `evlog:emit:keep` Nitro hook:
+
+```typescript
+// server/plugins/evlog-custom.ts
+export default defineNitroPlugin((nitroApp) => {
+  nitroApp.hooks.hook('evlog:emit:keep', (ctx) => {
+    // Always keep logs for premium users
+    if (ctx.context.user?.premium) {
+      ctx.shouldKeep = true
+    }
+  })
 })
 ```
 

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 export { EvlogError, createError, createEvlogError } from './error.mjs';
-export { createRequestLogger, getEnvironment, initLogger, log } from './logger.mjs';
+export { createRequestLogger, getEnvironment, initLogger, log, shouldKeep } from './logger.mjs';
 export { useLogger } from './runtime/server/useLogger.mjs';
 export { parseError } from './runtime/utils/parseError.mjs';
-export { BaseWideEvent, EnvironmentContext, ErrorOptions, H3EventContext, Log, LogLevel, LoggerConfig, ParsedError, RequestLogger, RequestLoggerOptions, ServerEvent, WideEvent } from './types.mjs';
+export { BaseWideEvent, DrainContext, EnvironmentContext, ErrorOptions, H3EventContext, Log, LogLevel, LoggerConfig, ParsedError, RequestLogger, RequestLoggerOptions, SamplingConfig, SamplingRates, ServerEvent, TailSamplingCondition, TailSamplingContext, WideEvent } from './types.mjs';

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { EvlogError, createError, createEvlogError } from './error.js';
-export { createRequestLogger, getEnvironment, initLogger, log } from './logger.js';
+export { createRequestLogger, getEnvironment, initLogger, log, shouldKeep } from './logger.js';
 export { useLogger } from './runtime/server/useLogger.js';
 export { parseError } from './runtime/utils/parseError.js';
-export { BaseWideEvent, EnvironmentContext, ErrorOptions, H3EventContext, Log, LogLevel, LoggerConfig, ParsedError, RequestLogger, RequestLoggerOptions, ServerEvent, WideEvent } from './types.js';
+export { BaseWideEvent, DrainContext, EnvironmentContext, ErrorOptions, H3EventContext, Log, LogLevel, LoggerConfig, ParsedError, RequestLogger, RequestLoggerOptions, SamplingConfig, SamplingRates, ServerEvent, TailSamplingCondition, TailSamplingContext, WideEvent } from './types.js';

package/dist/index.mjs

@@ -1,5 +1,5 @@
 export { EvlogError, createError, createEvlogError } from './error.mjs';
-export { createRequestLogger, getEnvironment, initLogger, log } from './logger.mjs';
+export { createRequestLogger, getEnvironment, initLogger, log, shouldKeep } from './logger.mjs';
 export { useLogger } from './runtime/server/useLogger.mjs';
 export { parseError } from './runtime/utils/parseError.mjs';
 import './utils.mjs';

package/dist/logger.d.mts

@@ -1,10 +1,15 @@
-import { RequestLoggerOptions, RequestLogger, EnvironmentContext, LoggerConfig, Log } from './types.mjs';
+import { RequestLoggerOptions, RequestLogger, EnvironmentContext, LoggerConfig, Log, TailSamplingContext } from './types.mjs';
 
 /**
  * Initialize the logger with configuration.
  * Call this once at application startup.
  */
 declare function initLogger(config?: LoggerConfig): void;
+/**
+ * Evaluate tail sampling conditions to determine if a log should be force-kept.
+ * Returns true if ANY condition matches (OR logic).
+ */
+declare function shouldKeep(ctx: TailSamplingContext): boolean;
 /**
  * Simple logging API - as easy as console.log
  *
@@ -32,4 +37,4 @@ declare function createRequestLogger(options?: RequestLoggerOptions): RequestLog
  */
 declare function getEnvironment(): EnvironmentContext;
 
-export { createRequestLogger, getEnvironment, initLogger, log };
+export { createRequestLogger, getEnvironment, initLogger, log, shouldKeep };

package/dist/logger.d.ts

@@ -1,10 +1,15 @@
-import { RequestLoggerOptions, RequestLogger, EnvironmentContext, LoggerConfig, Log } from './types.js';
+import { RequestLoggerOptions, RequestLogger, EnvironmentContext, LoggerConfig, Log, TailSamplingContext } from './types.js';
 
 /**
  * Initialize the logger with configuration.
  * Call this once at application startup.
  */
 declare function initLogger(config?: LoggerConfig): void;
+/**
+ * Evaluate tail sampling conditions to determine if a log should be force-kept.
+ * Returns true if ANY condition matches (OR logic).
+ */
+declare function shouldKeep(ctx: TailSamplingContext): boolean;
 /**
  * Simple logging API - as easy as console.log
  *
@@ -32,4 +37,4 @@ declare function createRequestLogger(options?: RequestLoggerOptions): RequestLog
  */
 declare function getEnvironment(): EnvironmentContext;
 
-export { createRequestLogger, getEnvironment, initLogger, log };
+export { createRequestLogger, getEnvironment, initLogger, log, shouldKeep };

package/dist/logger.mjs

@@ -1,10 +1,11 @@
-import { isDev, detectEnvironment, formatDuration, getConsoleMethod, colors, getLevelColor } from './utils.mjs';
+import { isDev, detectEnvironment, formatDuration, matchesPattern, getConsoleMethod, colors, getLevelColor } from './utils.mjs';
 
 let globalEnv = {
   service: "app",
   environment: "development"
 };
 let globalPretty = isDev();
+let globalSampling = {};
 function initLogger(config = {}) {
   const detected = detectEnvironment();
   globalEnv = {
@@ -15,8 +16,38 @@ function initLogger(config = {}) {
     region: config.env?.region ?? detected.region
   };
   globalPretty = config.pretty ?? isDev();
+  globalSampling = config.sampling ?? {};
 }
-function emitWideEvent(level, event) {
+function shouldSample(level) {
+  const { rates } = globalSampling;
+  if (!rates) {
+    return true;
+  }
+  const percentage = level === "error" && rates.error === void 0 ? 100 : rates[level] ?? 100;
+  if (percentage <= 0) return false;
+  if (percentage >= 100) return true;
+  return Math.random() * 100 < percentage;
+}
+function shouldKeep(ctx) {
+  const { keep } = globalSampling;
+  if (!keep?.length) return false;
+  return keep.some((condition) => {
+    if (condition.status !== void 0 && ctx.status !== void 0 && ctx.status >= condition.status) {
+      return true;
+    }
+    if (condition.duration !== void 0 && ctx.duration !== void 0 && ctx.duration >= condition.duration) {
+      return true;
+    }
+    if (condition.path && ctx.path && matchesPattern(ctx.path, condition.path)) {
+      return true;
+    }
+    return false;
+  });
+}
+function emitWideEvent(level, event, skipSamplingCheck = false) {
+  if (!skipSamplingCheck && !shouldSample(level)) {
+    return null;
+  }
   const formatted = {
     timestamp: (/* @__PURE__ */ new Date()).toISOString(),
     level,
@@ -28,9 +59,13 @@ function emitWideEvent(level, event) {
   } else {
     console[getConsoleMethod(level)](JSON.stringify(formatted));
   }
+  return formatted;
 }
 function emitTaggedLog(level, tag, message) {
   if (globalPretty) {
+    if (!shouldSample(level)) {
+      return;
+    }
     const color = getLevelColor(level);
     const timestamp = (/* @__PURE__ */ new Date()).toISOString().slice(11, 23);
     console.log(`${colors.dim}${timestamp}${colors.reset} ${color}[${tag}]${colors.reset} ${message}`);
@@ -130,13 +165,26 @@ function createRequestLogger(options = {}) {
       };
     },
     emit(overrides) {
-      const duration = formatDuration(Date.now() - startTime);
+      const durationMs = Date.now() - startTime;
+      const duration = formatDuration(durationMs);
       const level = hasError ? "error" : "info";
-      emitWideEvent(level, {
+      const { _forceKeep, ...restOverrides } = overrides ?? {};
+      const tailCtx = {
+        status: context.status ?? restOverrides.status,
+        duration: durationMs,
+        path: context.path,
+        method: context.method,
+        context: { ...context, ...restOverrides }
+      };
+      const forceKeep = _forceKeep || shouldKeep(tailCtx);
+      if (!forceKeep && !shouldSample(level)) {
+        return null;
+      }
+      return emitWideEvent(level, {
         ...context,
-        ...overrides,
+        ...restOverrides,
         duration
-      });
+      }, true);
     },
     getContext() {
       return { ...context };
@@ -147,4 +195,4 @@ function getEnvironment() {
   return { ...globalEnv };
 }
 
-export { createRequestLogger, getEnvironment, initLogger, log };
+export { createRequestLogger, getEnvironment, initLogger, log, shouldKeep };

package/dist/nitro/plugin.mjs

@@ -1,12 +1,7 @@
 import { defineNitroPlugin, useRuntimeConfig } from 'nitropack/runtime';
 import { initLogger, createRequestLogger } from '../logger.mjs';
-import '../utils.mjs';
+import { matchesPattern } from '../utils.mjs';
 
-function matchesPattern(path, pattern) {
-  const regexPattern = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*\*/g, "{{GLOBSTAR}}").replace(/\*/g, "[^/]*").replace(/{{GLOBSTAR}}/g, ".*").replace(/\?/g, "[^/]");
-  const regex = new RegExp(`^${regexPattern}$`);
-  return regex.test(path);
-}
 function shouldLog(path, include) {
   if (!include || include.length === 0) {
     return true;
@@ -25,18 +20,30 @@ function getResponseStatus(event) {
   }
   return 200;
 }
+function callDrainHook(nitroApp, emittedEvent, event) {
+  if (emittedEvent) {
+    nitroApp.hooks.callHook("evlog:drain", {
+      event: emittedEvent,
+      request: { method: event.method, path: event.path, requestId: event.context.requestId }
+    }).catch((err) => {
+      console.error("[evlog] drain failed:", err);
+    });
+  }
+}
 const plugin = defineNitroPlugin((nitroApp) => {
   const config = useRuntimeConfig();
   const evlogConfig = config.evlog;
   initLogger({
     env: evlogConfig?.env,
-    pretty: evlogConfig?.pretty
+    pretty: evlogConfig?.pretty,
+    sampling: evlogConfig?.sampling
   });
   nitroApp.hooks.hook("request", (event) => {
     const e = event;
     if (!shouldLog(e.path, evlogConfig?.include)) {
       return;
     }
+    e.context._evlogStartTime = Date.now();
     const log = createRequestLogger({
       method: e.method,
       path: e.path,
@@ -44,19 +51,50 @@ const plugin = defineNitroPlugin((nitroApp) => {
     });
     e.context.log = log;
   });
-  nitroApp.hooks.hook("afterResponse", (event) => {
+  nitroApp.hooks.hook("error", async (error, { event }) => {
     const e = event;
+    if (!e) return;
     const log = e.context.log;
     if (log) {
-      log.set({ status: getResponseStatus(e) });
-      log.emit();
+      log.error(error);
+      const errorStatus = error.statusCode ?? 500;
+      log.set({ status: errorStatus });
+      const startTime = e.context._evlogStartTime;
+      const durationMs = startTime ? Date.now() - startTime : void 0;
+      const tailCtx = {
+        status: errorStatus,
+        duration: durationMs,
+        path: e.path,
+        method: e.method,
+        context: log.getContext(),
+        shouldKeep: false
+      };
+      await nitroApp.hooks.callHook("evlog:emit:keep", tailCtx);
+      e.context._evlogEmitted = true;
+      const emittedEvent = log.emit({ _forceKeep: tailCtx.shouldKeep });
+      callDrainHook(nitroApp, emittedEvent, e);
     }
   });
-  nitroApp.hooks.hook("error", (error, { event }) => {
+  nitroApp.hooks.hook("afterResponse", async (event) => {
     const e = event;
-    const log = e?.context.log;
+    if (e.context._evlogEmitted) return;
+    const log = e.context.log;
     if (log) {
-      log.error(error);
+      const status = getResponseStatus(e);
+      log.set({ status });
+      const startTime = e.context._evlogStartTime;
+      const durationMs = startTime ? Date.now() - startTime : void 0;
+      const tailCtx = {
+        status,
+        duration: durationMs,
+        path: e.path,
+        method: e.method,
+        context: log.getContext(),
+        shouldKeep: false
+      };
+      await nitroApp.hooks.callHook("evlog:emit:keep", tailCtx);
+      const emittedEvent = log.emit({ _forceKeep: tailCtx.shouldKeep });
+      callDrainHook(nitroApp, emittedEvent, e);
     }
   });
 });

package/dist/nuxt/module.d.mts

@@ -1,5 +1,5 @@
 import * as _nuxt_schema from '@nuxt/schema';
-import { EnvironmentContext } from '../types.mjs';
+import { EnvironmentContext, SamplingConfig } from '../types.mjs';
 
 interface ModuleOptions {
     /**
@@ -18,6 +18,23 @@ interface ModuleOptions {
      * @example ['/api/**', '/auth/**']
      */
     include?: string[];
+    /**
+     * Sampling configuration for filtering logs.
+     * Allows configuring what percentage of logs to keep per level.
+     *
+     * @example
+     * ```ts
+     * sampling: {
+     *   rates: {
+     *     info: 10,    // Keep 10% of info logs
+     *     warn: 50,    // Keep 50% of warning logs
+     *     debug: 5,    // Keep 5% of debug logs
+     *     error: 100,  // Always keep errors (default)
+     *   }
+     * }
+     * ```
+     */
+    sampling?: SamplingConfig;
 }
 declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;
 

package/dist/nuxt/module.d.ts

@@ -1,5 +1,5 @@
 import * as _nuxt_schema from '@nuxt/schema';
-import { EnvironmentContext } from '../types.js';
+import { EnvironmentContext, SamplingConfig } from '../types.js';
 
 interface ModuleOptions {
     /**
@@ -18,6 +18,23 @@ interface ModuleOptions {
      * @example ['/api/**', '/auth/**']
      */
     include?: string[];
+    /**
+     * Sampling configuration for filtering logs.
+     * Allows configuring what percentage of logs to keep per level.
+     *
+     * @example
+     * ```ts
+     * sampling: {
+     *   rates: {
+     *     info: 10,    // Keep 10% of info logs
+     *     warn: 50,    // Keep 50% of warning logs
+     *     debug: 5,    // Keep 5% of debug logs
+     *     error: 100,  // Always keep errors (default)
+     *   }
+     * }
+     * ```
+     */
+    sampling?: SamplingConfig;
 }
 declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;
 

package/dist/nuxt/module.mjs

@@ -39,7 +39,7 @@ const module$1 = defineNuxtModule({
       },
       {
         name: "log",
-        from: resolver.resolve("../runtime/client/log")
+        from: resolver.resolve("../logger")
       },
       {
         name: "createEvlogError",

package/dist/runtime/client/log.mjs

@@ -1,6 +1,6 @@
 import { getConsoleMethod } from '../../utils.mjs';
 
-const IS_CLIENT = typeof window !== "undefined";
+const isClient = typeof window !== "undefined";
 let clientPretty = true;
 let clientService = "client";
 const LEVEL_COLORS = {
@@ -13,7 +13,7 @@ function initLog(options = {}) {
   clientPretty = options.pretty ?? true;
   clientService = options.service ?? "client";
 }
-function emitClientWideEvent(level, event) {
+function emitLog(level, event) {
   const formatted = {
     timestamp: (/* @__PURE__ */ new Date()).toISOString(),
     level,
@@ -28,33 +28,24 @@ function emitClientWideEvent(level, event) {
     console[method](JSON.stringify(formatted));
   }
 }
-function emitClientTaggedLog(level, tag, message) {
+function emitTaggedLog(level, tag, message) {
   if (clientPretty) {
     console[getConsoleMethod(level)](`%c[${tag}]%c ${message}`, LEVEL_COLORS[level] || "", "color: inherit");
   } else {
-    emitClientWideEvent(level, { tag, message });
+    emitLog(level, { tag, message });
   }
 }
 function createLogMethod(level) {
   return function logMethod(tagOrEvent, message) {
-    if (IS_CLIENT) {
-      if (typeof tagOrEvent === "string" && message !== void 0) {
-        emitClientTaggedLog(level, tagOrEvent, message);
-      } else if (typeof tagOrEvent === "object") {
-        emitClientWideEvent(level, tagOrEvent);
-      } else {
-        emitClientTaggedLog(level, "log", String(tagOrEvent));
-      }
+    if (!(import.meta.client ?? isClient)) {
+      return;
+    }
+    if (typeof tagOrEvent === "string" && message !== void 0) {
+      emitTaggedLog(level, tagOrEvent, message);
+    } else if (typeof tagOrEvent === "object") {
+      emitLog(level, tagOrEvent);
     } else {
-      import('../../logger.mjs').then(({ log: serverLog }) => {
-        if (typeof tagOrEvent === "string" && message !== void 0) {
-          serverLog[level](tagOrEvent, message);
-        } else if (typeof tagOrEvent === "object") {
-          serverLog[level](tagOrEvent);
-        } else {
-          serverLog[level]("log", String(tagOrEvent));
-        }
-      });
+      emitTaggedLog(level, "log", String(tagOrEvent));
     }
   };
 }

package/dist/runtime/server/useLogger.d.mts

@@ -1,5 +1,19 @@
 import { ServerEvent, RequestLogger } from '../../types.mjs';
 
+/**
+ * Returns the request logger attached to the given server event.
+ *
+ * @param event - The current server event containing the context with the logger.
+ * @returns The request-scoped logger.
+ * @throws Error if the logger is not initialized on the event context.
+ *
+ * @example
+ * export default defineEventHandler((event) => {
+ *   const log = useLogger(event)
+ *   log.set({ foo: 'bar' })
+ *   // ...
+ * })
+ */
 declare function useLogger(event: ServerEvent): RequestLogger;
 
 export { useLogger };

package/dist/runtime/server/useLogger.d.ts

@@ -1,5 +1,19 @@
 import { ServerEvent, RequestLogger } from '../../types.js';
 
+/**
+ * Returns the request logger attached to the given server event.
+ *
+ * @param event - The current server event containing the context with the logger.
+ * @returns The request-scoped logger.
+ * @throws Error if the logger is not initialized on the event context.
+ *
+ * @example
+ * export default defineEventHandler((event) => {
+ *   const log = useLogger(event)
+ *   log.set({ foo: 'bar' })
+ *   // ...
+ * })
+ */
 declare function useLogger(event: ServerEvent): RequestLogger;
 
 export { useLogger };

package/dist/types.d.mts

@@ -1,3 +1,140 @@
+declare module 'nitropack/types' {
+    interface NitroRuntimeHooks {
+        /**
+         * Tail sampling hook - called before emitting a log.
+         * Set `ctx.shouldKeep = true` to force-keep the log regardless of head sampling.
+         *
+         * @example
+         * ```ts
+         * nitroApp.hooks.hook('evlog:emit:keep', (ctx) => {
+         *   if (ctx.context.user?.premium) {
+         *     ctx.shouldKeep = true
+         *   }
+         * })
+         * ```
+         */
+        'evlog:emit:keep': (ctx: TailSamplingContext) => void | Promise<void>;
+        /**
+         * Drain hook - called after emitting a log (fire-and-forget).
+         * Use this to send logs to external services like Axiom, Loki, or custom endpoints.
+         * Errors are logged but never block the request.
+         *
+         * @example
+         * ```ts
+         * nitroApp.hooks.hook('evlog:drain', async (ctx) => {
+         *   await fetch('https://api.axiom.co/v1/datasets/logs/ingest', {
+         *     method: 'POST',
+         *     headers: { Authorization: `Bearer ${process.env.AXIOM_TOKEN}` },
+         *     body: JSON.stringify([ctx.event])
+         *   })
+         * })
+         * ```
+         */
+        'evlog:drain': (ctx: DrainContext) => void | Promise<void>;
+    }
+}
+/**
+ * Sampling rates per log level (0-100 percentage)
+ */
+interface SamplingRates {
+    /** Percentage of info logs to keep (0-100). Default: 100 */
+    info?: number;
+    /** Percentage of warn logs to keep (0-100). Default: 100 */
+    warn?: number;
+    /** Percentage of debug logs to keep (0-100). Default: 100 */
+    debug?: number;
+    /** Percentage of error logs to keep (0-100). Default: 100 */
+    error?: number;
+}
+/**
+ * Tail sampling condition for forcing log retention based on request outcome.
+ * All conditions use >= comparison (e.g., status: 400 means status >= 400).
+ */
+interface TailSamplingCondition {
+    /** Keep if HTTP status >= this value (e.g., 400 for all errors) */
+    status?: number;
+    /** Keep if request duration >= this value in milliseconds */
+    duration?: number;
+    /** Keep if path matches this glob pattern (e.g., '/api/critical/**') */
+    path?: string;
+}
+/**
+ * Context passed to tail sampling evaluation and hooks.
+ * Contains request outcome information for sampling decisions.
+ */
+interface TailSamplingContext {
+    /** HTTP response status code */
+    status?: number;
+    /** Request duration in milliseconds (raw number) */
+    duration?: number;
+    /** Request path */
+    path?: string;
+    /** HTTP method */
+    method?: string;
+    /** Full accumulated context from the request logger */
+    context: Record<string, unknown>;
+    /**
+     * Set to true in evlog:emit:keep hook to force keep this log.
+     * Multiple hooks can set this - if any sets it to true, the log is kept.
+     */
+    shouldKeep?: boolean;
+}
+/**
+ * Context passed to the evlog:drain hook.
+ * Contains the complete wide event and request metadata for external transport.
+ */
+interface DrainContext {
+    /** The complete wide event to drain */
+    event: WideEvent;
+    /** Request metadata (if available) */
+    request?: {
+        method?: string;
+        path?: string;
+        requestId?: string;
+    };
+}
+/**
+ * Sampling configuration for filtering logs
+ */
+interface SamplingConfig {
+    /**
+     * Sampling rates per log level (head sampling).
+     * Values are percentages from 0 to 100.
+     * Default: 100 for all levels (log everything).
+     * Error defaults to 100 even if not specified.
+     *
+     * @example
+     * ```ts
+     * sampling: {
+     *   rates: {
+     *     info: 10,    // Keep 10% of info logs
+     *     warn: 50,    // Keep 50% of warning logs
+     *     debug: 5,    // Keep 5% of debug logs
+     *     error: 100,  // Always keep errors (default)
+     *   }
+     * }
+     * ```
+     */
+    rates?: SamplingRates;
+    /**
+     * Tail sampling conditions for forcing log retention (OR logic).
+     * If ANY condition matches, the log is kept regardless of head sampling.
+     * Use the `evlog:emit:keep` Nitro hook for custom conditions.
+     *
+     * @example
+     * ```ts
+     * sampling: {
+     *   rates: { info: 10 },  // Head sampling: keep 10% of info logs
+     *   keep: [
+     *     { status: 400 },     // Always keep if status >= 400
+     *     { duration: 1000 },  // Always keep if duration >= 1000ms
+     *     { path: '/api/critical/**' },  // Always keep critical paths
+     *   ]
+     * }
+     * ```
+     */
+    keep?: TailSamplingCondition[];
+}
 /**
  * Environment context automatically included in every log event
  */
@@ -21,6 +158,8 @@ interface LoggerConfig {
     env?: Partial<EnvironmentContext>;
     /** Enable pretty printing (auto-detected: true in dev, false in prod) */
     pretty?: boolean;
+    /** Sampling configuration for filtering logs */
+    sampling?: SamplingConfig;
 }
 /**
  * Base structure for all wide events
@@ -59,9 +198,10 @@ interface RequestLogger {
      */
     error: (error: Error | string, context?: Record<string, unknown>) => void;
     /**
-     * Emit the final wide event with all accumulated context
+     * Emit the final wide event with all accumulated context.
+     * Returns the emitted WideEvent, or null if the log was sampled out.
      */
-    emit: (overrides?: Record<string, unknown>) => void;
+    emit: (overrides?: Record<string, unknown>) => WideEvent | null;
     /**
      * Get the current accumulated context
      */
@@ -142,6 +282,10 @@ interface H3EventContext {
     log?: RequestLogger;
     requestId?: string;
     status?: number;
+    /** Internal: start time for duration calculation in tail sampling */
+    _evlogStartTime?: number;
+    /** Internal: flag to prevent double emission on errors */
+    _evlogEmitted?: boolean;
     [key: string]: unknown;
 }
 /**
@@ -170,4 +314,4 @@ interface ParsedError {
     raw: unknown;
 }
 
-export type { BaseWideEvent, EnvironmentContext, ErrorOptions, H3EventContext, Log, LogLevel, LoggerConfig, ParsedError, RequestLogger, RequestLoggerOptions, ServerEvent, WideEvent };
+export type { BaseWideEvent, DrainContext, EnvironmentContext, ErrorOptions, H3EventContext, Log, LogLevel, LoggerConfig, ParsedError, RequestLogger, RequestLoggerOptions, SamplingConfig, SamplingRates, ServerEvent, TailSamplingCondition, TailSamplingContext, WideEvent };

package/dist/types.d.ts

@@ -1,3 +1,140 @@
+declare module 'nitropack/types' {
+    interface NitroRuntimeHooks {
+        /**
+         * Tail sampling hook - called before emitting a log.
+         * Set `ctx.shouldKeep = true` to force-keep the log regardless of head sampling.
+         *
+         * @example
+         * ```ts
+         * nitroApp.hooks.hook('evlog:emit:keep', (ctx) => {
+         *   if (ctx.context.user?.premium) {
+         *     ctx.shouldKeep = true
+         *   }
+         * })
+         * ```
+         */
+        'evlog:emit:keep': (ctx: TailSamplingContext) => void | Promise<void>;
+        /**
+         * Drain hook - called after emitting a log (fire-and-forget).
+         * Use this to send logs to external services like Axiom, Loki, or custom endpoints.
+         * Errors are logged but never block the request.
+         *
+         * @example
+         * ```ts
+         * nitroApp.hooks.hook('evlog:drain', async (ctx) => {
+         *   await fetch('https://api.axiom.co/v1/datasets/logs/ingest', {
+         *     method: 'POST',
+         *     headers: { Authorization: `Bearer ${process.env.AXIOM_TOKEN}` },
+         *     body: JSON.stringify([ctx.event])
+         *   })
+         * })
+         * ```
+         */
+        'evlog:drain': (ctx: DrainContext) => void | Promise<void>;
+    }
+}
+/**
+ * Sampling rates per log level (0-100 percentage)
+ */
+interface SamplingRates {
+    /** Percentage of info logs to keep (0-100). Default: 100 */
+    info?: number;
+    /** Percentage of warn logs to keep (0-100). Default: 100 */
+    warn?: number;
+    /** Percentage of debug logs to keep (0-100). Default: 100 */
+    debug?: number;
+    /** Percentage of error logs to keep (0-100). Default: 100 */
+    error?: number;
+}
+/**
+ * Tail sampling condition for forcing log retention based on request outcome.
+ * All conditions use >= comparison (e.g., status: 400 means status >= 400).
+ */
+interface TailSamplingCondition {
+    /** Keep if HTTP status >= this value (e.g., 400 for all errors) */
+    status?: number;
+    /** Keep if request duration >= this value in milliseconds */
+    duration?: number;
+    /** Keep if path matches this glob pattern (e.g., '/api/critical/**') */
+    path?: string;
+}
+/**
+ * Context passed to tail sampling evaluation and hooks.
+ * Contains request outcome information for sampling decisions.
+ */
+interface TailSamplingContext {
+    /** HTTP response status code */
+    status?: number;
+    /** Request duration in milliseconds (raw number) */
+    duration?: number;
+    /** Request path */
+    path?: string;
+    /** HTTP method */
+    method?: string;
+    /** Full accumulated context from the request logger */
+    context: Record<string, unknown>;
+    /**
+     * Set to true in evlog:emit:keep hook to force keep this log.
+     * Multiple hooks can set this - if any sets it to true, the log is kept.
+     */
+    shouldKeep?: boolean;
+}
+/**
+ * Context passed to the evlog:drain hook.
+ * Contains the complete wide event and request metadata for external transport.
+ */
+interface DrainContext {
+    /** The complete wide event to drain */
+    event: WideEvent;
+    /** Request metadata (if available) */
+    request?: {
+        method?: string;
+        path?: string;
+        requestId?: string;
+    };
+}
+/**
+ * Sampling configuration for filtering logs
+ */
+interface SamplingConfig {
+    /**
+     * Sampling rates per log level (head sampling).
+     * Values are percentages from 0 to 100.
+     * Default: 100 for all levels (log everything).
+     * Error defaults to 100 even if not specified.
+     *
+     * @example
+     * ```ts
+     * sampling: {
+     *   rates: {
+     *     info: 10,    // Keep 10% of info logs
+     *     warn: 50,    // Keep 50% of warning logs
+     *     debug: 5,    // Keep 5% of debug logs
+     *     error: 100,  // Always keep errors (default)
+     *   }
+     * }
+     * ```
+     */
+    rates?: SamplingRates;
+    /**
+     * Tail sampling conditions for forcing log retention (OR logic).
+     * If ANY condition matches, the log is kept regardless of head sampling.
+     * Use the `evlog:emit:keep` Nitro hook for custom conditions.
+     *
+     * @example
+     * ```ts
+     * sampling: {
+     *   rates: { info: 10 },  // Head sampling: keep 10% of info logs
+     *   keep: [
+     *     { status: 400 },     // Always keep if status >= 400
+     *     { duration: 1000 },  // Always keep if duration >= 1000ms
+     *     { path: '/api/critical/**' },  // Always keep critical paths
+     *   ]
+     * }
+     * ```
+     */
+    keep?: TailSamplingCondition[];
+}
 /**
  * Environment context automatically included in every log event
  */
@@ -21,6 +158,8 @@ interface LoggerConfig {
     env?: Partial<EnvironmentContext>;
     /** Enable pretty printing (auto-detected: true in dev, false in prod) */
     pretty?: boolean;
+    /** Sampling configuration for filtering logs */
+    sampling?: SamplingConfig;
 }
 /**
  * Base structure for all wide events
@@ -59,9 +198,10 @@ interface RequestLogger {
      */
     error: (error: Error | string, context?: Record<string, unknown>) => void;
     /**
-     * Emit the final wide event with all accumulated context
+     * Emit the final wide event with all accumulated context.
+     * Returns the emitted WideEvent, or null if the log was sampled out.
      */
-    emit: (overrides?: Record<string, unknown>) => void;
+    emit: (overrides?: Record<string, unknown>) => WideEvent | null;
     /**
      * Get the current accumulated context
      */
@@ -142,6 +282,10 @@ interface H3EventContext {
     log?: RequestLogger;
     requestId?: string;
     status?: number;
+    /** Internal: start time for duration calculation in tail sampling */
+    _evlogStartTime?: number;
+    /** Internal: flag to prevent double emission on errors */
+    _evlogEmitted?: boolean;
     [key: string]: unknown;
 }
 /**
@@ -170,4 +314,4 @@ interface ParsedError {
     raw: unknown;
 }
 
-export type { BaseWideEvent, EnvironmentContext, ErrorOptions, H3EventContext, Log, LogLevel, LoggerConfig, ParsedError, RequestLogger, RequestLoggerOptions, ServerEvent, WideEvent };
+export type { BaseWideEvent, DrainContext, EnvironmentContext, ErrorOptions, H3EventContext, Log, LogLevel, LoggerConfig, ParsedError, RequestLogger, RequestLoggerOptions, SamplingConfig, SamplingRates, ServerEvent, TailSamplingCondition, TailSamplingContext, WideEvent };

package/dist/utils.d.mts

@@ -20,5 +20,10 @@ declare const colors: {
     readonly gray: "\u001B[90m";
 };
 declare function getLevelColor(level: string): string;
+/**
+ * Match a path against a glob pattern.
+ * Supports * (any chars except /) and ** (any chars including /).
+ */
+declare function matchesPattern(path: string, pattern: string): boolean;
 
-export { colors, detectEnvironment, formatDuration, getConsoleMethod, getLevelColor, isClient, isDev, isServer };
+export { colors, detectEnvironment, formatDuration, getConsoleMethod, getLevelColor, isClient, isDev, isServer, matchesPattern };

package/dist/utils.d.ts

@@ -20,5 +20,10 @@ declare const colors: {
     readonly gray: "\u001B[90m";
 };
 declare function getLevelColor(level: string): string;
+/**
+ * Match a path against a glob pattern.
+ * Supports * (any chars except /) and ** (any chars including /).
+ */
+declare function matchesPattern(path: string, pattern: string): boolean;
 
-export { colors, detectEnvironment, formatDuration, getConsoleMethod, getLevelColor, isClient, isDev, isServer };
+export { colors, detectEnvironment, formatDuration, getConsoleMethod, getLevelColor, isClient, isDev, isServer, matchesPattern };

package/dist/utils.mjs

@@ -56,5 +56,10 @@ function getLevelColor(level) {
       return colors.white;
   }
 }
+function matchesPattern(path, pattern) {
+  const regexPattern = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*\*/g, "{{GLOBSTAR}}").replace(/\*/g, "[^/]*").replace(/{{GLOBSTAR}}/g, ".*").replace(/\?/g, "[^/]");
+  const regex = new RegExp(`^${regexPattern}$`);
+  return regex.test(path);
+}
 
-export { colors, detectEnvironment, formatDuration, getConsoleMethod, getLevelColor, isClient, isDev, isServer };
+export { colors, detectEnvironment, formatDuration, getConsoleMethod, getLevelColor, isClient, isDev, isServer, matchesPattern };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "evlog",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "Wide event logging library with structured error handling. Inspired by LoggingSucks.",
   "author": "HugoRCD <contact@hrcd.fr>",
   "homepage": "https://evlog.dev",