# Wide Events Guide

Wide events are comprehensive log entries that capture all context for a single logical operation (usually a request) in one place.

## Why Wide Events?

Traditional logging scatters information across many log lines:

```
10:23:45.001 Request received POST /checkout
10:23:45.012 User authenticated: user_123
10:23:45.045 Cart loaded: 3 items, $99.99
10:23:45.089 Payment initiated: Stripe
10:23:45.234 Payment failed: card_declined
10:23:45.235 Request completed: 500
```

During an incident, you're grep-ing through thousands of these trying to reconstruct what happened.

**Wide events emit once with everything:**

Development (pretty format):

```
10:23:45.235 ERROR [api] POST /checkout 500 in 234ms
  ├─ user: id=user_123 plan=premium accountAge=847
  ├─ cart: items=3 total=9999
  ├─ payment: provider=stripe method=card
  └─ error: code=card_declined retriable=false
```

Production (JSON format):

```json
{
  "timestamp": "2025-01-24T10:23:45.235Z",
  "level": "error",
  "service": "api",
  "method": "POST",
  "path": "/checkout",
  "duration": "234ms",
  "user": { "id": "user_123", "plan": "premium", "accountAge": 847 },
  "cart": { "items": 3, "total": 9999 },
  "payment": { "provider": "stripe", "method": "card" },
  "error": { "code": "card_declined", "retriable": false }
}
```

## When to Use Wide Events

| Scenario                      | Use Wide Event?                   |
| ----------------------------- | --------------------------------- |
| HTTP request handling         | Yes - one event per request       |
| Background job execution      | Yes - one event per job           |
| Database query                | No - use simple log               |
| Cache hit/miss                | No - include in parent wide event |
| User action (login, checkout) | Yes - one event per action        |
| Debug statements              | No - remove in production         |

## Required Fields

Every wide event should include:

### Request Context

```typescript
log.set({
  method: "POST",
  path: "/api/checkout",
  requestId: "req_abc123", // For tracing
  traceId: "trace_xyz", // Distributed tracing
});
```

### User Context

```typescript
log.set({
  user: {
    id: "user_123",
    plan: "premium", // Business-relevant
    accountAge: 847, // Days since signup
    subscription: "annual",
  },
});
```

### Business Context

Add domain-specific data relevant to the operation:

```typescript
// E-commerce checkout
log.set({
  cart: { id: "cart_xyz", items: 3, total: 9999 },
  payment: { method: "card", provider: "stripe" },
  order: { id: "order_123", status: "created" },
});

// API rate limiting
log.set({
  rateLimit: {
    limit: 1000,
    remaining: 42,
    resetAt: "2025-01-24T11:00:00Z",
  },
});

// File upload
log.set({
  upload: {
    filename: "document.pdf",
    size: 1024000,
    mimeType: "application/pdf",
  },
});
```

### Outcome

```typescript
// Success
log.set({
  status: 200,
  // duration is added automatically by emit()
});

// Error
log.error(error, {
  step: "payment",
  retriable: false,
});
```

## Pattern: Request Logger in API Routes

### Nuxt/Nitro (Recommended)

With the evlog module, use `useLogger(event)` - it's auto-created and auto-emitted:

```typescript
// server/api/checkout.post.ts
// Nuxt: useLogger and createError are auto-imported
// Nitro v3: import { useLogger } from 'evlog/nitro/v3'
// Nitro v2: import { useLogger } from 'evlog/nitro'
import { createError } from "evlog";

export default defineEventHandler(async (event) => {
  const log = useLogger(event); // Auto-created by evlog

  const user = await requireAuth(event);
  log.set({ user: { id: user.id, plan: user.plan } });

  const cart = await getCart(user.id);
  log.set({ cart: { items: cart.items.length, total: cart.total } });

  try {
    const payment = await processPayment(cart, user);
    log.set({ payment: { id: payment.id, method: payment.method } });
  } catch (error) {
    log.error(error, { step: "payment" });
    throw createError({
      message: "Payment failed",
      why: error.message,
      fix: "Try a different payment method",
    });
  }

  const order = await createOrder(cart, user);
  log.set({ order: { id: order.id, status: order.status } });

  return order;
  // log.emit() is called automatically at request end
});
```

