evlog

https://www.evlog.dev/
Admin
evlog is a modern TypeScript logger that captures wide events with context, structured errors, and...
Tokens:127,378
Snippets:1,490
Trust Score:4.8
Update:3 months ago
Show doc for...
Tokens:
Raw
### Run Fastify Example Locally

Source: https://www.evlog.dev/integrate/frameworks/fastify

Commands to clone the repository, install dependencies, and start the Fastify example server.

```bash
git clone https://github.com/hugorcd/evlog.git
cd evlog
pnpm install
pnpm run example:fastify
```

--------------------------------

### Run Evlog Example Locally

Source: https://www.evlog.dev/use-cases/eve

Commands to clone the repository and start the example project.

```bash
git clone https://github.com/HugoRCD/evlog
cd evlog
pnpm install
pnpm run example:eve
```

--------------------------------

### Run TanStack Start Example Locally

Source: https://www.evlog.dev/integrate/frameworks/tanstack-start

Commands to clone the repository and start the development server for the TanStack Start integration example.

```bash
git clone https://github.com/hugorcd/evlog.git
cd evlog/examples/tanstack-start
pnpm install
pnpm run dev
```

--------------------------------

### Run SvelteKit Example Locally

Source: https://www.evlog.dev/integrate/frameworks/sveltekit

Commands to clone the repository and start the SvelteKit example application.

```bash
git clone https://github.com/hugorcd/evlog.git
cd evlog
pnpm install
pnpm run example:sveltekit
```

--------------------------------

### Run Express Example Locally

Source: https://www.evlog.dev/integrate/frameworks/express

Commands to clone the repository and start the Express example server.

```bash
git clone https://github.com/hugorcd/evlog.git
cd evlog
pnpm install
pnpm run example:express
```

--------------------------------

### Run React Router example locally

Source: https://www.evlog.dev/integrate/frameworks/react-router

Commands to clone the repository and start the React Router example environment.

```bash
git clone https://github.com/hugorcd/evlog.git
cd evlog
pnpm install
pnpm run example:react-router
```

--------------------------------

### Run Hono Example Locally

Source: https://www.evlog.dev/integrate/frameworks/hono

Commands to clone the repository and start the Hono example server.

```bash
git clone https://github.com/hugorcd/evlog.git
cd evlog
pnpm install
pnpm run example:hono
```

--------------------------------

### Local Development Setup

Source: https://www.evlog.dev/integrate/frameworks/elysia

Commands to clone the repository and run the Elysia example locally.

```bash
git clone https://github.com/hugorcd/evlog.git
cd evlog
pnpm install
pnpm run example:elysia
```

--------------------------------

### Run Next.js Example Locally

Source: https://www.evlog.dev/integrate/frameworks/nextjs

Commands to clone the repository and start the development server for the Next.js example.

```bash
git clone https://github.com/hugorcd/evlog.git
cd evlog/examples/nextjs
pnpm install
pnpm run dev
```

--------------------------------

### Run oRPC Example Locally

Source: https://www.evlog.dev/integrate/frameworks/orpc

Commands to clone the repository and start the local development environment.

```bash
git clone https://github.com/hugorcd/evlog.git
cd evlog
pnpm install
pnpm run example:orpc
```

--------------------------------

### Run NestJS Example Locally

Source: https://www.evlog.dev/integrate/frameworks/nestjs

Commands to clone the repository and execute the NestJS example application.

```bash
git clone https://github.com/hugorcd/evlog.git
cd evlog
pnpm install
pnpm run example:nestjs
```

--------------------------------

### Install evlog and eve dependencies

Source: https://www.evlog.dev/use-cases/eve

Install the required packages using your preferred package manager.

```bash
pnpm add evlog eve
```

```bash
bun add evlog eve
```

```bash
yarn add evlog eve
```

```bash
npm install evlog eve
```

--------------------------------

### Logging library migration examples

Source: https://www.evlog.dev/reference/vs-other-loggers

Examples showing how to implement a checkout flow using various logging libraries before migrating to evlog.

```javascript
import pino from 'pino'

const log = pino({ name: 'checkout' })
const child = log.child({ flow: 'checkout' })

child.info({ event: 'checkout_started' })

try {
  const cart = await getCart(userId)
  child.info({ cart: { items: cart.items.length, total: cart.total } }, 'cart loaded')

  const charge = await stripe.charge(cart.total)
  child.info({ stripe: { chargeId: charge.id } }, 'charge ok')

  if (!charge.success) {
    throw new Error(`Payment failed: ${charge.decline_reason}`)
  }
} catch (err) {
  child.error({ err }, 'checkout failed')
  throw err
}
```

```javascript
import { createLogger as createWinston, format, transports } from 'winston'

const log = createWinston({
  defaultMeta: { service: 'checkout' },
  format: format.combine(format.timestamp(), format.json()),
  transports: [new transports.Console()],
})

log.info({ event: 'checkout_started', flow: 'checkout' })

try {
  const cart = await getCart(userId)
  log.info({ flow: 'checkout', cart: { items: cart.items.length, total: cart.total } })

  const charge = await stripe.charge(cart.total)
  log.info({ flow: 'checkout', stripe: { chargeId: charge.id } })

  if (!charge.success) {
    throw new Error(`Payment failed: ${charge.decline_reason}`)
  }
} catch (err) {
  log.error({ flow: 'checkout', err })
  throw err
}
```

