evlog 1.2.0 → 1.4.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.**
@@ -346,6 +347,128 @@ async function processSyncJob(job: Job) {
 }
 ```
 
+## Cloudflare Workers
+
+Use the Workers adapter for structured logs and correct platform severity.
+
+```typescript
+// src/index.ts
+import { initWorkersLogger, createWorkersLogger } from 'evlog/workers'
+
+initWorkersLogger({
+  env: { service: 'edge-api' },
+})
+
+export default {
+  async fetch(request: Request) {
+    const log = createWorkersLogger(request)
+
+    try {
+      log.set({ route: 'health' })
+      const response = new Response('ok', { status: 200 })
+      log.emit({ status: response.status })
+      return response
+    } catch (error) {
+      log.error(error as Error)
+      log.emit({ status: 500 })
+      throw error
+    }
+  },
+}
+```
+
+Disable invocation logs to avoid duplicate request logs:
+
+```toml
+# wrangler.toml
+[observability.logs]
+invocation_logs = false
+```
+
+Notes:
+- `requestId` defaults to `cf-ray` when available
+- `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)`
@@ -362,6 +485,7 @@ initLogger({
     region?: string      // Deployment region
   },
   pretty?: boolean       // Pretty print (default: true in dev)
+  stringify?: boolean    // JSON.stringify output (default: true, false for Workers)
   include?: string[]     // Route patterns to log (glob), e.g. ['/api/**']
   sampling?: {
     rates?: {            // Head sampling (random per level)
@@ -479,6 +603,34 @@ log.emit()                         // Emit final event
 log.getContext()                   // Get current context
 ```
 
+### `initWorkersLogger(options?)`
+
+Initialize evlog for Cloudflare Workers (object logs + correct severity).
+
+```typescript
+import { initWorkersLogger } from 'evlog/workers'
+
+initWorkersLogger({
+  env: { service: 'edge-api' },
+})
+```
+
+### `createWorkersLogger(request, options?)`
+
+Create a request-scoped logger for Workers. Auto-extracts `cf-ray`, `request.cf`, method, and path.
+
+```typescript
+import { createWorkersLogger } from 'evlog/workers'
+
+const log = createWorkersLogger(request, {
+  requestId: 'custom-id',      // Override cf-ray (default: cf-ray header)
+  headers: ['x-request-id'],   // Headers to include (default: none)
+})
+
+log.set({ user: { id: '123' } })
+log.emit({ status: 200 })
+```
+
 ### `createError(options)`
 
 Create a structured error with HTTP status support. Import from `evlog` directly to avoid conflicts with Nuxt/Nitro's `createError`.

package/dist/adapters/axiom.d.mts

@@ -0,0 +1,62 @@
+import { DrainContext, WideEvent } from '../types.mjs';
+
+interface AxiomConfig {
+    /** Axiom dataset name */
+    dataset: string;
+    /** Axiom API token */
+    token: string;
+    /** Organization ID (required for Personal Access Tokens) */
+    orgId?: string;
+    /** Base URL for Axiom API. Default: https://api.axiom.co */
+    baseUrl?: string;
+    /** Request timeout in milliseconds. Default: 5000 */
+    timeout?: number;
+}
+/**
+ * Create a drain function for sending logs to Axiom.
+ *
+ * Configuration priority (highest to lowest):
+ * 1. Overrides passed to createAxiomDrain()
+ * 2. runtimeConfig.evlog.axiom
+ * 3. runtimeConfig.axiom
+ * 4. Environment variables: NUXT_AXIOM_*, AXIOM_*
+ *
+ * @example
+ * ```ts
+ * // Zero config - just set NUXT_AXIOM_TOKEN and NUXT_AXIOM_DATASET env vars
+ * nitroApp.hooks.hook('evlog:drain', createAxiomDrain())
+ *
+ * // With overrides
+ * nitroApp.hooks.hook('evlog:drain', createAxiomDrain({
+ *   dataset: 'my-dataset',
+ * }))
+ * ```
+ */
+declare function createAxiomDrain(overrides?: Partial<AxiomConfig>): (ctx: DrainContext) => Promise<void>;
+/**
+ * Send a single event to Axiom.
+ *
+ * @example
+ * ```ts
+ * await sendToAxiom(event, {
+ *   dataset: 'my-logs',
+ *   token: process.env.AXIOM_TOKEN!,
+ * })
+ * ```
+ */
+declare function sendToAxiom(event: WideEvent, config: AxiomConfig): Promise<void>;
+/**
+ * Send a batch of events to Axiom.
+ *
+ * @example
+ * ```ts
+ * await sendBatchToAxiom(events, {
+ *   dataset: 'my-logs',
+ *   token: process.env.AXIOM_TOKEN!,
+ * })
+ * ```
+ */
+declare function sendBatchToAxiom(events: WideEvent[], config: AxiomConfig): Promise<void>;
+
+export { createAxiomDrain, sendBatchToAxiom, sendToAxiom };
+export type { AxiomConfig };

