evlog 1.0.1 → 1.2.0

package/dist/types.d.ts

@@ -1,3 +1,165 @@
+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>;
+    }
+}
+/**
+ * Transport configuration for sending client logs to the server
+ */
+interface TransportConfig {
+    /**
+     * Enable sending logs to the server API
+     * @default false
+     */
+    enabled?: boolean;
+    /**
+     * API endpoint for log ingestion
+     * @default '/api/_evlog/ingest'
+     */
+    endpoint?: string;
+}
+/**
+ * Payload sent from client to server for log ingestion
+ */
+interface IngestPayload {
+    timestamp: string;
+    level: 'info' | 'error' | 'warn' | 'debug';
+    [key: string]: unknown;
+}
+/**
+ * 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;
+    };
+    /** HTTP headers from the original request (useful for correlation with external services) */
+    headers?: Record<string, 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 +183,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
@@ -51,7 +215,7 @@ type WideEvent = BaseWideEvent & Record<string, unknown>;
  */
 interface RequestLogger {
     /**
-     * Add context to the wide event (shallow merge)
+     * Add context to the wide event (deep merge via defu)
      */
     set: <T extends Record<string, unknown>>(context: T) => void;
     /**
@@ -59,9 +223,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 +307,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 +339,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, IngestPayload, Log, LogLevel, LoggerConfig, ParsedError, RequestLogger, RequestLoggerOptions, SamplingConfig, SamplingRates, ServerEvent, TailSamplingCondition, TailSamplingContext, TransportConfig, 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.2.0",
   "description": "Wide event logging library with structured error handling. Inspired by LoggingSucks.",
   "author": "HugoRCD <contact@hrcd.fr>",
   "homepage": "https://evlog.dev",
@@ -67,7 +67,8 @@
     "typecheck": "echo 'Typecheck handled by build'"
   },
   "dependencies": {
-    "@nuxt/kit": "^4.3.0"
+    "@nuxt/kit": "^4.3.0",
+    "defu": "^6.1.4"
   },
   "devDependencies": {
     "@nuxt/devtools": "^3.1.1",