```javascript
import { consola } from 'consola'

const log = consola.withTag('checkout')

log.info('Starting checkout flow')

try {
  const cart = await getCart(userId)
  log.info('cart loaded', { items: cart.items.length, total: cart.total })

  const charge = await stripe.charge(cart.total)
  log.info('charge ok', { chargeId: charge.id })

  if (!charge.success) {
    throw new Error(`Payment failed: ${charge.decline_reason}`)
  }
} catch (err) {
  log.error('checkout failed', err)
  throw err
}
```

```javascript
console.log('[checkout] Starting checkout flow')

try {
  const cart = await getCart(userId)
  console.log('[checkout] cart loaded', { items: cart.items.length, total: cart.total })

  const charge = await stripe.charge(cart.total)
  console.log('[checkout] charge ok', { chargeId: charge.id })

  if (!charge.success) {
    throw new Error(`Payment failed: ${charge.decline_reason}`)
  }
} catch (err) {
  console.error('[checkout] failed', err)
  throw err
}
```

--------------------------------

### Install evlog dependencies

Source: https://www.evlog.dev/integrate/frameworks/elysia

Install the required packages using your preferred package manager.

```bash
pnpm add evlog elysia
```

```bash
bun add evlog elysia
```

```bash
yarn add evlog elysia
```

```bash
npm install evlog elysia
```

--------------------------------

### Install evlog dependencies

Source: https://www.evlog.dev/integrate/frameworks/express

Install the required packages using your preferred package manager.

```shell
pnpm add evlog express
```

```shell
bun add evlog express
```

```shell
yarn add evlog express
```

```shell
npm install evlog express
```

--------------------------------

### Install File System Adapter

Source: https://www.evlog.dev/integrate/adapters/self-hosted/fs

Import the adapter from the evlog/fs package.

```typescript
import { createFsDrain } from 'evlog/fs'
```

--------------------------------

### Install evlog and oRPC dependencies

Source: https://www.evlog.dev/integrate/frameworks/orpc

Install the required packages using your preferred package manager.

```bash
pnpm add evlog @orpc/server
```

```bash
bun add evlog @orpc/server
```

```bash
yarn add evlog @orpc/server
```

```bash
npm install evlog @orpc/server
```

--------------------------------

### Install @evlog/nuxthub dependencies

Source: https://www.evlog.dev/integrate/adapters/self-hosted/nuxthub

Install the required core and adapter packages using your preferred package manager.

```bash
pnpm add @nuxthub/core @evlog/nuxthub
```

```bash
bun add @nuxthub/core @evlog/nuxthub
```

```bash
yarn add @nuxthub/core @evlog/nuxthub
```

```bash
npm install @nuxthub/core @evlog/nuxthub
```

--------------------------------

### Wide event lifecycle example

Source: https://www.evlog.dev/reference/performance

Example of accumulating context and emitting a single wide event.

```javascript
const log = createLogger({ method: 'POST', path: '/api/checkout', requestId: 'req_abc' })
log.set({ user: { id: 'usr_123', plan: 'pro' } })
log.set({ cart: { items: 3, total: 9999 } })
log.set({ payment: { method: 'card', last4: '4242' } })
log.emit({ status: 200 })
```

--------------------------------

### Install Axiom Adapter

Source: https://www.evlog.dev/integrate/adapters/cloud/axiom

Import the Axiom drain creator from the evlog axiom package.

```typescript
import { createAxiomDrain } from 'evlog/axiom'
```

--------------------------------

### Example Client Log Output

Source: https://www.evlog.dev/use-cases/better-auth/client-sync

The resulting log structure after identity synchronization.

```json
{
  "level": "info",
  "tag": "checkout",
  "message": "User clicked checkout",
  "userId": "QBX9tPjJQExWawAbNll75",
  "userName": "Hugo Richard"
}
```

--------------------------------

### Install Better Auth dependency

Source: https://www.evlog.dev/use-cases/better-auth/overview

Install the Better Auth package using your preferred package manager.

```bash
pnpm add better-auth
```

```bash
bun add better-auth
```

```bash
yarn add better-auth
```

```bash
npm install better-auth
```

--------------------------------

### Install Sentry Adapter

Source: https://www.evlog.dev/integrate/adapters/cloud/sentry

Import the Sentry drain creator from the evlog package.

```typescript
import { createSentryDrain } from 'evlog/sentry'
```

--------------------------------

### Install evlog package

Source: https://www.evlog.dev/extend/custom-framework

Use your preferred package manager to add evlog to your project.

```shell
pnpm add evlog
```

```shell
bun add evlog
```

```shell
yarn add evlog
```

```shell
npm install evlog
```

--------------------------------

### Sampling Decision Examples

Source: https://www.evlog.dev/learn/sampling

Illustrative examples of how tail sampling rules interact with head sampling probabilities.

```text
POST /api/users     200  45ms   → 10% chance (head sampling)
POST /api/users     500  45ms   → always kept (status >= 400)
GET  /api/products  200  2300ms → always kept (duration >= 1000)
POST /api/checkout  200  120ms  → 10% chance (head sampling)
```

--------------------------------

### Install HyperDX Adapter

Source: https://www.evlog.dev/integrate/adapters/cloud/hyperdx

Import the HyperDX drain creator from the evlog package.

```typescript
import { createHyperDXDrain } from 'evlog/hyperdx'
```

--------------------------------

### Run Local OpenTelemetry Collector

Source: https://www.evlog.dev/integrate/adapters/cloud/otlp

