Cloudflare Workers & Edge Deployment

Vestig works fully on Edge runtimes with zero configuration changes. Logging, tracing, OTLP export, PII sanitization, wide events, and sampling all work out of the box on Cloudflare Workers, Vercel Edge Runtime, and Deno Deploy.

Overview

Edge runtimes run JavaScript at the network edge, close to your users. Unlike traditional Node.js servers, they use web-standard APIs and have shorter execution time limits. Vestig is built entirely on these web standards — no Node.js-specific dependencies like http, net, or fs — so everything works natively on Edge.

What works on Edge runtimes:

• Logging — Structured logging with all log levels
• Tracing — Span creation, nesting, and attribute tracking
• OTLP Export — Send traces to Honeycomb, Grafana, Jaeger, or any OTLP backend
• PII Sanitization — All sanitization presets (GDPR, HIPAA, PCI-DSS)
• Wide Events — Rich event aggregation across request lifecycles
• Sampling — Head and tail sampling strategies
• W3C Trace Context — Full traceparent and tracestate propagation

Runtime Detection

Vestig automatically detects Edge runtimes through its runtime.ts module. The detection logic checks for platform-specific globals:

1// Vercel Edge Runtime
2if ('EdgeRuntime' in globalThis) return 'edge'
3 
4// Next.js Edge via env
5if (process.env.NEXT_RUNTIME === 'edge') return 'edge'
6 
7// Cloudflare Workers: has caches + Request + Response, no window, no process.versions.node
8if ('caches' in globalThis && typeof Request === 'function'
9    && typeof Response === 'function'
10    && typeof window === 'undefined' && !hasNodeVersion()) return 'edge'

Once detected, you can use the convenience flags anywhere in your code:

1import { IS_EDGE, IS_SERVER, RUNTIME } from 'vestig'
2 
3// IS_EDGE = true on CF Workers, Vercel Edge, Deno Deploy
4// IS_SERVER = IS_NODE || IS_BUN || IS_DENO || IS_EDGE
5// RUNTIME = 'edge' on all Edge runtimes

These flags are resolved once at startup and remain constant for the lifetime of the isolate.

OTLP on Edge

The OTLPExporter uses native fetch() under the hood, making it fully compatible with Edge runtimes. There are no Node.js APIs involved — no http module, no net sockets, no filesystem access. Pure web standards.

Edge runtimes have shorter execution time limits than traditional servers, so you should tune the exporter for smaller batches, more frequent flushes, and shorter timeouts:

1import { registerSpanProcessor, span } from 'vestig'
2import { OTLPExporter } from 'vestig/otlp'
3 
4const exporter = new OTLPExporter({
5  endpoint: 'https://api.honeycomb.io/v1/traces',
6  serviceName: 'my-worker',
7  headers: { 'x-honeycomb-team': HONEYCOMB_API_KEY },
8  batchSize: 25,        // Smaller batches for Edge
9  flushInterval: 1000,  // More frequent flushes
10  timeout: 5000,        // Shorter timeout
11  maxRetries: 1,        // Fewer retries (execution time limits)
12})
13 
14registerSpanProcessor(exporter)

These settings keep the exporter well within the typical 30-second CPU time limit of Cloudflare Workers while ensuring spans are reliably delivered.

Context Management

Vestig adapts its context management strategy based on the runtime:

• Node.js / Bun / Deno — Uses AsyncLocalStorage for proper request isolation across async boundaries
• Edge runtimes (Cloudflare Workers) — Falls back to GlobalContextManager, a stack-based global context

The GlobalContextManager works correctly for sequential operations within a single request. Since Cloudflare Workers handle one request at a time per isolate, this is safe for most deployments. Concurrent requests in the same isolate can potentially share context, but this is rare in practice.

The API is identical regardless of runtime:

1import { withContext, getContext } from 'vestig'
2 
3// Works the same on Edge — context is propagated within the execution
4await withContext({ requestId: 'req-123' }, async () => {
5  const ctx = getContext()
6  // ctx.requestId === 'req-123'
7})

Basic Cloudflare Worker Example

