evlog 1.3.0 → 1.5.0

package/README.md

@@ -3,8 +3,9 @@
 [![npm version](https://img.shields.io/npm/v/evlog?color=black)](https://npmjs.com/package/evlog)
 [![npm downloads](https://img.shields.io/npm/dm/evlog?color=black)](https://npm.chart.dev/evlog)
 [![CI](https://img.shields.io/github/actions/workflow/status/HugoRCD/evlog/ci.yml?branch=main&color=black)](https://github.com/HugoRCD/evlog/actions/workflows/ci.yml)
-[![bundle size](https://img.shields.io/bundlephobia/minzip/evlog?color=black&label=size)](https://bundlephobia.com/package/evlog)
+[![TypeScript](https://img.shields.io/badge/TypeScript-black?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
 [![Nuxt](https://img.shields.io/badge/Nuxt-black?logo=nuxt&logoColor=white)](https://nuxt.com/)
+[![Documentation](https://img.shields.io/badge/Documentation-black?logo=readme&logoColor=white)](https://evlog.dev)
 [![license](https://img.shields.io/github/license/HugoRCD/evlog?color=black)](https://github.com/HugoRCD/evlog/blob/main/LICENSE)
 
 **Your logs are lying to you.**
@@ -389,6 +390,85 @@ Notes:
 - `request.cf` is included (colo, country, asn) unless disabled
 - Use `headerAllowlist` to avoid logging sensitive headers
 
+## Adapters
+
+Send your logs to external observability platforms with built-in adapters.
+
+### Axiom
+
+```typescript
+// server/plugins/evlog-drain.ts
+import { createAxiomDrain } from 'evlog/axiom'
+
+export default defineNitroPlugin((nitroApp) => {
+  nitroApp.hooks.hook('evlog:drain', createAxiomDrain())
+})
+```
+
+Set environment variables:
+
+```bash
+NUXT_AXIOM_TOKEN=xaat-your-token
+NUXT_AXIOM_DATASET=your-dataset
+```
+
+### OTLP (OpenTelemetry)
+
+Works with Grafana, Datadog, Honeycomb, and any OTLP-compatible backend.
+
+```typescript
+// server/plugins/evlog-drain.ts
+import { createOTLPDrain } from 'evlog/otlp'
+
+export default defineNitroPlugin((nitroApp) => {
+  nitroApp.hooks.hook('evlog:drain', createOTLPDrain())
+})
+```
+
+Set environment variables:
+
+```bash
+NUXT_OTLP_ENDPOINT=http://localhost:4318
+```
+
+### Multiple Destinations
+
+Send logs to multiple services:
+
+```typescript
+// server/plugins/evlog-drain.ts
+import { createAxiomDrain } from 'evlog/axiom'
+import { createOTLPDrain } from 'evlog/otlp'
+
+export default defineNitroPlugin((nitroApp) => {
+  const axiom = createAxiomDrain()
+  const otlp = createOTLPDrain()
+
+  nitroApp.hooks.hook('evlog:drain', async (ctx) => {
+    await Promise.allSettled([axiom(ctx), otlp(ctx)])
+  })
+})
+```
+
+### Custom Adapters
+
+Build your own adapter for any destination:
+
+```typescript
+// server/plugins/evlog-drain.ts
+export default defineNitroPlugin((nitroApp) => {
+  nitroApp.hooks.hook('evlog:drain', async (ctx) => {
+    await fetch('https://your-service.com/logs', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(ctx.event),
+    })
+  })
+})
+```
+
+> See the [full documentation](https://evlog.hrcd.fr/adapters/overview) for adapter configuration options, troubleshooting, and advanced patterns.
+
 ## API Reference
 
 ### `initLogger(config)`

package/dist/adapters/posthog.d.mts

@@ -0,0 +1,72 @@
+import { DrainContext, WideEvent } from '../types.mjs';
+
+interface PostHogConfig {
+    /** PostHog project API key */
+    apiKey: string;
+    /** PostHog host URL. Default: https://us.i.posthog.com */
+    host?: string;
+    /** PostHog event name. Default: evlog_wide_event */
+    eventName?: string;
+    /** Override distinct_id (defaults to event.service) */
+    distinctId?: string;
+    /** Request timeout in milliseconds. Default: 5000 */
+    timeout?: number;
+}
+/** PostHog event structure for the batch API */
+interface PostHogEvent {
+    event: string;
+    distinct_id: string;
+    timestamp: string;
+    properties: Record<string, unknown>;
+}
+/**
+ * Convert a WideEvent to a PostHog event format.
+ */
+declare function toPostHogEvent(event: WideEvent, config: PostHogConfig): PostHogEvent;
+/**
+ * Create a drain function for sending logs to PostHog.
+ *
+ * Configuration priority (highest to lowest):
+ * 1. Overrides passed to createPostHogDrain()
+ * 2. runtimeConfig.evlog.posthog
+ * 3. runtimeConfig.posthog
+ * 4. Environment variables: NUXT_POSTHOG_*, POSTHOG_*
+ *
+ * @example
+ * ```ts
+ * // Zero config - just set NUXT_POSTHOG_API_KEY env var
+ * nitroApp.hooks.hook('evlog:drain', createPostHogDrain())
+ *
+ * // With overrides
+ * nitroApp.hooks.hook('evlog:drain', createPostHogDrain({
+ *   apiKey: 'phc_...',
+ *   host: 'https://eu.i.posthog.com',
+ * }))
+ * ```
+ */
+declare function createPostHogDrain(overrides?: Partial<PostHogConfig>): (ctx: DrainContext) => Promise<void>;
+/**
+ * Send a single event to PostHog.
+ *
+ * @example
+ * ```ts
+ * await sendToPostHog(event, {
+ *   apiKey: process.env.POSTHOG_API_KEY!,
+ * })
+ * ```
+ */
+declare function sendToPostHog(event: WideEvent, config: PostHogConfig): Promise<void>;
+/**
+ * Send a batch of events to PostHog.
+ *
+ * @example
+ * ```ts
+ * await sendBatchToPostHog(events, {
+ *   apiKey: process.env.POSTHOG_API_KEY!,
+ * })
+ * ```
+ */
+declare function sendBatchToPostHog(events: WideEvent[], config: PostHogConfig): Promise<void>;
+
+export { createPostHogDrain, sendBatchToPostHog, sendToPostHog, toPostHogEvent };
+export type { PostHogConfig, PostHogEvent };

package/dist/adapters/posthog.d.ts

@@ -0,0 +1,72 @@
+import { DrainContext, WideEvent } from '../types.js';
+
+interface PostHogConfig {
+    /** PostHog project API key */
+    apiKey: string;
+    /** PostHog host URL. Default: https://us.i.posthog.com */
+    host?: string;
+    /** PostHog event name. Default: evlog_wide_event */
+    eventName?: string;
+    /** Override distinct_id (defaults to event.service) */
+    distinctId?: string;
+    /** Request timeout in milliseconds. Default: 5000 */
+    timeout?: number;
+}
+/** PostHog event structure for the batch API */
+interface PostHogEvent {
+    event: string;
+    distinct_id: string;
+    timestamp: string;
+    properties: Record<string, unknown>;
+}
+/**
+ * Convert a WideEvent to a PostHog event format.
+ */
+declare function toPostHogEvent(event: WideEvent, config: PostHogConfig): PostHogEvent;
+/**
+ * Create a drain function for sending logs to PostHog.
+ *
+ * Configuration priority (highest to lowest):
+ * 1. Overrides passed to createPostHogDrain()
+ * 2. runtimeConfig.evlog.posthog
+ * 3. runtimeConfig.posthog
+ * 4. Environment variables: NUXT_POSTHOG_*, POSTHOG_*
+ *
+ * @example
+ * ```ts
+ * // Zero config - just set NUXT_POSTHOG_API_KEY env var
+ * nitroApp.hooks.hook('evlog:drain', createPostHogDrain())
+ *
+ * // With overrides
+ * nitroApp.hooks.hook('evlog:drain', createPostHogDrain({
+ *   apiKey: 'phc_...',
+ *   host: 'https://eu.i.posthog.com',
+ * }))
+ * ```
+ */
+declare function createPostHogDrain(overrides?: Partial<PostHogConfig>): (ctx: DrainContext) => Promise<void>;
+/**
+ * Send a single event to PostHog.
+ *
+ * @example
+ * ```ts
+ * await sendToPostHog(event, {
+ *   apiKey: process.env.POSTHOG_API_KEY!,
+ * })
+ * ```
+ */
+declare function sendToPostHog(event: WideEvent, config: PostHogConfig): Promise<void>;
+/**
+ * Send a batch of events to PostHog.
+ *
+ * @example
+ * ```ts
+ * await sendBatchToPostHog(events, {
+ *   apiKey: process.env.POSTHOG_API_KEY!,
+ * })
+ * ```
+ */
+declare function sendBatchToPostHog(events: WideEvent[], config: PostHogConfig): Promise<void>;
+
+export { createPostHogDrain, sendBatchToPostHog, sendToPostHog, toPostHogEvent };
+export type { PostHogConfig, PostHogEvent };

package/dist/adapters/posthog.mjs

@@ -0,0 +1,79 @@
+function getRuntimeConfig() {
+  try {
+    const { useRuntimeConfig } = require("nitropack/runtime");
+    return useRuntimeConfig();
+  } catch {
+    return void 0;
+  }
+}
+function toPostHogEvent(event, config) {
+  const { timestamp, level, service, ...rest } = event;
+  return {
+    event: config.eventName ?? "evlog_wide_event",
+    distinct_id: config.distinctId ?? service,
+    timestamp,
+    properties: {
+      level,
+      service,
+      ...rest
+    }
+  };
+}
+function createPostHogDrain(overrides) {
+  return async (ctx) => {
+    const runtimeConfig = getRuntimeConfig();
+    const evlogPostHog = runtimeConfig?.evlog?.posthog;
+    const rootPostHog = runtimeConfig?.posthog;
+    const config = {
+      apiKey: overrides?.apiKey ?? evlogPostHog?.apiKey ?? rootPostHog?.apiKey ?? process.env.NUXT_POSTHOG_API_KEY ?? process.env.POSTHOG_API_KEY,
+      host: overrides?.host ?? evlogPostHog?.host ?? rootPostHog?.host ?? process.env.NUXT_POSTHOG_HOST ?? process.env.POSTHOG_HOST,
+      eventName: overrides?.eventName ?? evlogPostHog?.eventName ?? rootPostHog?.eventName,
+      distinctId: overrides?.distinctId ?? evlogPostHog?.distinctId ?? rootPostHog?.distinctId,
+      timeout: overrides?.timeout ?? evlogPostHog?.timeout ?? rootPostHog?.timeout
+    };
+    if (!config.apiKey) {
+      console.error("[evlog/posthog] Missing apiKey. Set NUXT_POSTHOG_API_KEY/POSTHOG_API_KEY env var or pass to createPostHogDrain()");
+      return;
+    }
+    try {
+      await sendToPostHog(ctx.event, config);
+    } catch (error) {
+      console.error("[evlog/posthog] Failed to send event:", error);
+    }
+  };
+}
+async function sendToPostHog(event, config) {
+  await sendBatchToPostHog([event], config);
+}
+async function sendBatchToPostHog(events, config) {
+  if (events.length === 0) return;
+  const host = (config.host ?? "https://us.i.posthog.com").replace(/\/$/, "");
+  const timeout = config.timeout ?? 5e3;
+  const url = `${host}/batch/`;
+  const batch = events.map((event) => toPostHogEvent(event, config));
+  const payload = {
+    api_key: config.apiKey,
+    batch
+  };
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), timeout);
+  try {
+    const response = await fetch(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify(payload),
+      signal: controller.signal
+    });
+    if (!response.ok) {
+      const text = await response.text().catch(() => "Unknown error");
+      const safeText = text.length > 200 ? `${text.slice(0, 200)}...[truncated]` : text;
+      throw new Error(`PostHog API error: ${response.status} ${response.statusText} - ${safeText}`);
+    }
+  } finally {
+    clearTimeout(timeoutId);
+  }
+}
+
+export { createPostHogDrain, sendBatchToPostHog, sendToPostHog, toPostHogEvent };

package/dist/nitro/plugin.mjs

@@ -15,6 +15,15 @@ function shouldLog(path, include, exclude) {
   }
   return include.some((pattern) => matchesPattern(path, pattern));
 }
+function getServiceForPath(path, routes) {
+  if (!routes) return void 0;
+  for (const [pattern, config] of Object.entries(routes)) {
+    if (matchesPattern(path, pattern)) {
+      return config.service;
+    }
+  }
+  return void 0;
+}
 const SENSITIVE_HEADERS = [
   "authorization",
   "cookie",
@@ -46,14 +55,17 @@ 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 },
-      headers: getSafeHeaders(event)
-    }).catch((err) => {
-      console.error("[evlog] drain failed:", err);
-    });
+  if (!emittedEvent) return;
+  const drainPromise = nitroApp.hooks.callHook("evlog:drain", {
+    event: emittedEvent,
+    request: { method: event.method, path: event.path, requestId: event.context.requestId },
+    headers: getSafeHeaders(event)
+  }).catch((err) => {
+    console.error("[evlog] drain failed:", err);
+  });
+  const waitUntilCtx = event.context.cloudflare?.context ?? event.context;
+  if (typeof waitUntilCtx?.waitUntil === "function") {
+    waitUntilCtx.waitUntil(drainPromise);
   }
 }
 const plugin = defineNitroPlugin((nitroApp) => {
@@ -70,11 +82,20 @@ const plugin = defineNitroPlugin((nitroApp) => {
       return;
     }
     e.context._evlogStartTime = Date.now();
+    let requestIdOverride = void 0;
+    if (globalThis.navigator?.userAgent === "Cloudflare-Workers") {
+      const cfRay = getSafeHeaders(event)?.["cf-ray"];
+      if (cfRay) requestIdOverride = cfRay;
+    }
     const log = createRequestLogger({
       method: e.method,
       path: e.path,
-      requestId: e.context.requestId || crypto.randomUUID()
+      requestId: requestIdOverride || e.context.requestId || crypto.randomUUID()
     });
+    const routeService = getServiceForPath(e.path, evlogConfig?.routes);
+    if (routeService) {
+      log.set({ service: routeService });
+    }
     e.context.log = log;
   });
   nitroApp.hooks.hook("error", async (error, { event }) => {

package/dist/nuxt/module.d.mts

@@ -1,5 +1,5 @@
 import * as _nuxt_schema from '@nuxt/schema';
-import { EnvironmentContext, SamplingConfig, TransportConfig } from '../types.mjs';
+import { EnvironmentContext, RouteConfig, SamplingConfig, TransportConfig } from '../types.mjs';
 
 interface ModuleOptions {
     /**
@@ -25,6 +25,20 @@ interface ModuleOptions {
      * @example ['/api/_nuxt_icon/**', '/health']
      */
     exclude?: string[];
+    /**
+     * Route-specific service configuration.
+     * Allows setting different service names for different routes.
+     * Patterns are matched using glob syntax.
+     *
+     * @example
+     * ```ts
+     * routes: {
+     *   '/api/foo/**': { service: 'service1' },
+     *   '/api/bar/**': { service: 'service2' }
+     * }
+     * ```
+     */
+    routes?: Record<string, RouteConfig>;
     /**
      * Sampling configuration for filtering logs.
      * Allows configuring what percentage of logs to keep per level.

package/dist/nuxt/module.d.ts

@@ -1,5 +1,5 @@
 import * as _nuxt_schema from '@nuxt/schema';
-import { EnvironmentContext, SamplingConfig, TransportConfig } from '../types.js';
+import { EnvironmentContext, RouteConfig, SamplingConfig, TransportConfig } from '../types.js';
 
 interface ModuleOptions {
     /**
@@ -25,6 +25,20 @@ interface ModuleOptions {
      * @example ['/api/_nuxt_icon/**', '/health']
      */
     exclude?: string[];
+    /**
+     * Route-specific service configuration.
+     * Allows setting different service names for different routes.
+     * Patterns are matched using glob syntax.
+     *
+     * @example
+     * ```ts
+     * routes: {
+     *   '/api/foo/**': { service: 'service1' },
+     *   '/api/bar/**': { service: 'service2' }
+     * }
+     * ```
+     */
+    routes?: Record<string, RouteConfig>;
     /**
      * Sampling configuration for filtering logs.
      * Allows configuring what percentage of logs to keep per level.

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

@@ -4,6 +4,7 @@ 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.
+ * @param service - Optional service name to override the default service.
  * @returns The request-scoped logger.
  * @throws Error if the logger is not initialized on the event context.
  *
@@ -13,7 +14,15 @@ import { ServerEvent, RequestLogger } from '../../types.mjs';
  *   log.set({ foo: 'bar' })
  *   // ...
  * })
+ *
+ * @example
+ * // Override service name for specific routes
+ * export default defineEventHandler((event) => {
+ *   const log = useLogger(event, 'payment-service')
+ *   log.set({ foo: 'bar' })
+ *   // ...
+ * })
  */
-declare function useLogger(event: ServerEvent): RequestLogger;
+declare function useLogger(event: ServerEvent, service?: string): RequestLogger;
 
 export { useLogger };

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

@@ -4,6 +4,7 @@ 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.
+ * @param service - Optional service name to override the default service.
  * @returns The request-scoped logger.
  * @throws Error if the logger is not initialized on the event context.
  *
@@ -13,7 +14,15 @@ import { ServerEvent, RequestLogger } from '../../types.js';
  *   log.set({ foo: 'bar' })
  *   // ...
  * })
+ *
+ * @example
+ * // Override service name for specific routes
+ * export default defineEventHandler((event) => {
+ *   const log = useLogger(event, 'payment-service')
+ *   log.set({ foo: 'bar' })
+ *   // ...
+ * })
  */
-declare function useLogger(event: ServerEvent): RequestLogger;
+declare function useLogger(event: ServerEvent, service?: string): RequestLogger;
 
 export { useLogger };

package/dist/runtime/server/useLogger.mjs

@@ -1,10 +1,13 @@
-function useLogger(event) {
+function useLogger(event, service) {
   const log = event.context.log;
   if (!log) {
     throw new Error(
       '[evlog] Logger not initialized. Make sure the evlog Nitro plugin is registered. If using Nuxt, add "evlog" to your modules.'
     );
   }
+  if (service) {
+    log.set({ service });
+  }
   return log;
 }
 

package/dist/types.d.mts

@@ -160,6 +160,13 @@ interface SamplingConfig {
      */
     keep?: TailSamplingCondition[];
 }
+/**
+ * Route-based service configuration
+ */
+interface RouteConfig {
+    /** Service name to use for routes matching this pattern */
+    service: string;
+}
 /**
  * Environment context automatically included in every log event
  */
@@ -325,7 +332,16 @@ interface H3EventContext {
 interface ServerEvent {
     method: string;
     path: string;
-    context: H3EventContext;
+    context: H3EventContext & {
+        /** Cloudflare Workers context (available when deployed to CF Workers) */
+        cloudflare?: {
+            context: {
+                waitUntil: (promise: Promise<unknown>) => void;
+            };
+        };
+        /** Vercel Edge context (available when deployed to Vercel Edge) */
+        waitUntil?: (promise: Promise<unknown>) => void;
+    };
     node?: {
         res?: {
             statusCode?: number;
@@ -345,4 +361,4 @@ interface ParsedError {
     raw: unknown;
 }
 
-export type { BaseWideEvent, DrainContext, EnvironmentContext, ErrorOptions, H3EventContext, IngestPayload, Log, LogLevel, LoggerConfig, ParsedError, RequestLogger, RequestLoggerOptions, SamplingConfig, SamplingRates, ServerEvent, TailSamplingCondition, TailSamplingContext, TransportConfig, WideEvent };
+export type { BaseWideEvent, DrainContext, EnvironmentContext, ErrorOptions, H3EventContext, IngestPayload, Log, LogLevel, LoggerConfig, ParsedError, RequestLogger, RequestLoggerOptions, RouteConfig, SamplingConfig, SamplingRates, ServerEvent, TailSamplingCondition, TailSamplingContext, TransportConfig, WideEvent };

package/dist/types.d.ts

@@ -160,6 +160,13 @@ interface SamplingConfig {
      */
     keep?: TailSamplingCondition[];
 }
+/**
+ * Route-based service configuration
+ */
+interface RouteConfig {
+    /** Service name to use for routes matching this pattern */
+    service: string;
+}
 /**
  * Environment context automatically included in every log event
  */
@@ -325,7 +332,16 @@ interface H3EventContext {
 interface ServerEvent {
     method: string;
     path: string;
-    context: H3EventContext;
+    context: H3EventContext & {
+        /** Cloudflare Workers context (available when deployed to CF Workers) */
+        cloudflare?: {
+            context: {
+                waitUntil: (promise: Promise<unknown>) => void;
+            };
+        };
+        /** Vercel Edge context (available when deployed to Vercel Edge) */
+        waitUntil?: (promise: Promise<unknown>) => void;
+    };
     node?: {
         res?: {
             statusCode?: number;
@@ -345,4 +361,4 @@ interface ParsedError {
     raw: unknown;
 }
 
-export type { BaseWideEvent, DrainContext, EnvironmentContext, ErrorOptions, H3EventContext, IngestPayload, Log, LogLevel, LoggerConfig, ParsedError, RequestLogger, RequestLoggerOptions, SamplingConfig, SamplingRates, ServerEvent, TailSamplingCondition, TailSamplingContext, TransportConfig, WideEvent };
+export type { BaseWideEvent, DrainContext, EnvironmentContext, ErrorOptions, H3EventContext, IngestPayload, Log, LogLevel, LoggerConfig, ParsedError, RequestLogger, RequestLoggerOptions, RouteConfig, SamplingConfig, SamplingRates, ServerEvent, TailSamplingCondition, TailSamplingContext, TransportConfig, WideEvent };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "evlog",
-  "version": "1.3.0",
+  "version": "1.5.0",
   "description": "Wide event logging library with structured error handling. Inspired by LoggingSucks.",
   "author": "HugoRCD <contact@hrcd.fr>",
   "homepage": "https://evlog.dev",
@@ -46,6 +46,10 @@
     "./otlp": {
       "types": "./dist/adapters/otlp.d.mts",
       "import": "./dist/adapters/otlp.mjs"
+    },
+    "./posthog": {
+      "types": "./dist/adapters/posthog.d.mts",
+      "import": "./dist/adapters/posthog.mjs"
     }
   },
   "main": "./dist/index.mjs",
@@ -69,6 +73,9 @@
       ],
       "otlp": [
         "./dist/adapters/otlp.d.mts"
+      ],
+      "posthog": [
+        "./dist/adapters/posthog.d.mts"
       ]
     }
   },
@@ -88,17 +95,17 @@
     "typecheck": "echo 'Typecheck handled by build'"
   },
   "dependencies": {
-    "@nuxt/kit": "^4.3.0",
+    "@nuxt/kit": "^4.3.1",
     "defu": "^6.1.4"
   },
   "devDependencies": {
     "@nuxt/devtools": "^3.1.1",
-    "@nuxt/schema": "^4.3.0",
+    "@nuxt/schema": "^4.3.1",
     "@nuxt/test-utils": "^3.23.0",
     "changelogen": "^0.6.2",
     "h3": "^1.15.5",
     "nitropack": "^2.13.1",
-    "nuxt": "^4.3.0",
+    "nuxt": "^4.3.1",
     "typescript": "^5.9.3",
     "unbuild": "^3.6.1"
   },