Start the collector container using the local configuration file.

```bash
docker run --rm -p 4318:4318 \
  -v $(pwd)/otel-collector.yaml:/etc/otelcol/config.yaml \
  otel/opentelemetry-collector:latest
```

--------------------------------

### Initialize and log events in frontend applications

Source: https://www.evlog.dev/use-cases/client-logging

Examples for integrating evlog into various frontend frameworks and environments.

```typescript
import { initLog, log } from 'evlog/client'

export default defineNuxtPlugin(() => {
  initLog({ service: 'web' })

  log.info({ action: 'app_init', path: window.location.pathname })
})
```

```typescript
'use client'
import { useEffect } from 'react'
import { initLog, log } from 'evlog/client'

export function LogProvider({ children }: { children: React.ReactNode }) {
  useEffect(() => {
    initLog({ service: 'web' })
    log.info({ action: 'app_init', path: window.location.pathname })
  }, [])

  return <>{children}</>
}
```

```typescript
import { initLog, log } from 'evlog/client'

initLog({ service: 'web' })
log.info({ action: 'app_init', path: window.location.pathname })
```

--------------------------------

### Axiom Audit Query Examples

Source: https://www.evlog.dev/use-cases/audit/recipes

Example queries for analyzing audit logs within Axiom, including filtering by action and identifying denied access attempts.

```text
['audit']
| where audit.action == "invoice.refund"
| summarize count() by audit.outcome, bin(_time, 1h)
```

```text
['audit']
| where audit.outcome == "denied"
| summarize count() by audit.actor.id, audit.action
| order by count_ desc
```

--------------------------------

### Install Evlog dependencies

Source: https://www.evlog.dev/integrate/frameworks/nestjs

Install the required evlog and NestJS core packages using your preferred package manager.

```shell
pnpm add evlog @nestjs/common @nestjs/core @nestjs/platform-express
```

```shell
bun add evlog @nestjs/common @nestjs/core @nestjs/platform-express
```

```shell
yarn add evlog @nestjs/common @nestjs/core @nestjs/platform-express
```

```shell
npm install evlog @nestjs/common @nestjs/core @nestjs/platform-express
```

--------------------------------

### Implement Server Ingest Endpoint

Source: https://www.evlog.dev/extend/drain-pipeline

Example server-side implementations for receiving log batches.

```express
app.post('/v1/ingest', express.json(), (req, res) => {
  for (const entry of req.body) {
    console.log('[BROWSER]', JSON.stringify(entry))
  }
  res.sendStatus(204)
})
```

```hono
app.post('/v1/ingest', async (c) => {
  const body = await c.req.json()
  for (const entry of body) {
    console.log('[BROWSER]', JSON.stringify(entry))
  }
  return c.body(null, 204)
})
```

--------------------------------

### Log Output With Redaction

Source: https://www.evlog.dev/learn/redaction

Example of the same log entry after applying redaction settings.

```json
{
  "user": { "email": "a***@***.com", "ip": "***.***.***.42" },
  "payment": { "card": "****1111" },
  "auth": "Bearer ***"
}
```

--------------------------------

### Example Trace Context Output

Source: https://www.evlog.dev/use-cases/enrichers

A sample JSON representation of an event enriched with trace context.

```json
{
  "traceContext": {
    "traceparent": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
    "traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
    "spanId": "00f067aa0ba902b7"
  },
  "traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
  "spanId": "00f067aa0ba902b7"
}
```

--------------------------------

### Environment Variable Configuration

Source: https://www.evlog.dev/integrate/adapters/overview

Standard environment variables used for zero-config adapter setup.

```bash
# Axiom
AXIOM_API_KEY=xaat-xxx
AXIOM_DATASET=my-logs

# OTLP
OTLP_ENDPOINT=https://otlp.example.com

# HyperDX
HYPERDX_API_KEY=<YOUR_HYPERDX_API_KEY_HERE>

# PostHog
POSTHOG_API_KEY=phc_xxx

# Sentry
SENTRY_DSN=https://key@o0.ingest.sentry.io/123

# Better Stack
BETTER_STACK_API_KEY=your-source-token

# Datadog
DD_API_KEY=your-api-key
DD_SITE=datadoghq.eu
```

--------------------------------

### Install AI SDK

Source: https://www.evlog.dev/use-cases/ai-sdk/overview

Commands to add the AI SDK dependency using various package managers.

```bash
pnpm add ai
```

```bash
bun add ai
```

```bash
yarn add ai
```

```bash
npm install ai
```

--------------------------------

### Configure File System Drain

Source: https://www.evlog.dev/integrate/adapters/self-hosted/fs

Examples of initializing the file system drain with various configuration options.

```typescript
// Keep only the last 7 days of logs
createFsDrain({ maxFiles: 7 })

// Rotate files at 10MB, keep 30 files
createFsDrain({
  maxSizePerFile: 10 * 1024 * 1024,
  maxFiles: 30,
})

// Pretty-print for human reading
createFsDrain({ pretty: true })

// Custom directory
createFsDrain({ dir: '/var/log/myapp' })
```

--------------------------------

### Configure Redaction in Hono, Express, or Fastify

Source: https://www.evlog.dev/learn/redaction

Example of initializing the logger for standard Node.js frameworks.

```typescript
import { initLogger } from 'evlog'

initLogger({
  env: { service: 'my-app' },
  sampling: {
    rates: { info: 10, debug: 0 },
    keep: [{ status: 400 }, { duration: 1000 }],
  },
})
```