### Standalone TypeScript (Scripts, Workers)

Without Nuxt/Nitro, use `createRequestLogger()` and call `emit()` manually:

```typescript
// scripts/sync-job.ts
import { initLogger, createRequestLogger } from "evlog";

initLogger({ env: { service: "sync-worker", environment: "production" } });

async function processJob(job: Job) {
  const log = createRequestLogger({ jobId: job.id, type: "sync" });

  try {
    log.set({ source: job.source, target: job.target });

    const result = await performSync(job);
    log.set({ recordsSynced: result.count });

    return result;
  } catch (error) {
    log.error(error, { step: "sync" });
    throw error;
  } finally {
    log.emit(); // Manual emit required
  }
}
```

## Transformation Examples

### Before: Console.log Spam

```typescript
// server/api/checkout.post.ts

export default defineEventHandler(async (event) => {
  console.log("Checkout started");

  const user = await getUser(event);
  console.log("User loaded:", user.id);

  const cart = await getCart(user.id);
  console.log("Cart loaded:", cart.items.length, "items");

  try {
    const payment = await processPayment(cart);
    console.log("Payment successful:", payment.id);
    return { orderId: payment.orderId };
  } catch (error) {
    console.error("Payment failed:", error.message);
    throw error;
  }
});
```

### After: Single Wide Event

```typescript
// server/api/checkout.post.ts
// Nuxt: useLogger and createError are auto-imported
// Nitro v3: import { useLogger } from 'evlog/nitro/v3'
// Nitro v2: import { useLogger } from 'evlog/nitro'
import { createError } from "evlog";

export default defineEventHandler(async (event) => {
  const log = useLogger(event);

  const user = await getUser(event);
  log.set({ user: { id: user.id, plan: user.plan } });

  const cart = await getCart(user.id);
  log.set({ cart: { items: cart.items.length, total: cart.total } });

  try {
    const payment = await processPayment(cart);
    log.set({ payment: { id: payment.id }, order: { id: payment.orderId } });

    return { orderId: payment.orderId };
  } catch (error) {
    log.error(error, { step: "payment" });
    throw createError({
      message: "Payment failed",
      why: error.message,
      fix: "Try a different payment method",
    });
  }
  // emit() called automatically
});
```

## Best Practices

### Do

- Include business-relevant context (user plan, cart value, etc.)
- Add enough context to debug without looking elsewhere
- Use consistent field names across your codebase
- Let `emit()` calculate duration automatically

### Don't

- Log sensitive data (passwords, tokens, full credit card numbers)
- Create multiple wide events for one logical operation
- Forget to call `emit()` (or use the Nuxt module for auto-emit)
- Include debugging logs inside wide events (remove them)

## Security: Preventing Sensitive Data Leakage

Always explicitly select which fields to log:

```typescript
// ❌ DANGEROUS - logs everything including password
log.set({ user: body });

// ✅ SAFE - explicitly select fields
log.set({
  user: {
    id: body.id,
    email: maskEmail(body.email),
    // password: body.password ← NEVER include
  },
});
```

**Never log:** passwords, API keys, tokens, secrets, full card numbers, CVV, SSN, PII, session tokens, JWTs.

**Sanitization helpers:**

```typescript
// server/utils/sanitize.ts
export function maskEmail(email: string): string {
  const [local, domain] = email.split("@");
  if (!domain) return "***";
  return `${local[0]}***@${domain[0]}***.${domain.split(".")[1]}`;
}

export function maskCard(card: string): string {
  return `****${card.slice(-4)}`;
}
```

See [code-review.md](code-review.md) for the full security review checklist.

## Field Naming Conventions

Use consistent, descriptive field names:

```typescript
// ✅ Good - grouped, descriptive
log.set({
  user: { id, plan, accountAge },
  cart: { items, total },
  payment: { method, provider },
});

// ❌ Bad - flat, abbreviated
log.set({
  uid: "123",
  n: 3,
  t: 9999,
  pm: "card",
});
```