evlog 1.8.0 → 1.10.0

package/README.md

@@ -4,13 +4,12 @@
 [![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)
 [![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.**
 
-A single request generates 10+ log lines. When production breaks at 3am, you're grep-ing through noise, praying you'll find signal. Your errors say "Something went wrong" – thanks, very helpful.
+A single request generates 10+ log lines. When production breaks at 3am, you're grep-ing through noise, praying you'll find signal. Your errors say "Something went wrong" -- thanks, very helpful.
 
 **evlog fixes this.** One log per request. All context included. Errors that explain themselves.
 
@@ -21,13 +20,13 @@ A single request generates 10+ log lines. When production breaks at 3am, you're
 ```typescript
 // server/api/checkout.post.ts
 
-// ❌ Scattered logs - impossible to debug
+// Scattered logs - impossible to debug
 console.log('Request received')
 console.log('User:', user.id)
 console.log('Cart loaded')
 console.log('Payment failed')  // Good luck finding this at 3am
 
-throw new Error('Something went wrong')  // 🤷‍♂️
+throw new Error('Something went wrong')
 ```
 
 ### The Solution
@@ -36,7 +35,7 @@ throw new Error('Something went wrong')  // 🤷‍♂️
 // server/api/checkout.post.ts
 import { useLogger } from 'evlog'
 
-// ✅ One comprehensive event per request
+// One comprehensive event per request
 export default defineEventHandler(async (event) => {
   const log = useLogger(event)  // Auto-injected by evlog
 
@@ -176,18 +175,43 @@ The wide event emitted at the end contains **everything**:
 
 Works with **any framework powered by Nitro**: Nuxt, Analog, Vinxi, SolidStart, TanStack Start, and more.
 
+### Nitro v3
+
+```typescript
+// nitro.config.ts
+import { defineConfig } from 'nitro'
+import evlog from 'evlog/nitro/v3'
+
+export default defineConfig({
+  modules: [
+    evlog({ env: { service: 'my-api' } })
+  ],
+})
+```
+
+### Nitro v2
+
 ```typescript
 // nitro.config.ts
+import { defineNitroConfig } from 'nitropack/config'
+import evlog from 'evlog/nitro'
+
 export default defineNitroConfig({
-  plugins: ['evlog/nitro'],
+  modules: [
+    evlog({ env: { service: 'my-api' } })
+  ],
 })
 ```
 
-Same API, same wide events:
+Then use `useLogger` in any route. Import from `evlog/nitro/v3` (v3) or `evlog/nitro` (v2):
 
 ```typescript
 // routes/api/documents/[id]/export.post.ts
-import { useLogger, createError } from 'evlog'
+// Nitro v3: import { defineHandler } from 'nitro/h3' + import { useLogger } from 'evlog/nitro/v3'
+// Nitro v2: import { defineEventHandler } from 'h3' + import { useLogger } from 'evlog/nitro'
+import { defineEventHandler } from 'h3'
+import { useLogger } from 'evlog/nitro'
+import { createError } from 'evlog'
 
 export default defineEventHandler(async (event) => {
   const log = useLogger(event)
@@ -248,47 +272,6 @@ Output when the export completes:
 }
 ```
 
-## Structured Errors
-
-Errors should tell you **what** happened, **why**, and **how to fix it**.
-
-```typescript
-// server/api/repos/sync.post.ts
-import { useLogger, createError } from 'evlog'
-
-export default defineEventHandler(async (event) => {
-  const log = useLogger(event)
-
-  log.set({ repo: { owner: 'acme', name: 'my-project' } })
-
-  try {
-    const result = await syncWithGitHub()
-    log.set({ sync: { commits: result.commits, files: result.files } })
-    return result
-  } catch (error) {
-    log.error(error, { step: 'github-sync' })
-
-    throw createError({
-      message: 'Failed to sync repository',
-      status: 503,
-      why: 'GitHub API rate limit exceeded',
-      fix: 'Wait 1 hour or use a different token',
-      link: 'https://docs.github.com/en/rest/rate-limit',
-      cause: error,
-    })
-  }
-})
-```
-
-Console output (development):
-
-```
-Error: Failed to sync repository
-Why: GitHub API rate limit exceeded
-Fix: Wait 1 hour or use a different token
-More info: https://docs.github.com/en/rest/rate-limit
-```
-
 ## Standalone TypeScript
 
 For scripts, workers, or any TypeScript project:
@@ -390,6 +373,130 @@ Notes:
 - `request.cf` is included (colo, country, asn) unless disabled
 - Use `headerAllowlist` to avoid logging sensitive headers
 
+## Hono
+
+Use the standalone API to create one wide event per request from a Hono middleware.
+
+```typescript
+// src/index.ts
+import { serve } from '@hono/node-server'
+import { Hono } from 'hono'
+import { createRequestLogger, initLogger } from 'evlog'
+
+initLogger({
+  env: { service: 'hono-api' },
+})
+
+const app = new Hono()
+
+app.use('*', async (c, next) => {
+  const startedAt = Date.now()
+  const log = createRequestLogger({ method: c.req.method, path: c.req.path })
+
+  try {
+    await next()
+  } catch (error) {
+    log.error(error as Error)
+    throw error
+  } finally {
+    log.emit({
+      status: c.res.status,
+      duration: Date.now() - startedAt,
+    })
+  }
+})
+
+app.get('/health', (c) => c.json({ ok: true }))
+
+serve({ fetch: app.fetch, port: 3000 })
+```
+
+See the full [hono example](https://github.com/HugoRCD/evlog/tree/main/examples/hono) for a complete working project.
+
+## Browser
+
+Use the `log` API on the client side for structured browser logging:
+
+```typescript
+import { log } from 'evlog/browser'
+
+log.info('checkout', 'User initiated checkout')
+log.error({ action: 'payment', error: 'validation_failed' })
+```
+
+In Nuxt, `log` is auto-imported -- no import needed in Vue components:
+
+```vue
+<script setup>
+log.info('checkout', 'User initiated checkout')
+</script>
+```
+
+Client logs output to the browser console with colored tags in development.
+
+### Client Transport
+
+To send client logs to the server for centralized logging, enable the transport:
+
+```typescript
+// nuxt.config.ts
+export default defineNuxtConfig({
+  modules: ['evlog/nuxt'],
+  evlog: {
+    transport: {
+      enabled: true,  // Send client logs to server
+    },
+  },
+})
+```
+
+When enabled:
+1. Client logs are sent to `/api/_evlog/ingest` via POST
+2. Server enriches with environment context (service, version, etc.)
+3. `evlog:drain` hook is called with `source: 'client'`
+4. External services receive the log
+
+## Structured Errors
+
+Errors should tell you **what** happened, **why**, and **how to fix it**.
+
+```typescript
+// server/api/repos/sync.post.ts
+import { useLogger, createError } from 'evlog'
+
+export default defineEventHandler(async (event) => {
+  const log = useLogger(event)
+
+  log.set({ repo: { owner: 'acme', name: 'my-project' } })
+
+  try {
+    const result = await syncWithGitHub()
+    log.set({ sync: { commits: result.commits, files: result.files } })
+    return result
+  } catch (error) {
+    log.error(error, { step: 'github-sync' })
+
+    throw createError({
+      message: 'Failed to sync repository',
+      status: 503,
+      why: 'GitHub API rate limit exceeded',
+      fix: 'Wait 1 hour or use a different token',
+      link: 'https://docs.github.com/en/rest/rate-limit',
+      cause: error,
+    })
+  }
+})
+```
+
+Console output (development):
+
+```
+Error: Failed to sync repository
+Why: GitHub API rate limit exceeded
+Fix: Wait 1 hour or use a different token
+More info: https://docs.github.com/en/rest/rate-limit
+```
+
 ## Enrichment Hook
 
 Use the `evlog:enrich` hook to add derived context after emit, before drain.
@@ -428,6 +535,58 @@ export default defineNitroPlugin((nitroApp) => {
 })
 ```
 
+Each enricher adds a specific field to the event:
+
+| Enricher | Event Field | Shape |
+|----------|-------------|-------|
+| `createUserAgentEnricher()` | `event.userAgent` | `{ raw, browser?: { name, version? }, os?: { name, version? }, device?: { type } }` |
+| `createGeoEnricher()` | `event.geo` | `{ country?, region?, regionCode?, city?, latitude?, longitude? }` |
+| `createRequestSizeEnricher()` | `event.requestSize` | `{ requestBytes?, responseBytes? }` |
+| `createTraceContextEnricher()` | `event.traceContext` + `event.traceId` + `event.spanId` | `{ traceparent?, tracestate?, traceId?, spanId? }` |
+
+All enrichers accept an optional `{ overwrite?: boolean }` option. By default (`overwrite: false`), user-provided data on the event takes precedence over enricher-computed values. Set `overwrite: true` to always replace existing fields.
+
+> **Cloudflare geo note:** Only `cf-ipcountry` is a real Cloudflare HTTP header. The `cf-region`, `cf-city`, `cf-latitude`, `cf-longitude` headers are NOT standard -- they are properties of `request.cf`. For full geo data on Cloudflare, write a custom enricher that reads `request.cf`, or use a Workers middleware to forward `cf` properties as custom headers.
+
+### Custom Enrichers
+
+The `evlog:enrich` hook receives an `EnrichContext` with these fields:
+
+```typescript
+interface EnrichContext {
+  event: WideEvent        // The emitted wide event (mutable -- modify it directly)
+  request?: {             // Request metadata
+    method?: string
+    path?: string
+    requestId?: string
+  }
+  headers?: Record<string, string>  // Safe HTTP headers (sensitive headers filtered)
+  response?: {            // Response metadata
+    status?: number
+    headers?: Record<string, string>
+  }
+}
+```
+
+Example custom enricher:
+
+```typescript
+// server/plugins/evlog-enrich.ts
+export default defineNitroPlugin((nitroApp) => {
+  nitroApp.hooks.hook('evlog:enrich', (ctx) => {
+    // Add deployment metadata
+    ctx.event.deploymentId = process.env.DEPLOYMENT_ID
+    ctx.event.region = process.env.FLY_REGION
+
+    // Extract data from headers
+    const tenantId = ctx.headers?.['x-tenant-id']
+    if (tenantId) {
+      ctx.event.tenantId = tenantId
+    }
+  })
+})
+```
+
 ## Adapters
 
 Send your logs to external observability platforms with built-in adapters.
@@ -469,6 +628,24 @@ Set environment variables:
 NUXT_OTLP_ENDPOINT=http://localhost:4318
 ```
 
+### PostHog
+
+```typescript
+// server/plugins/evlog-drain.ts
+import { createPostHogDrain } from 'evlog/posthog'
+
+export default defineNitroPlugin((nitroApp) => {
+  nitroApp.hooks.hook('evlog:drain', createPostHogDrain())
+})
+```
+
+Set environment variables:
+
+```bash
+NUXT_POSTHOG_API_KEY=phc_your-key
+NUXT_POSTHOG_HOST=https://us.i.posthog.com  # Optional: for EU or self-hosted
+```
+
 ### Sentry
 
 ```typescript
@@ -486,6 +663,23 @@ Set environment variables:
 NUXT_SENTRY_DSN=https://public@o0.ingest.sentry.io/123
 ```
 
+### Better Stack
+
+```typescript
+// server/plugins/evlog-drain.ts
+import { createBetterStackDrain } from 'evlog/better-stack'
+
+export default defineNitroPlugin((nitroApp) => {
+  nitroApp.hooks.hook('evlog:drain', createBetterStackDrain())
+})
+```
+
+Set environment variables:
+
+```bash
+NUXT_BETTER_STACK_SOURCE_TOKEN=your-source-token
+```
+
 ### Multiple Destinations
 
 Send logs to multiple services:
@@ -571,15 +765,15 @@ export default defineNitroPlugin((nitroApp) => {
 | `retry.initialDelayMs` | `1000` | Base delay for first retry |
 | `retry.maxDelayMs` | `30000` | Upper bound for any retry delay |
 | `maxBufferSize` | `1000` | Max buffered events before dropping oldest |
-| `onDropped` | — | Callback when events are dropped |
+| `onDropped` | -- | Callback when events are dropped |
 
 ### Returned drain function
 
 The function returned by `pipeline(drain)` is hook-compatible and exposes:
 
-- **`drain(ctx)`** — Push a single event into the buffer
-- **`drain.flush()`** — Force-flush all buffered events (call on server shutdown)
-- **`drain.pending`** — Number of events currently buffered
+- **`drain(ctx)`** -- Push a single event into the buffer
+- **`drain.flush()`** -- Force-flush all buffered events (call on server shutdown)
+- **`drain.pending`** -- Number of events currently buffered
 
 ## API Reference
 
@@ -589,7 +783,7 @@ Initialize the logger. Required for standalone usage, automatic with Nuxt/Nitro
 
 ```typescript
 initLogger({
-  enabled: boolean       // (optional) Enable/disable all logging (default: true)
+  enabled: boolean       // Optional. Enable/disable all logging (default: true)
   env: {
     service: string      // Service name
     environment: string  // 'production' | 'development' | 'test'
@@ -680,9 +874,9 @@ In development, evlog uses a compact tree format:
 
 ```
 16:45:31.060 INFO [my-app] GET /api/checkout 200 in 234ms
-  ├─ user: id=123 plan=premium
-  ├─ cart: items=3 total=9999
-  └─ payment: id=pay_xyz method=card
+  |- user: id=123 plan=premium
+  |- cart: items=3 total=9999
+  +- payment: id=pay_xyz method=card
 ```
 
 In production (`pretty: false`), logs are emitted as JSON for machine parsing.
@@ -793,16 +987,16 @@ try {
 
 ## Framework Support
 
-evlog works with any framework powered by [Nitro](https://nitro.unjs.io/):
-
 | Framework | Integration |
 |-----------|-------------|
 | **Nuxt** | `modules: ['evlog/nuxt']` |
-| **Analog** | `plugins: ['evlog/nitro']` |
-| **Vinxi** | `plugins: ['evlog/nitro']` |
-| **SolidStart** | `plugins: ['evlog/nitro']` |
-| **TanStack Start** | `plugins: ['evlog/nitro']` |
-| **Standalone Nitro** | `plugins: ['evlog/nitro']` |
+| **Next.js** | `createEvlog()` factory with `import { createEvlog } from 'evlog/next'` ([example](./examples/nextjs)) |
+| **Nitro v3** | `modules: [evlog()]` with `import evlog from 'evlog/nitro/v3'` |
+| **Nitro v2** | `modules: [evlog()]` with `import evlog from 'evlog/nitro'` |
+| **Analog** | Nitro v2 module setup |
+| **Vinxi** | Nitro v2 module setup |
+| **SolidStart** | Nitro v2 module setup ([example](./examples/solidstart)) |
+| **TanStack Start** | Nitro v2 module setup |
 
 ## Agent Skills
 

package/dist/{_severity-CXfyvxQi.mjs → _severity-D_IU9-90.mjs}

@@ -14,4 +14,4 @@ const OTEL_SEVERITY_TEXT = {
 
 //#endregion
 export { OTEL_SEVERITY_TEXT as n, OTEL_SEVERITY_NUMBER as t };
-//# sourceMappingURL=_severity-CXfyvxQi.mjs.map
+//# sourceMappingURL=_severity-D_IU9-90.mjs.map

package/dist/{_severity-CXfyvxQi.mjs.map → _severity-D_IU9-90.mjs.map}

@@ -1 +1 @@
-{"version":3,"file":"_severity-CXfyvxQi.mjs","names":[],"sources":["../src/adapters/_severity.ts"],"sourcesContent":["import type { LogLevel } from '../types'\n\nexport const OTEL_SEVERITY_NUMBER: Record<LogLevel, number> = {\n  debug: 5,\n  info: 9,\n  warn: 13,\n  error: 17,\n}\n\nexport const OTEL_SEVERITY_TEXT: Record<LogLevel, string> = {\n  debug: 'DEBUG',\n  info: 'INFO',\n  warn: 'WARN',\n  error: 'ERROR',\n}\n"],"mappings":";AAEA,MAAa,uBAAiD;CAC5D,OAAO;CACP,MAAM;CACN,MAAM;CACN,OAAO;CACR;AAED,MAAa,qBAA+C;CAC1D,OAAO;CACP,MAAM;CACN,MAAM;CACN,OAAO;CACR"}
+{"version":3,"file":"_severity-D_IU9-90.mjs","names":[],"sources":["../src/adapters/_severity.ts"],"sourcesContent":["import type { LogLevel } from '../types'\n\nexport const OTEL_SEVERITY_NUMBER: Record<LogLevel, number> = {\n  debug: 5,\n  info: 9,\n  warn: 13,\n  error: 17,\n}\n\nexport const OTEL_SEVERITY_TEXT: Record<LogLevel, string> = {\n  debug: 'DEBUG',\n  info: 'INFO',\n  warn: 'WARN',\n  error: 'ERROR',\n}\n"],"mappings":";AAEA,MAAa,uBAAiD;CAC5D,OAAO;CACP,MAAM;CACN,MAAM;CACN,OAAO;CACR;AAED,MAAa,qBAA+C;CAC1D,OAAO;CACP,MAAM;CACN,MAAM;CACN,OAAO;CACR"}

package/dist/adapters/otlp.mjs

@@ -1,5 +1,5 @@
 import { n as defineDrain, r as resolveAdapterConfig, t as httpPost } from "../_http-DVDwNag0.mjs";
-import { n as OTEL_SEVERITY_TEXT, t as OTEL_SEVERITY_NUMBER } from "../_severity-CXfyvxQi.mjs";
+import { n as OTEL_SEVERITY_TEXT, t as OTEL_SEVERITY_NUMBER } from "../_severity-D_IU9-90.mjs";
 
 //#region src/adapters/otlp.ts
 const OTLP_FIELDS = [

package/dist/adapters/sentry.mjs

@@ -1,5 +1,5 @@
 import { n as defineDrain, r as resolveAdapterConfig, t as httpPost } from "../_http-DVDwNag0.mjs";
-import { t as OTEL_SEVERITY_NUMBER } from "../_severity-CXfyvxQi.mjs";
+import { t as OTEL_SEVERITY_NUMBER } from "../_severity-D_IU9-90.mjs";
 
 //#region src/adapters/sentry.ts
 const SENTRY_FIELDS = [

package/dist/next/client.d.mts

@@ -0,0 +1,55 @@
+import { TransportConfig } from "../types.mjs";
+import { clearIdentity, log as _clientLog, setIdentity } from "../runtime/client/log.mjs";
+import * as react from "react";
+
+//#region src/next/client.d.ts
+interface EvlogProviderProps {
+  /**
+   * Service name for client-side logs.
+   * @default 'client'
+   */
+  service?: string;
+  /**
+   * Enable pretty printing in the browser console.
+   * @default true
+   */
+  pretty?: boolean;
+  /**
+   * Transport configuration for sending client logs to the server.
+   */
+  transport?: TransportConfig;
+  /**
+   * Enable or disable client-side logging.
+   * @default true
+   */
+  enabled?: boolean;
+  children: React.ReactNode;
+}
+/**
+ * React provider that initializes evlog client-side logging.
+ * Place this in your root layout to enable client logging throughout your app.
+ *
+ * @example
+ * ```tsx
+ * // app/layout.tsx
+ * import { EvlogProvider } from 'evlog/next/client'
+ *
+ * export default function Layout({ children }) {
+ *   return (
+ *     <EvlogProvider service="my-app" transport={{ enabled: true }}>
+ *       {children}
+ *     </EvlogProvider>
+ *   )
+ * }
+ * ```
+ */
+declare function EvlogProvider({
+  service,
+  pretty,
+  transport,
+  enabled,
+  children
+}: EvlogProviderProps): react.ReactNode;
+//#endregion
+export { EvlogProvider, EvlogProviderProps, clearIdentity, _clientLog as log, setIdentity };
+//# sourceMappingURL=client.d.mts.map

package/dist/next/client.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.mts","names":[],"sources":["../../src/next/client.ts"],"mappings":";;;;;UAQiB,kBAAA;;;AAAjB;;EAKE,OAAA;EAmByB;;;;EAbzB,MAAA;EAWA;;;EANA,SAAA,GAAY,eAAA;EAQa;;AAsB3B;;EAxBE,OAAA;EAEA,QAAA,EAAU,KAAA,CAAM,SAAA;AAAA;;;;;;;;;;;;;;;;;;;iBAsBF,aAAA,CAAA;EAAgB,OAAA;EAAS,MAAA;EAAQ,SAAA;EAAW,OAAA;EAAS;AAAA,GAAY,kBAAA,GAAkB,KAAA,CAAA,SAAA"}

package/dist/next/client.mjs

@@ -0,0 +1,44 @@
+'use client';
+
+import { clearIdentity, initLog, log as _clientLog, setIdentity } from "../runtime/client/log.mjs";
+import { useEffect } from "react";
+
+//#region src/next/client.ts
+/**
+* React provider that initializes evlog client-side logging.
+* Place this in your root layout to enable client logging throughout your app.
+*
+* @example
+* ```tsx
+* // app/layout.tsx
+* import { EvlogProvider } from 'evlog/next/client'
+*
+* export default function Layout({ children }) {
+*   return (
+*     <EvlogProvider service="my-app" transport={{ enabled: true }}>
+*       {children}
+*     </EvlogProvider>
+*   )
+* }
+* ```
+*/
+function EvlogProvider({ service, pretty, transport, enabled, children }) {
+	useEffect(() => {
+		initLog({
+			enabled,
+			pretty,
+			service,
+			transport
+		});
+	}, [
+		enabled,
+		pretty,
+		service,
+		transport
+	]);
+	return children;
+}
+
+//#endregion
+export { EvlogProvider, clearIdentity, _clientLog as log, setIdentity };
+//# sourceMappingURL=client.mjs.map

package/dist/next/client.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.mjs","names":[],"sources":["../../src/next/client.ts"],"sourcesContent":["'use client'\n\nimport { useEffect } from 'react'\nimport type { TransportConfig } from '../types'\nimport { initLog, log, setIdentity, clearIdentity } from '../runtime/client/log'\n\nexport { log, setIdentity, clearIdentity } from '../runtime/client/log'\n\nexport interface EvlogProviderProps {\n  /**\n   * Service name for client-side logs.\n   * @default 'client'\n   */\n  service?: string\n\n  /**\n   * Enable pretty printing in the browser console.\n   * @default true\n   */\n  pretty?: boolean\n\n  /**\n   * Transport configuration for sending client logs to the server.\n   */\n  transport?: TransportConfig\n\n  /**\n   * Enable or disable client-side logging.\n   * @default true\n   */\n  enabled?: boolean\n\n  children: React.ReactNode\n}\n\n/**\n * React provider that initializes evlog client-side logging.\n * Place this in your root layout to enable client logging throughout your app.\n *\n * @example\n * ```tsx\n * // app/layout.tsx\n * import { EvlogProvider } from 'evlog/next/client'\n *\n * export default function Layout({ children }) {\n *   return (\n *     <EvlogProvider service=\"my-app\" transport={{ enabled: true }}>\n *       {children}\n *     </EvlogProvider>\n *   )\n * }\n * ```\n */\n// eslint-disable-next-line @typescript-eslint/naming-convention\nexport function EvlogProvider({ service, pretty, transport, enabled, children }: EvlogProviderProps) {\n  useEffect(() => {\n    initLog({\n      enabled,\n      pretty,\n      service,\n      transport,\n    })\n  }, [enabled, pretty, service, transport])\n\n  return children\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;AAsDA,SAAgB,cAAc,EAAE,SAAS,QAAQ,WAAW,SAAS,YAAgC;AACnG,iBAAgB;AACd,UAAQ;GACN;GACA;GACA;GACA;GACD,CAAC;IACD;EAAC;EAAS;EAAQ;EAAS;EAAU,CAAC;AAEzC,QAAO"}