--------------------------------

### Implementing Wide Events

Source: https://www.evlog.dev/learn/wide-events

Examples of using evlog to accumulate context in different environments.

```typescript
import { useLogger } from 'evlog'

const log = useLogger(event)

log.set({ user: { id: 1, plan: 'pro' } })
log.set({ cart: { id: 42, items: 3, total: 9999 } })
log.set({ payment: { method: 'card', status: 'success' } })
```

```typescript
import { createLogger } from 'evlog'

const log = createLogger({ jobId: 'sync-001', queue: 'emails' })

log.set({ source: 'postgres', target: 's3' })
log.set({ records: { found: 1250, synced: 1250 } })
log.emit()
```

--------------------------------

### Install Memory Adapter

Source: https://www.evlog.dev/integrate/adapters/self-hosted/memory

Import the memory drain and log reader functions from the evlog memory module.

```typescript
import { createMemoryDrain, readMemoryLogs } from 'evlog/memory'
```

--------------------------------

### Configure Enrichers in Standalone Applications

Source: https://www.evlog.dev/use-cases/enrichers

Setup for standalone applications using the logger initialization.

```typescript
// index.ts
import { initLogger } from 'evlog'
import {
  createUserAgentEnricher,
  createGeoEnricher,
  createRequestSizeEnricher,
  createTraceContextEnricher,
} from 'evlog/enrichers'

initLogger({
  enrichers: [
    createUserAgentEnricher(),
    createGeoEnricher(),
    createRequestSizeEnricher(),
    createTraceContextEnricher(),
  ],
})
```

--------------------------------

### Standalone Stream Server Initialization

Source: https://www.evlog.dev/extend/stream

Manually start the stream server for frameworks like Hono, Express, or Fastify.

```typescript
import { startStreamServer } from 'evlog/stream'

if (process.env.NODE_ENV !== 'production' && process.env.EVLOG_STREAM === '1') {
  const { drain } = await startStreamServer()
  // Plug `drain` into the evlog drain hook for your framework
}
```

--------------------------------

### Integrate Axiom Drain with Frameworks

Source: https://www.evlog.dev/integrate/adapters/cloud/axiom

Examples of wiring the Axiom drain into various server frameworks.

```typescript
// server/plugins/evlog-drain.ts
import { createAxiomDrain } from 'evlog/axiom'

export default defineNitroPlugin((nitroApp) => {
  nitroApp.hooks.hook('evlog:drain', createAxiomDrain())
})
```

```typescript
// lib/evlog.ts
import { createEvlog } from 'evlog/next'
import { createAxiomDrain } from 'evlog/axiom'

export const { withEvlog, useLogger, log, createError } = createEvlog({
  service: 'my-app',
  drain: createAxiomDrain(),
})
```

```typescript
import { createAxiomDrain } from 'evlog/axiom'

app.use(evlog({ drain: createAxiomDrain() }))
```

```typescript
import { createAxiomDrain } from 'evlog/axiom'

app.use(evlog({ drain: createAxiomDrain() }))
```

```typescript
import { createAxiomDrain } from 'evlog/axiom'

await app.register(evlog, { drain: createAxiomDrain() })
```

```typescript
import { createAxiomDrain } from 'evlog/axiom'

app.use(evlog({ drain: createAxiomDrain() }))
```

```typescript
import { createAxiomDrain } from 'evlog/axiom'

EvlogModule.forRoot({ drain: createAxiomDrain() })
```

```typescript
import { createAxiomDrain } from 'evlog/axiom'

initLogger({ drain: createAxiomDrain() })
```

--------------------------------

### Configure Enrichers in Hono, Express, Fastify, or Elysia

Source: https://www.evlog.dev/use-cases/enrichers

General setup for various Node.js web frameworks.

```typescript
import {
  createUserAgentEnricher,
  createGeoEnricher,
  createRequestSizeEnricher,
  createTraceContextEnricher,
} from 'evlog/enrichers'

const enrichers = [
  createUserAgentEnricher(),
  createGeoEnricher(),
  createRequestSizeEnricher(),
  createTraceContextEnricher(),
]

app.use(evlog({ enrichers })) // Hono / Express / Elysia
// await app.register(evlog, { enrichers }) // Fastify
// EvlogModule.forRoot({ enrichers }) // NestJS
```

--------------------------------

### GET /

Source: https://www.evlog.dev/extend/stream

Establishes a Server-Sent Events (SSE) connection to the stream server to receive real-time application events.

```APIDOC
## GET /

### Description
Establishes a Server-Sent Events (SSE) connection to the stream server to receive real-time application events. The server streams events with the format `{ evlog: '1', type, data }`.

### Method
GET

### Endpoint
/

### Query Parameters
- **since** (string) - Optional - ISO timestamp to replay buffered events from a specific point in time.

### Response
#### Success Response (200)
- **Content-Type** (text/event-stream) - The stream of events.
```

--------------------------------

### Example User Agent event output

Source: https://www.evlog.dev/use-cases/enrichers

A sample JSON representation of the userAgent field added to a wide event.

```json
{
  "userAgent": {
    "raw": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 Chrome/120.0.0.0",
    "browser": { "name": "Chrome", "version": "120.0.0.0" },
    "os": { "name": "macOS", "version": "10.15.7" },
    "device": { "type": "desktop" }
  }
}
```

--------------------------------

### Terminal output example

Source: https://www.evlog.dev/integrate/frameworks/astro