A complete Cloudflare Worker with logging, tracing, and OTLP export:

1import { createLogger, span, withContext, createCorrelationContext } from 'vestig'
2import { OTLPExporter, registerSpanProcessor, shutdownSpanProcessors } from 'vestig/otlp'
3 
4const log = createLogger({ namespace: 'worker' })
5 
6// Setup OTLP (run once at module level)
7const exporter = new OTLPExporter({
8  endpoint: 'https://api.honeycomb.io/v1/traces',
9  serviceName: 'my-worker',
10  headers: { 'x-honeycomb-team': 'your-api-key' },
11  batchSize: 25,
12  timeout: 5000,
13})
14registerSpanProcessor(exporter)
15 
16export default {
17  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
18    const context = createCorrelationContext()
19 
20    return withContext(context, async () => {
21      return span('worker:request', async (s) => {
22        s.setAttribute('http.method', request.method)
23        s.setAttribute('http.url', request.url)
24 
25        log.info('Request received', { method: request.method })
26 
27        const result = await handleRequest(request)
28 
29        s.setAttribute('http.status_code', result.status)
30 
31        // Ensure spans are flushed before Worker terminates
32        ctx.waitUntil(exporter.forceFlush())
33 
34        return result
35      })
36    })
37  },
38}

Important: Always use ctx.waitUntil() to flush spans. Cloudflare Workers terminate immediately after the response is sent. Without waitUntil, pending spans would be lost. The ExecutionContext.waitUntil() method extends the Worker's lifetime to complete background tasks like flushing telemetry.

Next.js Edge Routes

Vestig works seamlessly in Next.js Edge API routes. Add export const runtime = 'edge' to opt into Edge execution:

1// app/api/fast/route.ts
2export const runtime = 'edge'
3 
4import { span } from 'vestig'
5import { log } from '@/lib/logger'
6 
7export async function GET(request: Request) {
8  return span('api:fast', async (s) => {
9    s.setAttribute('runtime', 'edge')
10    log.info('Edge API called')
11    return Response.json({ fast: true })
12  })
13}

Vestig detects the Edge runtime automatically via the NEXT_RUNTIME environment variable and adjusts its behavior accordingly.

W3C Trace Context Propagation

For cross-service correlation, parse incoming traceparent headers and propagate them to downstream services:

1import { parseTraceparent, createTraceparent, span } from 'vestig'
2 
3export default {
4  async fetch(request: Request) {
5    // Parse incoming trace context
6    const traceparent = request.headers.get('traceparent')
7    const parsed = traceparent ? parseTraceparent(traceparent) : null
8 
9    return span('worker:handle', async (s) => {
10      // Propagate to downstream services
11      const outgoing = createTraceparent({
12        traceId: parsed?.traceId ?? s.traceId,
13        spanId: s.spanId,
14        sampled: true,
15      })
16 
17      const response = await fetch('https://api.example.com/data', {
18        headers: { 'traceparent': outgoing },
19      })
20 
21      return new Response(await response.text())
22    })
23  },
24}

This ensures a single trace ID follows a request from the Edge Worker through any number of downstream services, giving you a complete picture in your tracing backend.

Feature Compatibility Matrix

Best Practices for Edge Deployments

• Flush before termination — Always use ctx.waitUntil(exporter.forceFlush()) in Cloudflare Workers to ensure spans are exported before the isolate shuts down
• Smaller batches — Use batchSize: 25 and flushInterval: 1000 to stay within execution time limits
• Shorter timeouts — Edge functions have strict CPU time budgets; use timeout: 5000 to avoid hitting them
• Fewer retries — Set maxRetries: 1 to prevent retry loops from exhausting execution time
• Log sparingly — Edge runtimes have no persistent storage; rely on OTLP export for observability rather than high-volume console logging
• Trace context — Propagate traceparent headers to downstream services for end-to-end distributed tracing

Related

• OTLP Export — Configure OTLP backends
• Tracing Overview — Span creation and management
• Runtime Detection — How Vestig detects environments
• Context Propagation — Request correlation
• W3C Trace Context — traceparent and tracestate