package/dist/adapters/axiom.d.ts

@@ -0,0 +1,62 @@
+import { DrainContext, WideEvent } from '../types.js';
+
+interface AxiomConfig {
+    /** Axiom dataset name */
+    dataset: string;
+    /** Axiom API token */
+    token: string;
+    /** Organization ID (required for Personal Access Tokens) */
+    orgId?: string;
+    /** Base URL for Axiom API. Default: https://api.axiom.co */
+    baseUrl?: string;
+    /** Request timeout in milliseconds. Default: 5000 */
+    timeout?: number;
+}
+/**
+ * Create a drain function for sending logs to Axiom.
+ *
+ * Configuration priority (highest to lowest):
+ * 1. Overrides passed to createAxiomDrain()
+ * 2. runtimeConfig.evlog.axiom
+ * 3. runtimeConfig.axiom
+ * 4. Environment variables: NUXT_AXIOM_*, AXIOM_*
+ *
+ * @example
+ * ```ts
+ * // Zero config - just set NUXT_AXIOM_TOKEN and NUXT_AXIOM_DATASET env vars
+ * nitroApp.hooks.hook('evlog:drain', createAxiomDrain())
+ *
+ * // With overrides
+ * nitroApp.hooks.hook('evlog:drain', createAxiomDrain({
+ *   dataset: 'my-dataset',
+ * }))
+ * ```
+ */
+declare function createAxiomDrain(overrides?: Partial<AxiomConfig>): (ctx: DrainContext) => Promise<void>;
+/**
+ * Send a single event to Axiom.
+ *
+ * @example
+ * ```ts
+ * await sendToAxiom(event, {
+ *   dataset: 'my-logs',
+ *   token: process.env.AXIOM_TOKEN!,
+ * })
+ * ```
+ */
+declare function sendToAxiom(event: WideEvent, config: AxiomConfig): Promise<void>;
+/**
+ * Send a batch of events to Axiom.
+ *
+ * @example
+ * ```ts
+ * await sendBatchToAxiom(events, {
+ *   dataset: 'my-logs',
+ *   token: process.env.AXIOM_TOKEN!,
+ * })
+ * ```
+ */
+declare function sendBatchToAxiom(events: WideEvent[], config: AxiomConfig): Promise<void>;
+
+export { createAxiomDrain, sendBatchToAxiom, sendToAxiom };
+export type { AxiomConfig };

package/dist/adapters/axiom.mjs