Example of the structured log output in the terminal.

```text
14:58:15 INFO [my-astro-app] GET /api/users/usr_123
  ├─ user: id=usr_123 name=Alice plan=pro
  └─ requestId: 4a8ff3a8-...
```

--------------------------------

### Initialize Evlog via CLI

Source: https://www.evlog.dev/

Use the npx command to add the Evlog package to your project.

```bash
$ npx skills add https://www.evlog.dev
```

--------------------------------

### Compare legacy logging implementations

Source: https://www.evlog.dev/learn/simple-logging

Examples of standard logging patterns using popular Node.js libraries before migrating to evlog.

```javascript
import pino from 'pino'

const log = pino({ name: 'checkout' })

log.info({ event: 'checkout_started' })
log.info({ event: 'cart_loaded', items: 3, total: 9999 })
log.warn({ event: 'inventory_low', sku: 'SKU-42' })
log.error({ event: 'payment_failed', reason: 'card_declined' })
```

```javascript
import { createLogger, format, transports } from 'winston'

const log = createLogger({
  defaultMeta: { service: 'checkout' },
  format: format.json(),
  transports: [new transports.Console()],
})

log.info({ event: 'checkout_started' })
log.info({ event: 'cart_loaded', items: 3, total: 9999 })
log.warn({ event: 'inventory_low', sku: 'SKU-42' })
log.error({ event: 'payment_failed', reason: 'card_declined' })
```

```javascript
import { consola } from 'consola'

const log = consola.withTag('checkout')

log.info('Starting checkout')
log.info('cart loaded', { items: 3, total: 9999 })
log.warn('inventory low', { sku: 'SKU-42' })
log.error('payment failed', { reason: 'card_declined' })
```

```javascript
console.log('[checkout] Starting checkout')
console.log('[checkout] cart loaded', { items: 3, total: 9999 })
console.warn('[checkout] inventory low', { sku: 'SKU-42' })
console.error('[checkout] payment failed', { reason: 'card_declined' })
```

--------------------------------

### Run Benchmarks and Size Analysis

Source: https://www.evlog.dev/reference/performance

Commands to execute the full benchmark suite, specific comparison tests, or bundle size calculations.

```bash
cd packages/evlog

pnpm run bench                          # all benchmarks
pnpm exec vitest bench bench/comparison/ # vs alternatives only
pnpm exec tsx bench/scripts/size.ts     # bundle size
```

--------------------------------

### Initialize and use evlog

Source: https://www.evlog.dev/learn/simple-logging

The unified implementation for evlog, requiring no additional transport or formatter configuration.

```javascript
import { initLogger, log } from 'evlog'

initLogger({ env: { service: 'checkout' } })

log.info({ event: 'checkout_started' })
log.info({ event: 'cart_loaded', items: 3, total: 9999 })
log.warn({ event: 'inventory_low', sku: 'SKU-42' })
log.error({ event: 'payment_failed', reason: 'card_declined' })
```

--------------------------------

### GET /info

Source: https://www.evlog.dev/extend/stream

Retrieves handshake metadata for the stream server.

```APIDOC
## GET /info

### Description
Retrieves handshake metadata for the stream server.

### Method
GET

### Endpoint
/info

### Response
#### Success Response (200)
- **metadata** (object) - Handshake metadata including version and configuration details.
```

--------------------------------

### Log application lifecycle events

Source: https://www.evlog.dev/learn/simple-logging

Demonstrates logging server startup and connection status using the evlog library.

```typescript
import { log } from 'evlog'

log.info('app', 'Starting server on port 3000')
log.info({ action: 'db_connected', host: 'localhost', database: 'mydb', pool: 10 })
log.info('app', 'Ready to accept connections')
```

--------------------------------

### Configure Redaction in Next.js

Source: https://www.evlog.dev/learn/redaction

Example of initializing Evlog in a Next.js environment.

```typescript
import { createEvlog } from 'evlog/next'

export const { withEvlog, useLogger } = createEvlog({
  service: 'my-app',
  sampling: {
    rates: { info: 10, debug: 0 },
    keep: [{ status: 400 }, { duration: 1000 }],
  },
})
```

--------------------------------

### createAuthMiddleware(auth, options)

Source: https://www.evlog.dev/use-cases/better-auth/middleware

Initializes the authentication middleware factory. Call this once at startup and use the returned function within your framework's middleware or hook system.

```APIDOC
## createAuthMiddleware(auth, options)

### Description
Creates a middleware function that resolves sessions, identifies users, and executes lifecycle hooks. It is designed to be called once at startup and reused across requests.

### Parameters
- **auth** (object) - Required - The Better Auth instance.
- **options** (object) - Optional - Configuration object for the middleware.
  - **exclude** (string[]) - Optional - Glob patterns for routes to skip (default: ['/api/auth/**']).
  - **include** (string[]) - Optional - Glob patterns for routes to include. If set, only matching routes are resolved.
  - **maskEmail** (boolean) - Optional - Whether to mask the user email.
  - **onIdentify** (function) - Optional - Callback function (log, session) => void executed after successful identification.
  - **onAnonymous** (function) - Optional - Callback function (log) => void executed when no session is found.

### Usage Example
```typescript
import { createAuthMiddleware } from 'evlog/better-auth'

const identify = createAuthMiddleware(auth, {
  exclude: ['/api/auth/**', '/api/public/**'],
  include: ['/api/**'],
  maskEmail: true,
  onIdentify: (log, session) => {
    if (session.user.plan === 'enterprise') {
      log.set({ _forceKeep: true })
    }
  }
})
```
```

