W3C Trace Context

1{version}-{trace-id}-{parent-id}-{trace-flags}

1import { parseTraceparent } from 'vestig'
2 
3const header = '00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01'
4const context = parseTraceparent(header)
5 
6if (context) {
7  console.log(context.traceId)    // '0af7651916cd43dd8448eb211c80319c'
8  console.log(context.parentId)   // 'b7ad6b7169203331'
9  console.log(context.traceFlags) // 1 (sampled)
10  console.log(context.version)    // 0
11}

1import { createTraceparent, generateTraceId, generateSpanId } from 'vestig'
2 
3// Generate new trace context
4const traceparent = createTraceparent({
5  traceId: generateTraceId(),   // 32 hex chars
6  parentId: generateSpanId(),   // 16 hex chars
7  traceFlags: 1,                // 1 = sampled
8  version: 0
9})
10 
11// Result: '00-{traceId}-{parentId}-01'

1tracestate: vendor1=value1,vendor2=value2,vestig=abc123

1import { parseTracestate } from 'vestig'
2 
3const header = 'vendor1=value1,vendor2=value2,vestig=abc123'
4const state = parseTracestate(header)
5 
6// state is a Map<string, string>
7console.log(state.get('vendor1')) // 'value1'
8console.log(state.get('vestig'))  // 'abc123'

1import { createTracestate } from 'vestig'
2 
3const state = new Map([
4  ['vestig', 'span-123'],
5  ['region', 'us-east-1'],
6])
7 
8const header = createTracestate(state)
9// Result: 'vestig=span-123,region=us-east-1'

1import {
2  parseTracestate,
3  getTracestateValue,
4  setTracestateValue,
5  deleteTracestateKey,
6  createTracestate
7} from 'vestig'
8 
9// Parse incoming header
10let state = parseTracestate('vendor1=value1,vendor2=value2')
11 
12// Get a value
13const vendor1 = getTracestateValue(state, 'vendor1') // 'value1'
14 
15// Set a value (moves key to front per spec)
16state = setTracestateValue(state, 'vestig', 'my-span-id')
17// Result order: vestig, vendor1, vendor2
18 
19// Delete a key
20state = deleteTracestateKey(state, 'vendor2')
21 
22// Create outgoing header
23const header = createTracestate(state)
24// Result: 'vestig=my-span-id,vendor1=value1'

1import { span, parseTraceparent } from 'vestig'
2 
3// In an HTTP handler
4async function handleRequest(req: Request) {
5  // Parse incoming trace context
6  const traceparent = parseTraceparent(
7    req.headers.get('traceparent') || ''
8  )
9 
10  // Create span with parent context
11  return await span('handle-request', async (s) => {
12    if (traceparent) {
13      s.setAttribute('parentTraceId', traceparent.traceId)
14    }
15 
16    // Your logic here
17    return processRequest(req)
18  }, {
19    parentContext: traceparent ? {
20      traceId: traceparent.traceId,
21      spanId: traceparent.parentId,
22    } : undefined
23  })
24}

1import { createTraceparent, getActiveSpan } from 'vestig'
2 
3async function callDownstreamService(url: string) {
4  const activeSpan = getActiveSpan()
5 
6  const headers: Record<string, string> = {}
7 
8  if (activeSpan) {
9    headers['traceparent'] = createTraceparent({
10      traceId: activeSpan.traceId,
11      parentId: activeSpan.spanId,
12      traceFlags: activeSpan.sampled ? 1 : 0,
13      version: 0
14    })
15  }
16 
17  return fetch(url, { headers })
18}

1// middleware.ts
2import { withVestig } from '@vestig/next/middleware'
3 
4export const middleware = withVestig((request) => {
5  // Trace context is automatically:
6  // 1. Parsed from incoming traceparent header
7  // 2. Propagated to response headers
8  // 3. Available in your route handlers
9})

1// Example: Calling an OTel-instrumented service
2import { span, createTraceparent, createTracestate } from 'vestig'
3 
4await span('call-otel-service', async (s) => {
5  const response = await fetch('https://otel-service.example.com/api', {
6    headers: {
7      'traceparent': createTraceparent({
8        traceId: s.traceId,
9        parentId: s.spanId,
10        traceFlags: 1,
11        version: 0
12      }),
13      'tracestate': createTracestate(new Map([
14        ['vestig', s.spanId]
15      ]))
16    }
17  })
18 
19  return response.json()
20})

1interface TraceContext {
2  version: number       // Always 0 for current spec
3  traceId: string       // 32 hex characters
4  parentId: string      // 16 hex characters (span ID)
5  traceFlags: number    // Bit field (1 = sampled)
6}
7 
8type Tracestate = Map<string, string>