@@ -0,0 +1,65 @@
+function getRuntimeConfig() {
+  try {
+    const { useRuntimeConfig } = require("nitropack/runtime");
+    return useRuntimeConfig();
+  } catch {
+    return void 0;
+  }
+}
+function createAxiomDrain(overrides) {
+  return async (ctx) => {
+    const runtimeConfig = getRuntimeConfig();
+    const evlogAxiom = runtimeConfig?.evlog?.axiom;
+    const rootAxiom = runtimeConfig?.axiom;
+    const config = {
+      dataset: overrides?.dataset ?? evlogAxiom?.dataset ?? rootAxiom?.dataset ?? process.env.NUXT_AXIOM_DATASET ?? process.env.AXIOM_DATASET,
+      token: overrides?.token ?? evlogAxiom?.token ?? rootAxiom?.token ?? process.env.NUXT_AXIOM_TOKEN ?? process.env.AXIOM_TOKEN,
+      orgId: overrides?.orgId ?? evlogAxiom?.orgId ?? rootAxiom?.orgId ?? process.env.NUXT_AXIOM_ORG_ID ?? process.env.AXIOM_ORG_ID,
+      baseUrl: overrides?.baseUrl ?? evlogAxiom?.baseUrl ?? rootAxiom?.baseUrl ?? process.env.NUXT_AXIOM_URL ?? process.env.AXIOM_URL,
+      timeout: overrides?.timeout ?? evlogAxiom?.timeout ?? rootAxiom?.timeout
+    };
+    if (!config.dataset || !config.token) {
+      console.error("[evlog/axiom] Missing dataset or token. Set NUXT_AXIOM_TOKEN/NUXT_AXIOM_DATASET env vars or pass to createAxiomDrain()");
+      return;
+    }
+    try {
+      await sendToAxiom(ctx.event, config);
+    } catch (error) {
+      console.error("[evlog/axiom] Failed to send event:", error);
+    }
+  };
+}
+async function sendToAxiom(event, config) {
+  await sendBatchToAxiom([event], config);
+}
+async function sendBatchToAxiom(events, config) {
+  const baseUrl = config.baseUrl ?? "https://api.axiom.co";
+  const timeout = config.timeout ?? 5e3;
+  const url = `${baseUrl}/v1/datasets/${encodeURIComponent(config.dataset)}/ingest`;
+  const headers = {
+    "Content-Type": "application/json",
+    "Authorization": `Bearer ${config.token}`
+  };
+  if (config.orgId) {
+    headers["X-Axiom-Org-Id"] = config.orgId;
+  }
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), timeout);
+  try {
+    const response = await fetch(url, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(events),
+      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(`Axiom API error: ${response.status} ${response.statusText} - ${safeText}`);
+    }
+  } finally {
+    clearTimeout(timeoutId);
+  }
+}
+
+export { createAxiomDrain, sendBatchToAxiom, sendToAxiom };

package/dist/adapters/otlp.d.mts

@@ -0,0 +1,83 @@
+import { DrainContext, WideEvent } from '../types.mjs';
+
+interface OTLPConfig {
+    /** OTLP HTTP endpoint (e.g., http://localhost:4318) */
+    endpoint: string;
+    /** Override service name (defaults to event.service) */
+    serviceName?: string;
+    /** Additional resource attributes */
+    resourceAttributes?: Record<string, string | number | boolean>;
+    /** Custom headers (e.g., for authentication) */
+    headers?: Record<string, string>;
+    /** Request timeout in milliseconds. Default: 5000 */
+    timeout?: number;
+}
+/** OTLP Log Record structure */
+interface OTLPLogRecord {
+    timeUnixNano: string;
+    severityNumber: number;
+    severityText: string;
+    body: {
+        stringValue: string;
+    };
+    attributes: Array<{
+        key: string;
+        value: {
+            stringValue?: string;
+            intValue?: string;
+            boolValue?: boolean;
+        };
+    }>;
+    traceId?: string;
+    spanId?: string;
+}
+/**
+ * Convert an evlog WideEvent to an OTLP LogRecord.
+ */
+declare function toOTLPLogRecord(event: WideEvent): OTLPLogRecord;
+/**
+ * Create a drain function for sending logs to an OTLP endpoint.
+ *
+ * Configuration priority (highest to lowest):
+ * 1. Overrides passed to createOTLPDrain()
+ * 2. runtimeConfig.evlog.otlp (NUXT_EVLOG_OTLP_*)
+ * 3. runtimeConfig.otlp (NUXT_OTLP_*)
+ * 4. Environment variables: OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_SERVICE_NAME
+ *
+ * @example
+ * ```ts
+ * // Zero config - reads from runtimeConfig or env vars
+ * nitroApp.hooks.hook('evlog:drain', createOTLPDrain())
+ *
+ * // With overrides
+ * nitroApp.hooks.hook('evlog:drain', createOTLPDrain({
+ *   endpoint: 'http://localhost:4318',
+ * }))
+ * ```
+ */
+declare function createOTLPDrain(overrides?: Partial<OTLPConfig>): (ctx: DrainContext) => Promise<void>;
+/**
+ * Send a single event to an OTLP endpoint.
+ *
+ * @example
+ * ```ts
+ * await sendToOTLP(event, {
+ *   endpoint: 'http://localhost:4318',
+ * })
+ * ```
+ */
+declare function sendToOTLP(event: WideEvent, config: OTLPConfig): Promise<void>;
+/**
+ * Send a batch of events to an OTLP endpoint.
+ *
+ * @example
+ * ```ts
+ * await sendBatchToOTLP(events, {
+ *   endpoint: 'http://localhost:4318',
+ * })
+ * ```
+ */
+declare function sendBatchToOTLP(events: WideEvent[], config: OTLPConfig): Promise<void>;
+
+export { createOTLPDrain, sendBatchToOTLP, sendToOTLP, toOTLPLogRecord };
+export type { OTLPConfig, OTLPLogRecord };