--------------------------------

### Configure Enrichers in Nitro

Source: https://www.evlog.dev/use-cases/enrichers

Setup for Nuxt/Nitro applications using a plugin.

```typescript
// server/plugins/evlog-enrich.ts
import {
  createUserAgentEnricher,
  createGeoEnricher,
  createRequestSizeEnricher,
  createTraceContextEnricher,
} from 'evlog/enrichers'

export default defineNitroPlugin((nitroApp) => {
  const enrichers = [
    createUserAgentEnricher(),
    createGeoEnricher(),
    createRequestSizeEnricher(),
    createTraceContextEnricher(),
  ]

  nitroApp.hooks.hook('evlog:enrich', (ctx) => {
    for (const enricher of enrichers) enricher(ctx)
  })
})
```

--------------------------------

### Run Worker Locally

Source: https://www.evlog.dev/integrate/frameworks/cloudflare-workers

Command to start the worker in a local development environment.

```bash
wrangler dev
```

--------------------------------

### Configure Evlog Middleware

Source: https://www.evlog.dev/reference/configuration

Examples of initializing Evlog middleware across different frameworks with route filtering, enrichment, and sampling.

```typescript
// lib/evlog.ts
import { createEvlog } from 'evlog/next'
import { createAxiomDrain } from 'evlog/axiom'

export const { withEvlog, useLogger, log, createError } = createEvlog({
  service: 'my-app',
  include: ['/api/**'],
  exclude: ['/api/health'],
  routes: { '/api/auth/**': { service: 'auth' } },
  drain: createAxiomDrain(),
  enrich: (ctx) => { ctx.event.region = process.env.FLY_REGION },
  keep: (ctx) => { if (ctx.duration > 2000) ctx.shouldKeep = true },
})
```

```javascript
app.use(evlog({
  include: ['/api/**'],
  exclude: ['/api/health'],
  routes: { '/api/auth/**': { service: 'auth' } },
  drain: createAxiomDrain(),
  enrich: (ctx) => { ctx.event.region = process.env.FLY_REGION },
  keep: (ctx) => { if (ctx.duration > 2000) ctx.shouldKeep = true },
}))
```

```javascript
app.use(evlog({
  include: ['/api/**'],
  drain: createAxiomDrain(),
  enrich: (ctx) => { ctx.event.region = process.env.FLY_REGION },
}))
```

```javascript
await app.register(evlog, {
  include: ['/api/**'],
  drain: createAxiomDrain(),
})
```

--------------------------------

### initLog(options)

Source: https://www.evlog.dev/use-cases/client-logging

Initializes the client logger with specific service settings and transport configurations.

```APIDOC
## initLog(options)

### Description
Initializes the logging system for the client application. Allows configuration of console output, log levels, and server transport.

### Parameters
- **enabled** (boolean) - Optional - Enable or disable all client logging (default: true)
- **console** (boolean) - Optional - Output logs to the browser console (default: true)
- **pretty** (boolean) - Optional - Use colored, formatted console output (default: true)
- **minLevel** (string) - Optional - Minimum severity: 'debug' < 'info' < 'warn' < 'error' (default: 'debug')
- **service** (string) - Optional - Service name included in every log event (default: 'client')
- **transport** (object) - Optional - Configuration for sending logs to a server endpoint
```

--------------------------------

### Configure Enrichers in Next.js

Source: https://www.evlog.dev/use-cases/enrichers

Setup for Next.js applications using the evlog library.

```typescript
// lib/evlog.ts
import { createEvlog } from 'evlog/next'
import {
  createUserAgentEnricher,
  createGeoEnricher,
  createRequestSizeEnricher,
  createTraceContextEnricher,
} from 'evlog/enrichers'

const enrichers = [
  createUserAgentEnricher(),
  createGeoEnricher(),
  createRequestSizeEnricher(),
  createTraceContextEnricher(),
]

export const { withEvlog, useLogger, log, createError } = createEvlog({
  service: 'my-app',
  enrich: (ctx) => {
    for (const enricher of enrichers) enricher(ctx)
  },
})
```

--------------------------------

### Example Audit Event Output

Source: https://www.evlog.dev/use-cases/audit/overview

The JSON structure of a generated audit log event.

```json
{
  "level": "info",
  "service": "billing-api",
  "method": "POST",
  "path": "/api/invoices/inv_889/refund",
  "status": 200,
  "duration": "84ms",
  "requestId": "a566ef91-7765-4f59-b6f0-b9f40ce71599",
  "audit": {
    "action": "invoice.refund",
    "actor": { "type": "user", "id": "usr_42", "email": "demo@example.com" },
    "target": { "type": "invoice", "id": "inv_889" },
    "outcome": "success",
    "reason": "Customer requested refund",
    "version": 1,
    "idempotencyKey": "ak_8f3c4b2a1e5d6f7c",
    "context": {
      "requestId": "a566ef91-7765-4f59-b6f0-b9f40ce71599",
      "ip": "203.0.113.7",
      "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36"
    }
  }
}
```

--------------------------------

### Usage of Sanitization Utilities

Source: https://www.evlog.dev/reference/best-practices

Example implementation of masking utilities within an event handler.

