Context Propagation

Vestig provides powerful context propagation using AsyncLocalStorage, ensuring your logging context flows through your entire request lifecycle without manual passing.

Overview

Context propagation solves a fundamental problem: how do you attach metadata (like request IDs, user info) to all logs within a request without passing context through every function?

typescript

1import { withContext, log } from 'vestig'
2 
3// All logs inside this callback automatically include the context
4await withContext({ requestId: 'req-123', userId: 'user-456' }, async () => {
5  log.info('Starting request')          // Includes requestId, userId
6  await processOrder()                   // Any logs here too!
7  log.info('Request completed')          // And here!
8})

How It Works

Vestig uses AsyncLocalStorage (available in Node.js, Bun, and Deno) to maintain context across async boundaries:

text

1+----------------------------------------------------------+
2|                    Request Lifecycle                      |
3+----------------------------------------------------------+
4|                                                           |
5|  withContext({ requestId: 'req-123' }, async () => {     |
6|    |                                                      |
7|    +-- log.info('A')  ----------> { requestId: 'req-123' }|
8|    |                                                      |
9|    +-- await asyncOperation()                             |
10|    |     |                                                |
11|    |     +-- log.info('B')  ---> { requestId: 'req-123' } |
12|    |                                                      |
13|    +-- log.info('C')  ----------> { requestId: 'req-123' }|
14|                                                           |
15+----------------------------------------------------------+

Basic Usage

Setting Context

typescript

1import { withContext, log } from 'vestig'
2 
3// Synchronous callback
4withContext({ userId: 'user-123' }, () => {
5  log.info('User action')
6  // All logs include userId
7})
8 
9// Async callback
10await withContext({ requestId: 'req-456' }, async () => {
11  const data = await fetchData()
12  log.info('Data fetched', { count: data.length })
13  // Logs include requestId
14})

Reading Context

typescript

1import { getContext, log } from 'vestig'
2 
3function logWithContext(message: string) {
4  const ctx = getContext()
5  console.log('Current context:', ctx)
6  // { requestId: 'req-123', userId: 'user-456', ... }
7 
8  log.info(message) // Context automatically included
9}

Nested Context

Context can be nested, with inner contexts merging with outer:

typescript

1import { withContext, log } from 'vestig'
2 
3await withContext({ requestId: 'req-123' }, async () => {
4  log.info('Outer context')
5  // { requestId: 'req-123' }
6 
7  await withContext({ operation: 'checkout' }, async () => {
8    log.info('Inner context')
9    // { requestId: 'req-123', operation: 'checkout' }
10  })
11 
12  log.info('Back to outer')
13  // { requestId: 'req-123' }
14})

Correlation Context

Vestig provides a specialized correlation context for request tracing:

typescript

1import { createCorrelationContext, withContext } from 'vestig'
2 
3// Create correlation context with auto-generated IDs
4const correlationContext = createCorrelationContext({
5  service: 'api',
6  environment: 'production'
7})
8 
9// correlationContext includes:
10// - correlationId: auto-generated UUID
11// - requestId: auto-generated UUID
12// - timestamp: ISO string
13// - service: 'api'
14// - environment: 'production'
15 
16await withContext(correlationContext, async () => {
17  // All logs include correlation IDs
18})

Custom Correlation IDs

typescript

1import { createCorrelationContext } from 'vestig'
2 
3// Use existing correlation ID from upstream service
4const ctx = createCorrelationContext({
5  correlationId: req.headers['x-correlation-id'],
6  requestId: req.headers['x-request-id'],
7  service: 'payment-service'
8})

Context with Child Loggers

Child loggers inherit context from the current scope:

typescript

1import { log, withContext } from 'vestig'
2 
3const orderLogger = log.child('orders')
4 
5await withContext({ orderId: 'order-789' }, async () => {
6  orderLogger.info('Processing order')
7  // namespace: 'orders'
8  // orderId: 'order-789'
9 
10  const paymentLogger = orderLogger.child('payment')
11  paymentLogger.info('Charging card')
12  // namespace: 'orders.payment'
13  // orderId: 'order-789'
14})

Context with Spans

Spans automatically include the current context:

typescript

1import { span, withContext, log } from 'vestig'
2 
3await withContext({ userId: 'user-123' }, async () => {
4  await span('process-order', async (s) => {
5    // Span has access to context
6    s.setAttribute('userId', 'user-123') // Explicit
7 
8    log.info('Processing')
9    // Log includes: userId, traceId, spanId
10  })
11})

HTTP Request Context

Express.js

typescript

1import express from 'express'
2import { withContext, createCorrelationContext } from 'vestig'
3 
4const app = express()
5 
6app.use((req, res, next) => {
7  const ctx = createCorrelationContext({
8    correlationId: req.headers['x-correlation-id'] as string,
9    method: req.method,
10    path: req.path,
11    userAgent: req.headers['user-agent']
12  })
13 
14  withContext(ctx, () => {
15    next()
16  })
17})
18 
19app.get('/api/orders', async (req, res) => {
20  // All logs automatically include request context
21  log.info('Fetching orders')
22  const orders = await getOrders()
23  res.json(orders)
24})

Next.js

With @vestig/next, context is automatically set up:

typescript

1// middleware.ts
2import { withVestig } from '@vestig/next/middleware'
3 
4export const middleware = withVestig((request) => {
5  // Context automatically includes:
6  // - correlationId
7  // - requestId
8  // - method, path, userAgent
9})
10 
11// In route handlers, context is available
12import { getRequestContext } from '@vestig/next'
13 
14export async function GET() {
15  const ctx = await getRequestContext()
16  // { correlationId, requestId, method, path, ... }
17}

Browser Context

In browsers (where AsyncLocalStorage isn't available), Vestig uses a fallback:

typescript

1import { withContext, log } from 'vestig'
2 
3// Works the same way in browsers
4withContext({ sessionId: 'sess-123' }, () => {
5  log.info('User clicked button')
6  // Includes sessionId
7})

Note: Browser context doesn't persist across async operations the same way. For full async context in browsers, explicitly pass context or use the VestigProvider.

With VestigProvider (React)

tsx

1import { VestigProvider, useLogger } from '@vestig/next/client'
2 
3function App() {
4  return (
5    <VestigProvider
6      initialContext={{ sessionId: getSessionId() }}
7      endpoint="/api/logs"
8    >
9      <MyComponent />
10    </VestigProvider>
11  )
12}
13 
14function MyComponent() {
15  const log = useLogger()
16  // All logs include sessionId from provider
17  log.info('Component rendered')
18}

Context Cleanup

Context is automatically cleaned up when the callback completes:

typescript

1await withContext({ temp: 'value' }, async () => {
2  // temp is available
3})
4// temp is no longer in context
5 
6const ctx = getContext()
7console.log(ctx.temp) // undefined

Performance Considerations

AsyncLocalStorage has minimal overhead:

~0.01ms per context access
No memory leaks (context cleaned up automatically)
Works with thousands of concurrent requests

However, avoid storing large objects in context:

typescript

1// ❌ Bad: Large objects in context
2withContext({ fullUserObject: user }, () => { ... })
3 
4// ✅ Good: Just IDs and small metadata
5withContext({ userId: user.id, role: user.role }, () => { ... })

API Reference

Functions

Function	Description
`withContext(ctx, fn)`	Run function with context, returns function result
`withContextAsync(ctx, fn)`	Alias for `withContext` with async function
`getContext()`	Get current context object
`createCorrelationContext(opts)`	Create correlation context with auto IDs

Types

typescript

1interface CorrelationContext {
2  correlationId: string
3  requestId: string
4  timestamp: string
5  [key: string]: unknown
6}
7 
8type Context = Record<string, unknown>

Best Practices

Set context at request entry - middleware, route handler entry
Keep context small - IDs and metadata, not full objects
Use correlation IDs - for tracing across services
Don't mutate context - create new contexts for changes
Use child loggers - for per-module logging with context inheritance

Context Propagation

Vestig provides powerful context propagation using AsyncLocalStorage, ensuring your logging context flows through your entire request lifecycle without manual passing.

Overview

Context propagation solves a fundamental problem: how do you attach metadata (like request IDs, user info) to all logs within a request without passing context through every function?

typescript

1import { withContext, log } from 'vestig'
2 
3// All logs inside this callback automatically include the context
4await withContext({ requestId: 'req-123', userId: 'user-456' }, async () => {
5  log.info('Starting request')          // Includes requestId, userId
6  await processOrder()                   // Any logs here too!
7  log.info('Request completed')          // And here!
8})

How It Works

Vestig uses AsyncLocalStorage (available in Node.js, Bun, and Deno) to maintain context across async boundaries:

text

1+----------------------------------------------------------+
2|                    Request Lifecycle                      |
3+----------------------------------------------------------+
4|                                                           |
5|  withContext({ requestId: 'req-123' }, async () => {     |
6|    |                                                      |
7|    +-- log.info('A')  ----------> { requestId: 'req-123' }|
8|    |                                                      |
9|    +-- await asyncOperation()                             |
10|    |     |                                                |
11|    |     +-- log.info('B')  ---> { requestId: 'req-123' } |
12|    |                                                      |
13|    +-- log.info('C')  ----------> { requestId: 'req-123' }|
14|                                                           |
15+----------------------------------------------------------+

Basic Usage

Setting Context

typescript

1import { withContext, log } from 'vestig'
2 
3// Synchronous callback
4withContext({ userId: 'user-123' }, () => {
5  log.info('User action')
6  // All logs include userId
7})
8 
9// Async callback
10await withContext({ requestId: 'req-456' }, async () => {
11  const data = await fetchData()
12  log.info('Data fetched', { count: data.length })
13  // Logs include requestId
14})

Reading Context

typescript

1import { getContext, log } from 'vestig'
2 
3function logWithContext(message: string) {
4  const ctx = getContext()
5  console.log('Current context:', ctx)
6  // { requestId: 'req-123', userId: 'user-456', ... }
7 
8  log.info(message) // Context automatically included
9}

Nested Context

Context can be nested, with inner contexts merging with outer:

typescript

1import { withContext, log } from 'vestig'
2 
3await withContext({ requestId: 'req-123' }, async () => {
4  log.info('Outer context')
5  // { requestId: 'req-123' }
6 
7  await withContext({ operation: 'checkout' }, async () => {
8    log.info('Inner context')
9    // { requestId: 'req-123', operation: 'checkout' }
10  })
11 
12  log.info('Back to outer')
13  // { requestId: 'req-123' }
14})

Correlation Context

Vestig provides a specialized correlation context for request tracing:

typescript

1import { createCorrelationContext, withContext } from 'vestig'
2 
3// Create correlation context with auto-generated IDs
4const correlationContext = createCorrelationContext({
5  service: 'api',
6  environment: 'production'
7})
8 
9// correlationContext includes:
10// - correlationId: auto-generated UUID
11// - requestId: auto-generated UUID
12// - timestamp: ISO string
13// - service: 'api'
14// - environment: 'production'
15 
16await withContext(correlationContext, async () => {
17  // All logs include correlation IDs
18})

Custom Correlation IDs

typescript

1import { createCorrelationContext } from 'vestig'
2 
3// Use existing correlation ID from upstream service
4const ctx = createCorrelationContext({
5  correlationId: req.headers['x-correlation-id'],
6  requestId: req.headers['x-request-id'],
7  service: 'payment-service'
8})

Context with Child Loggers

Child loggers inherit context from the current scope:

typescript

1import { log, withContext } from 'vestig'
2 
3const orderLogger = log.child('orders')
4 
5await withContext({ orderId: 'order-789' }, async () => {
6  orderLogger.info('Processing order')
7  // namespace: 'orders'
8  // orderId: 'order-789'
9 
10  const paymentLogger = orderLogger.child('payment')
11  paymentLogger.info('Charging card')
12  // namespace: 'orders.payment'
13  // orderId: 'order-789'
14})

Context with Spans

Spans automatically include the current context:

typescript

1import { span, withContext, log } from 'vestig'
2 
3await withContext({ userId: 'user-123' }, async () => {
4  await span('process-order', async (s) => {
5    // Span has access to context
6    s.setAttribute('userId', 'user-123') // Explicit
7 
8    log.info('Processing')
9    // Log includes: userId, traceId, spanId
10  })
11})

HTTP Request Context

Express.js

typescript

1import express from 'express'
2import { withContext, createCorrelationContext } from 'vestig'
3 
4const app = express()
5 
6app.use((req, res, next) => {
7  const ctx = createCorrelationContext({
8    correlationId: req.headers['x-correlation-id'] as string,
9    method: req.method,
10    path: req.path,
11    userAgent: req.headers['user-agent']
12  })
13 
14  withContext(ctx, () => {
15    next()
16  })
17})
18 
19app.get('/api/orders', async (req, res) => {
20  // All logs automatically include request context
21  log.info('Fetching orders')
22  const orders = await getOrders()
23  res.json(orders)
24})

Next.js

With @vestig/next, context is automatically set up:

typescript

1// middleware.ts
2import { withVestig } from '@vestig/next/middleware'
3 
4export const middleware = withVestig((request) => {
5  // Context automatically includes:
6  // - correlationId
7  // - requestId
8  // - method, path, userAgent
9})
10 
11// In route handlers, context is available
12import { getRequestContext } from '@vestig/next'
13 
14export async function GET() {
15  const ctx = await getRequestContext()
16  // { correlationId, requestId, method, path, ... }
17}

Browser Context

In browsers (where AsyncLocalStorage isn't available), Vestig uses a fallback:

typescript

1import { withContext, log } from 'vestig'
2 
3// Works the same way in browsers
4withContext({ sessionId: 'sess-123' }, () => {
5  log.info('User clicked button')
6  // Includes sessionId
7})

Note: Browser context doesn't persist across async operations the same way. For full async context in browsers, explicitly pass context or use the VestigProvider.

With VestigProvider (React)

tsx

1import { VestigProvider, useLogger } from '@vestig/next/client'
2 
3function App() {
4  return (
5    <VestigProvider
6      initialContext={{ sessionId: getSessionId() }}
7      endpoint="/api/logs"
8    >
9      <MyComponent />
10    </VestigProvider>
11  )
12}
13 
14function MyComponent() {
15  const log = useLogger()
16  // All logs include sessionId from provider
17  log.info('Component rendered')
18}

Context Cleanup

Context is automatically cleaned up when the callback completes:

typescript

1await withContext({ temp: 'value' }, async () => {
2  // temp is available
3})
4// temp is no longer in context
5 
6const ctx = getContext()
7console.log(ctx.temp) // undefined

Performance Considerations

AsyncLocalStorage has minimal overhead:

~0.01ms per context access
No memory leaks (context cleaned up automatically)
Works with thousands of concurrent requests

However, avoid storing large objects in context:

typescript

1// ❌ Bad: Large objects in context
2withContext({ fullUserObject: user }, () => { ... })
3 
4// ✅ Good: Just IDs and small metadata
5withContext({ userId: user.id, role: user.role }, () => { ... })

API Reference

Functions

Function	Description
`withContext(ctx, fn)`	Run function with context, returns function result
`withContextAsync(ctx, fn)`	Alias for `withContext` with async function
`getContext()`	Get current context object
`createCorrelationContext(opts)`	Create correlation context with auto IDs

Types

typescript

1interface CorrelationContext {
2  correlationId: string
3  requestId: string
4  timestamp: string
5  [key: string]: unknown
6}
7 
8type Context = Record<string, unknown>

Best Practices

Set context at request entry - middleware, route handler entry
Keep context small - IDs and metadata, not full objects
Use correlation IDs - for tracing across services
Don't mutate context - create new contexts for changes
Use child loggers - for per-module logging with context inheritance