package/dist/adapters/otlp.d.ts

@@ -0,0 +1,83 @@
+import { DrainContext, WideEvent } from '../types.js';
+
+interface OTLPConfig {
+    /** OTLP HTTP endpoint (e.g., http://localhost:4318) */
+    endpoint: string;
+    /** Override service name (defaults to event.service) */
+    serviceName?: string;
+    /** Additional resource attributes */
+    resourceAttributes?: Record<string, string | number | boolean>;
+    /** Custom headers (e.g., for authentication) */
+    headers?: Record<string, string>;
+    /** Request timeout in milliseconds. Default: 5000 */
+    timeout?: number;
+}
+/** OTLP Log Record structure */
+interface OTLPLogRecord {
+    timeUnixNano: string;
+    severityNumber: number;
+    severityText: string;
+    body: {
+        stringValue: string;
+    };
+    attributes: Array<{
+        key: string;
+        value: {
+            stringValue?: string;
+            intValue?: string;
+            boolValue?: boolean;
+        };
+    }>;
+    traceId?: string;
+    spanId?: string;
+}
+/**
+ * Convert an evlog WideEvent to an OTLP LogRecord.
+ */
+declare function toOTLPLogRecord(event: WideEvent): OTLPLogRecord;
+/**
+ * Create a drain function for sending logs to an OTLP endpoint.
+ *
+ * Configuration priority (highest to lowest):
+ * 1. Overrides passed to createOTLPDrain()
+ * 2. runtimeConfig.evlog.otlp (NUXT_EVLOG_OTLP_*)
+ * 3. runtimeConfig.otlp (NUXT_OTLP_*)
+ * 4. Environment variables: OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_SERVICE_NAME
+ *
+ * @example
+ * ```ts
+ * // Zero config - reads from runtimeConfig or env vars
+ * nitroApp.hooks.hook('evlog:drain', createOTLPDrain())
+ *
+ * // With overrides
+ * nitroApp.hooks.hook('evlog:drain', createOTLPDrain({
+ *   endpoint: 'http://localhost:4318',
+ * }))
+ * ```
+ */
+declare function createOTLPDrain(overrides?: Partial<OTLPConfig>): (ctx: DrainContext) => Promise<void>;
+/**
+ * Send a single event to an OTLP endpoint.
+ *
+ * @example
+ * ```ts
+ * await sendToOTLP(event, {
+ *   endpoint: 'http://localhost:4318',
+ * })
+ * ```
+ */
+declare function sendToOTLP(event: WideEvent, config: OTLPConfig): Promise<void>;
+/**
+ * Send a batch of events to an OTLP endpoint.
+ *
+ * @example
+ * ```ts
+ * await sendBatchToOTLP(events, {
+ *   endpoint: 'http://localhost:4318',
+ * })
+ * ```
+ */
+declare function sendBatchToOTLP(events: WideEvent[], config: OTLPConfig): Promise<void>;
+
+export { createOTLPDrain, sendBatchToOTLP, sendToOTLP, toOTLPLogRecord };
+export type { OTLPConfig, OTLPLogRecord };