```typescript
import { useLogger } from 'evlog'

export default defineEventHandler(async (event) => {
  const log = useLogger(event)
  const { user, card } = await readBody(event)

  log.set({
    user: {
      id: user.id,
      email: maskEmail(user.email),
    },
    payment: {
      last4: maskCard(card.number),
      // ❌ Never: number, cvv, expiry
    },
  })
})
```

--------------------------------

### createEvlog(options)

Source: https://www.evlog.dev/integrate/frameworks/nextjs

Initializes the Evlog logger with service configuration and sampling rules.

```APIDOC
## createEvlog(options)

### Description
Initializes the Evlog logging service. Returns `withEvlog` and `useLogger` for use in the application.

### Parameters
- **service** (string) - Optional - Service name shown in logs (default: 'app')
- **environment** (string) - Optional - Environment name
- **include** (string[]) - Optional - Route patterns to log
- **exclude** (string[]) - Optional - Route patterns to exclude
- **routes** (Record<string, RouteConfig>) - Optional - Route-specific service configuration
- **sampling.rates** (object) - Optional - Head sampling rates per log level
- **sampling.keep** (array) - Optional - Tail sampling conditions
- **keep** (function) - Optional - Custom tail sampling callback
- **drain** (DrainFunction) - Optional - Drain adapter for external services
- **enrich** (function) - Optional - Event enrichment callback
```

--------------------------------

### Configure a multi-destination drain pipeline

Source: https://www.evlog.dev/extend/drain-pipeline

Setup a pipeline that fans out batches to Axiom, Datadog, Sentry, and local file system drains in parallel.

```typescript
import { createDrainPipeline } from 'evlog/pipeline'
import { createAxiomDrain } from 'evlog/axiom'
import { createDatadogDrain } from 'evlog/datadog'
import { createSentryDrain } from 'evlog/sentry'
import { createFsDrain } from 'evlog/fs'
import type { DrainContext } from 'evlog'

const pipeline = createDrainPipeline<DrainContext>({
  batch: { size: 50, intervalMs: 5000 },
  retry: { maxAttempts: 3 },
  maxBufferSize: 1000,
})

const axiom = createAxiomDrain()
const datadog = createDatadogDrain()
const sentry = createSentryDrain({ minLevel: 'error' })
const fs = createFsDrain({ dir: '.evlog/logs', maxFiles: 14 })

export const drain = pipeline(async (batch) => {
  await Promise.allSettled([
    axiom(batch),
    datadog(batch),
    sentry(batch),
    fs(batch),
  ])
})
```

--------------------------------

### Framework Integration Patterns

Source: https://www.evlog.dev/integrate/adapters/overview

Examples of passing the drain function to various web frameworks.

```typescript
// server/plugins/evlog-drain.ts
export default defineNitroPlugin((nitroApp) => {
  nitroApp.hooks.hook('evlog:drain', drain)
})
```

```typescript
// lib/evlog.ts
import { createEvlog } from 'evlog/next'

export const { withEvlog, useLogger, log, createError } = createEvlog({
  service: 'my-app',
  drain,
})
```

```typescript
app.use(evlog({ drain }))
```

```typescript
app.use(evlog({ drain }))
```

```typescript
await app.register(evlog, { drain })
```

```typescript
app.use(evlog({ drain }))
```

```typescript
EvlogModule.forRoot({ drain })
```

```typescript
initLogger({ drain })
```

--------------------------------

### Initialize Evlog Provider

Source: https://www.evlog.dev/integrate/frameworks/nextjs

Wraps the root layout with EvlogProvider to enable client-side logging and transport.

```typescript
import { EvlogProvider } from 'evlog/next/client'

export default function Layout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <EvlogProvider service="my-app" transport={{ enabled: true }}>
          {children}
        </EvlogProvider>
      </body>
    </html>
  )
}
```

--------------------------------

### Configure Evlog with Tail Sampling

Source: https://www.evlog.dev/integrate/frameworks/nextjs

Initializes Evlog with service naming, head sampling rates, and custom tail sampling rules to preserve specific log events.

```typescript
export const { withEvlog, useLogger } = createEvlog({
  service: 'my-app',
  sampling: {
    rates: { info: 10 }, // Only keep 10% of info logs
    keep: [
      { status: 400 },              // Always keep 4xx/5xx
      { duration: 1000 },           // Always keep slow requests
      { path: '/api/critical/**' }, // Always keep critical paths
    ],
  },
  // Custom: always keep premium user requests
  keep: (ctx) => {
    const user = ctx.context.user as { premium?: boolean } | undefined
    if (user?.premium) ctx.shouldKeep = true
  },
})
```

--------------------------------

### Configure Axiom Adapter in Frameworks

Source: https://www.evlog.dev/integrate/adapters/overview

Standard adapter registration for Hono, Express, Fastify, Elysia, NestJS, and Standalone environments.

```javascript
import { createAxiomDrain } from 'evlog/axiom'

app.use(evlog({ drain: createAxiomDrain() }))
```

```javascript
import { createAxiomDrain } from 'evlog/axiom'

app.use(evlog({ drain: createAxiomDrain() }))
```

```javascript
import { createAxiomDrain } from 'evlog/axiom'

await app.register(evlog, { drain: createAxiomDrain() })
```

```javascript
import { createAxiomDrain } from 'evlog/axiom'

app.use(evlog({ drain: createAxiomDrain() }))
```

```javascript
import { createAxiomDrain } from 'evlog/axiom'

EvlogModule.forRoot({ drain: createAxiomDrain() })
```

