Wide Events

1// Traditional approach - context is scattered
2log.info('Request received', { method: 'POST', path: '/checkout' })
3log.debug('User authenticated', { userId: 'user-123' })
4log.debug('Cart loaded', { items: 3 })
5log.info('Payment started', { amount: 9999 })
6log.debug('Stripe API called', { duration: 230 })
7log.info('Order created', { orderId: 'order-456' })
8log.info('Request completed', { duration: 850 })

1import { createLogger, createWideEvent } from 'vestig'
2 
3const logger = createLogger()
4 
5// Create the event at request start
6const event = createWideEvent({ type: 'http.request' })
7 
8// Enrich throughout the request lifecycle
9event.merge('http', { method: 'POST', path: '/checkout', status_code: 200 })
10event.merge('user', { id: 'user-123', subscription: 'premium' })
11event.merge('cart', { items: 3, total: 9999 })
12event.merge('payment', { provider: 'stripe', status: 'succeeded' })
13event.merge('performance', { stripe_api_ms: 230, db_query_ms: 45 })
14 
15// Emit once at the end
16logger.emitWideEvent(event.end({ status: 'success' }))

1{
2  "event_type": "http.request",
3  "status": "success",
4  "duration_ms": 850,
5  "http.method": "POST",
6  "http.path": "/checkout",
7  "http.status_code": 200,
8  "user.id": "user-123",
9  "user.subscription": "premium",
10  "cart.items": 3,
11  "payment.provider": "stripe",
12  "performance.stripe_api_ms": 230
13}

1const event = createWideEvent({
2  type: 'http.request',  // Event type identifier
3  context: {             // Optional correlation context
4    requestId: 'req-abc',
5    traceId: 'trace-xyz',
6  },
7})

1// Set a single field
2event.set('http', 'method', 'POST')
3 
4// Merge multiple fields into a category
5event.merge('user', {
6  id: 'user-123',
7  email: 'user@example.com',
8  subscription: 'premium',
9})
10 
11// Merge multiple categories at once
12event.mergeAll({
13  http: { method: 'POST', path: '/api' },
14  user: { id: 'user-123' },
15})
16 
17// Get a field value
18const method = event.get('http', 'method')
19 
20// Set context (requestId, traceId, etc.)
21event.setContext({ userId: 'user-123' })
22 
23// Get current context
24const ctx = event.getContext()
25 
26// Get all fields
27const fields = event.getFields()
28 
29// Convert to flat metadata (for traditional logging)
30const metadata = event.toMetadata()

1const completedEvent = event.end({
2  status: 'success',      // 'success' | 'error' | 'timeout' | 'cancelled'
3  level: 'info',          // Log level for emission
4  error: new Error('...'), // Optional error to attach
5  fields: { ... },        // Optional final fields to merge
6})

1const logger = createLogger()
2logger.emitWideEvent(completedEvent)

1// HTTP context
2event.merge('http', {
3  method: 'POST',
4  path: '/api/checkout',
5  status_code: 200,
6  request_size: 1234,
7  response_size: 567,
8})
9 
10// User context
11event.merge('user', {
12  id: 'user-123',
13  email: 'user@example.com',
14  subscription: 'premium',
15  role: 'admin',
16})
17 
18// Performance metrics
19event.merge('performance', {
20  db_query_ms: 45,
21  external_api_ms: 230,
22  cache_hit: true,
23})
24 
25// Business metrics
26event.merge('order', {
27  id: 'order-456',
28  items: 3,
29  total: 9999,
30  currency: 'usd',
31})
32 
33// Feature flags
34event.merge('feature_flags', {
35  new_checkout: true,
36  beta_features: false,
37})
38 
39// Error context (when things go wrong)
40event.merge('error', {
41  type: 'PaymentFailed',
42  code: 'card_declined',
43  retry_count: 2,
44})

1import type { HttpRequestEventFields } from 'vestig'
2 
3// Type-safe field structure
4const fields: HttpRequestEventFields = {
5  http: {
6    method: 'POST',
7    path: '/api/users',
8    status_code: 201,
9    request_size: 1024,
10  },
11  user: {
12    id: 'user-123',
13    subscription: 'premium',
14  },
15  performance: {
16    total_ms: 150,
17    db_ms: 45,
18  },
19}