```javascript
import { createAxiomDrain } from 'evlog/axiom'

initLogger({ drain: createAxiomDrain() })
```

--------------------------------

### Example wide event output

Source: https://www.evlog.dev/integrate/frameworks/nextjs

The resulting log output after a wide event handler completes.

```text
10:23:45.612 INFO [my-app] POST /api/checkout 200 in 145ms
  ├─ user: id=usr_123 plan=enterprise
  ├─ cart: items=3 total=14999 currency=USD
  ├─ payment: method=card cardLast4=4242
  └─ requestId: a1b2c3d4-...
```

--------------------------------

### createOTLPDrain(options)

Source: https://www.evlog.dev/integrate/adapters/cloud/otlp

Initializes the OTLP drain with the provided configuration options.

```APIDOC
## createOTLPDrain(options)

### Description
Initializes an OTLP drain instance to export telemetry data. Configuration can be provided via function arguments, runtime config, or environment variables.

### Parameters
- **options** (object) - Required
  - **endpoint** (string) - Required - OTLP HTTP endpoint.
  - **serviceName** (string) - Optional - Override for the service.name resource attribute.
  - **headers** (object) - Optional - Custom HTTP headers for authentication.
  - **resourceAttributes** (object) - Optional - Additional OTLP resource attributes.
  - **timeout** (number) - Optional - Request timeout in milliseconds (default: 5000).

### Usage Example
```typescript
const drain = createOTLPDrain({
  endpoint: 'http://localhost:4318',
  serviceName: 'my-api',
  headers: {
    'Authorization': 'Bearer xxx',
  },
  resourceAttributes: {
    'deployment.environment': 'staging',
  },
})
```

--------------------------------

### View structured error terminal output

Source: https://www.evlog.dev/integrate/frameworks/express

Example of how structured errors appear in the terminal logs.

```text
14:58:20 ERROR [my-api] GET /checkout 402 in 3ms
  ├─ error: name=EvlogError message=Payment failed status=402
  └─ requestId: 880a50ac-...
```

--------------------------------

### Wire PostHog Drain to Frameworks

Source: https://www.evlog.dev/integrate/adapters/cloud/posthog

Examples of integrating the PostHog drain into various Node.js frameworks.

```typescript
// server/plugins/evlog-drain.ts
import { createPostHogDrain } from 'evlog/posthog'

export default defineNitroPlugin((nitroApp) => {
  nitroApp.hooks.hook('evlog:drain', createPostHogDrain())
})
```

```typescript
// lib/evlog.ts
import { createEvlog } from 'evlog/next'
import { createPostHogDrain } from 'evlog/posthog'

export const { withEvlog, useLogger, log, createError } = createEvlog({
  service: 'my-app',
  drain: createPostHogDrain(),
})
```

```typescript
import { createPostHogDrain } from 'evlog/posthog'

app.use(evlog({ drain: createPostHogDrain() }))
```

```typescript
import { createPostHogDrain } from 'evlog/posthog'

app.use(evlog({ drain: createPostHogDrain() }))
```

```typescript
import { createPostHogDrain } from 'evlog/posthog'

await app.register(evlog, { drain: createPostHogDrain() })
```

```typescript
import { createPostHogDrain } from 'evlog/posthog'

app.use(evlog({ drain: createPostHogDrain() }))
```

```typescript
import { createPostHogDrain } from 'evlog/posthog'

EvlogModule.forRoot({ drain: createPostHogDrain() })
```

```typescript
import { createPostHogDrain } from 'evlog/posthog'

initLogger({ drain: createPostHogDrain() })
```

--------------------------------

### initLog

Source: https://www.evlog.dev/use-cases/client-logging

Initializes the logging configuration, specifically setting the minimum log level.

```APIDOC
## initLog(options)

### Description
Initializes the logging system with a specified minimum log level.

### Parameters
- **minLevel** (string) - Optional - The minimum severity level to log. Options: 'debug', 'info', 'warn', 'error'. Default is 'debug'.
```

--------------------------------

### Wire Sentry Drain to Frameworks

Source: https://www.evlog.dev/integrate/adapters/cloud/sentry

Examples of integrating the Sentry drain into various Node.js frameworks.

```typescript
// server/plugins/evlog-drain.ts
import { createSentryDrain } from 'evlog/sentry'

export default defineNitroPlugin((nitroApp) => {
  nitroApp.hooks.hook('evlog:drain', createSentryDrain())
})
```

```typescript
// lib/evlog.ts
import { createEvlog } from 'evlog/next'
import { createSentryDrain } from 'evlog/sentry'

export const { withEvlog, useLogger, log, createError } = createEvlog({
  service: 'my-app',
  drain: createSentryDrain(),
})
```

```typescript
import { createSentryDrain } from 'evlog/sentry'

app.use(evlog({ drain: createSentryDrain() }))
```

```typescript
import { createSentryDrain } from 'evlog/sentry'

app.use(evlog({ drain: createSentryDrain() }))
```

```typescript
import { createSentryDrain } from 'evlog/sentry'

await app.register(evlog, { drain: createSentryDrain() })
```

```typescript
import { createSentryDrain } from 'evlog/sentry'

app.use(evlog({ drain: createSentryDrain() }))
```

```typescript
import { createSentryDrain } from 'evlog/sentry'

EvlogModule.forRoot({ drain: createSentryDrain() })
```

```typescript
import { createSentryDrain } from 'evlog/sentry'

initLogger({ drain: createSentryDrain() })
```
Tokens:
Raw