1import type { BackgroundJobEventFields } from 'vestig'
2 
3const fields: BackgroundJobEventFields = {
4  job: {
5    id: 'job-789',
6    type: 'email.send',
7    queue: 'emails',
8    attempts: 1,
9  },
10  performance: {
11    duration_ms: 230,
12    memory_mb: 64,
13  },
14}

1export async function handleRequest(req: Request) {
2  // Create at the start
3  const event = createWideEvent({ type: 'http.request' })
4 
5  try {
6    // Enrich as you process
7    event.merge('http', extractHttpContext(req))
8 
9    const user = await authenticate(req)
10    event.merge('user', { id: user.id, tier: user.tier })
11 
12    const result = await processRequest(req, user)
13    event.merge('result', result.metadata)
14 
15    return Response.json(result)
16  } finally {
17    // Always emit, even on error
18    logger.emitWideEvent(event.end({ status: 'success' }))
19  }
20}

1try {
2  await processPayment(order)
3} catch (error) {
4  event.merge('error', {
5    type: error.name,
6    message: error.message,
7    code: error.code,
8  })
9 
10  logger.emitWideEvent(event.end({
11    status: 'error',
12    error,
13    level: 'error',
14  }))
15 
16  throw error
17}

1// Good: Consistent naming
2event.set('performance', 'db_query_ms', 45)
3event.set('performance', 'api_call_ms', 230)
4event.set('performance', 'total_ms', 850)
5 
6// Bad: Inconsistent naming
7event.set('perf', 'dbTime', 45)
8event.set('metrics', 'apiDuration', 230)
9event.set('timing', 'totalDuration', 850)

1// Include what matters for your business
2event.merge('business', {
3  revenue: order.total,
4  customer_type: user.tier,
5  promotion_code: order.promoCode,
6  is_first_purchase: user.orderCount === 0,
7})

1import { createLogger, createWideEvent } from 'vestig'
2 
3const logger = createLogger({
4  tailSampling: {
5    enabled: true,
6    alwaysKeepStatuses: ['error'],
7    slowThresholdMs: 2000,
8    successSampleRate: 0.1,
9  },
10})
11 
12export async function checkout(req: Request) {
13  const event = createWideEvent({
14    type: 'http.request',
15    context: { requestId: crypto.randomUUID() },
16  })
17 
18  try {
19    // HTTP context
20    event.merge('http', {
21      method: req.method,
22      path: new URL(req.url).pathname,
23    })
24 
25    // Authenticate
26    const user = await auth.verify(req)
27    event.merge('user', {
28      id: user.id,
29      subscription: user.subscription,
30      country: user.country,
31    })
32 
33    // Load cart
34    const startDb = performance.now()
35    const cart = await db.carts.get(user.id)
36    event.set('performance', 'db_cart_ms', performance.now() - startDb)
37    event.merge('cart', {
38      items: cart.items.length,
39      total: cart.total,
40    })
41 
42    // Process payment
43    const startPayment = performance.now()
44    const payment = await stripe.charge(cart)
45    event.set('performance', 'stripe_ms', performance.now() - startPayment)
46    event.merge('payment', {
47      provider: 'stripe',
48      status: payment.status,
49      amount: payment.amount,
50    })
51 
52    // Create order
53    const order = await db.orders.create({ user, cart, payment })
54    event.merge('order', {
55      id: order.id,
56      items: order.items.length,
57    })
58 
59    event.set('http', 'status_code', 201)
60    logger.emitWideEvent(event.end({ status: 'success' }))
61 
62    return Response.json({ orderId: order.id }, { status: 201 })
63 
64  } catch (error) {
65    event.set('http', 'status_code', 500)
66    event.merge('error', {
67      type: error.name,
68      message: error.message,
69    })
70 
71    logger.emitWideEvent(event.end({
72      status: 'error',
73      error,
74      level: 'error',
75    }))
76 
77    return Response.json({ error: 'Checkout failed' }, { status: 500 })
78  }
79}