otel-cf-workers

OpenTelemetry instrumentation for Cloudflare Workers with automatic tracing and logging for handlers, bindings, and distributed traces.

Installation

yarn add @inference-net/otel-cf-workers @opentelemetry/api

Requirements

Add the nodejs_compat compatibility flag to your wrangler.toml:

compatibility_flags = ["nodejs_compat"]

Quick Start

Tracing Only

import { trace } from '@opentelemetry/api'
import { instrument, ResolveConfigFn } from '@inference-net/otel-cf-workers'

export interface Env {
	SIGNOZ_ENDPOINT: string
	SIGNOZ_ACCESS_TOKEN: string
	MY_KV: KVNamespace
	MY_D1: D1Database
}

const handler = {
	async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
		// Auto-instrumented: HTTP handler
		await fetch('https://api.example.com') // Auto-instrumented: outbound fetch

		await env.MY_KV.get('key') // Auto-instrumented: KV operations
		await env.MY_D1.prepare('SELECT * FROM users').all() // Auto-instrumented: D1 queries

		// Manual instrumentation: add custom attributes
		trace.getActiveSpan()?.setAttribute('user.id', '123')

		return new Response('Hello World!')
	},
}

const config: ResolveConfigFn = (env: Env, _trigger) => {
	return {
		service: { name: 'my-worker' },
		trace: {
			exporter: {
				url: env.SIGNOZ_ENDPOINT,
				headers: { 'signoz-access-token': env.SIGNOZ_ACCESS_TOKEN },
			},
		},
	}
}

export default instrument(handler, config)

Tracing + Logging

import { trace } from '@opentelemetry/api'
import { instrument, getLogger, OTLPTransport, ConsoleTransport } from '@inference-net/otel-cf-workers'

const handler = {
	async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
		const logger = getLogger('my-app')

		// Logs automatically include trace context (trace ID, span ID)
		logger.info('Processing request', {
			'http.url': request.url,
			'user.id': '123',
		})

		try {
			await env.MY_KV.get('key')
			logger.debug('KV operation complete')

			return new Response('OK')
		} catch (error) {
			// Error logs automatically extract exception info
			logger.error(error as Error)
			return new Response('Error', { status: 500 })
		}
	},
}

const config: ResolveConfigFn = (env: Env, _trigger) => ({
	service: { name: 'my-worker' },
	trace: {
		exporter: {
			url: `${env.OTEL_ENDPOINT}/v1/traces`,
			headers: { 'x-api-key': env.API_KEY },
		},
	},
	logs: {
		transports: [
			new OTLPTransport({
				url: `${env.OTEL_ENDPOINT}/v1/logs`,
				headers: { 'x-api-key': env.API_KEY },
			}),
			new ConsoleTransport({ pretty: true }), // Also log to console
		],
	},
})

export default instrument(handler, config)

Durable Objects

import { instrumentDO, ResolveConfigFn } from '@inference-net/otel-cf-workers'

class MyDurableObject implements DurableObject {
	async fetch(request: Request): Promise<Response> {
		// Auto-instrumented: DO fetch handler
		await this.ctx.storage.get('key') // Auto-instrumented: DO storage
		await this.ctx.storage.sql.exec('SELECT * FROM data') // Auto-instrumented: DO SQL
		return new Response('Hello from DO!')
	}

	async alarm(): Promise<void> {
		// Auto-instrumented: DO alarm handler
	}
}

const config: ResolveConfigFn = (env, _trigger) => ({
	exporter: { url: env.OTEL_ENDPOINT },
	service: { name: 'my-durable-object' },
})

export const MyDO = instrumentDO(MyDurableObject, config)

OpenTelemetry Features

✅ Fully Supported

Tracing:

• Distributed Tracing: Automatic W3C Trace Context propagation across services
• Semantic Conventions: Full support for OpenTelemetry semantic conventions (v1.28.0+)
  • db.query.text - Database queries and keys
  • db.system.name - Database system identification
  • db.operation.name - Operation types
  • db.operation.batch.size - Batch operation tracking
  • http.* - HTTP request/response attributes
  • faas.* - FaaS trigger and execution attributes
• Custom Spans: Create manual spans with trace.getTracer()
• Span Attributes: Set custom attributes on active spans
• Context Propagation: Async context management across Workers runtime
• Sampling: Both head and tail sampling strategies
• Exporters: OTLP/HTTP (JSON) format
• Span Processors: Custom trace-based batch processing

Logging:

• Structured Logging: OpenTelemetry Logs API with convenience methods
• Automatic Trace Correlation: Logs include trace ID and span ID from active spans
• Child Loggers: Inherit attributes from parent loggers for context propagation
• Multiple Transports: Send logs to OTLP backends, console, or custom destinations
• Batching Strategies: Configurable batching (immediate or size-based)
• Severity Levels: Standard OpenTelemetry severity levels (TRACE, DEBUG, INFO, WARN, ERROR, FATAL)
• Console Instrumentation: Optional capture of console.log(), console.error(), etc.
• Custom Transports: Extensible transport interface for custom log destinations

📖 See LOGS.md for complete logging documentation

Cloudflare-Specific Attributes

In addition to OpenTelemetry standard attributes, we capture Cloudflare-specific metadata:

• cloudflare.* - Platform-specific attributes (ray ID, colo, script version)
• geo.* - Request geolocation data
• Response metadata (TTL, cache status, rows read/written)
• Binding-specific attributes (KV keys, D1 query stats, R2 checksums)

Cloudflare Platform Support

Triggers & Handlers

Feature	Status	Notes
HTTP Handler (fetch)	✅	Full support with geo, headers, user-agent parsing
Scheduled Handler (scheduled)	✅	Cron trigger instrumentation
Queue Consumer (queue)	✅	Message batch processing with ack/retry tracking
Email Handler (email)	✅	Incoming email processing
Durable Object fetch	✅	DO HTTP requests
Durable Object alarm	✅	DO alarm triggers
ctx.waitUntil	✅	Background promise tracking
Tail Handler (tail)	❌	Not yet supported
DO Hibernated WebSocket	❌	Not yet supported

Bindings

Binding	Status	Operations Instrumented
KV Namespace	✅	get, put, delete, list, getWithMetadata
R2 Bucket	✅	head, get, put, delete, list, createMultipartUpload, resumeMultipartUpload
D1 Database	✅	prepare, exec, batch, all, run, first, raw
Durable Objects	✅	Stub fetch calls
DO Storage (KV)	✅	get, put, delete, list, getAlarm, setAlarm, deleteAlarm
DO Storage (SQL)	✅	exec, execBatch
Queue Producer	✅	send, sendBatch
Service Bindings	✅	Worker-to-worker calls
Analytics Engine	✅	writeDataPoint
Images	✅	get, list, delete
Rate Limiting	✅	limit
Workers AI	❌	Not yet supported
Vectorize	❌	Not yet supported
Hyperdrive	❌	Not yet supported
Browser Rendering	❌	Not yet supported
Email Sending	❌	Not yet supported
mTLS	❌	Not yet supported

Global APIs

API	Status	Notes
fetch()	✅	Global fetch calls with trace context injection
caches	✅	Cache API operations

Cloudflare Modules

Module	Status
cloudflare:email	❌
cloudflare:sockets	❌

Configuration

Basic Configuration

const config: ResolveConfigFn = (env: Env, trigger) => ({
	service: {
		name: 'my-service',
		version: '1.0.0', // Optional
		namespace: 'production', // Optional
	},
	trace: {
		exporter: {
			url: env.SIGNOZ_ENDPOINT,
			headers: { 'signoz-access-token': env.SIGNOZ_ACCESS_TOKEN },
		},
	},
	// Logs are optional
	logs: {
		transports: [new OTLPTransport({ url: env.LOGS_ENDPOINT })],
	},
})

Note: Both trace and logs are optional. You can configure:

• Tracing only
• Logging only
• Both tracing and logging
• Neither (no telemetry)

Sampling

const config: ResolveConfigFn = (env, trigger) => ({
	// ... exporter config
	sampling: {
		// Head sampling: sample 10% of requests at start
		headSampler: {
			ratio: 0.1,
			acceptRemote: true, // Accept parent trace decisions
		},
		// Tail sampling: always keep errors even if not head-sampled
		tailSampler: (trace) => {
			const rootSpan = trace.localRootSpan
			return (
				rootSpan.status.code === SpanStatusCode.ERROR || (rootSpan.spanContext().traceFlags & TraceFlags.SAMPLED) !== 0
			)
		},
	},
})

Trace Context Propagation

const config: ResolveConfigFn = (env, trigger) => ({
	// ... exporter config

	// Control outbound trace context
	fetch: {
		includeTraceContext: (request) => {
			// Only propagate to same-origin requests
			return new URL(request.url).hostname === 'api.example.com'
		},
	},

	// Control inbound trace context
	handlers: {
		fetch: {
			acceptTraceContext: (request) => {
				// Accept trace context from trusted origins
				return request.headers.get('x-trusted') === 'true'
			},
		},
	},
})

Post-Processing

Redact sensitive data before export:

const config: ResolveConfigFn = (env, trigger) => ({
	// ... exporter config
	postProcessor: (spans) => {
		return spans.map((span) => {
			// Redact URLs with tokens
			if (span.attributes['http.url']) {
				span.attributes['http.url'] = span.attributes['http.url'].replace(/token=[^&]+/, 'token=REDACTED')
			}
			// Remove sensitive headers
			delete span.attributes['http.request.header.authorization']
			return span
		})
	},
})

Custom Propagator

const config: ResolveConfigFn = (env, trigger) => ({
	// ... exporter config
	propagator: new MyCustomPropagator(),
})

Manual Instrumentation

Adding Attributes

import { trace } from '@opentelemetry/api'

const handler = {
	async fetch(request: Request, env: Env) {
		const span = trace.getActiveSpan()
		if (span) {
			span.setAttribute('user.id', '123')
			span.setAttribute('user.role', 'admin')
		}
		return new Response('OK')
	},
}

Creating Custom Spans

import { trace, SpanStatusCode } from '@opentelemetry/api'

const handler = {
	async fetch(request: Request, env: Env) {
		const tracer = trace.getTracer('my-app')

		return await tracer.startActiveSpan('process-request', async (span) => {
			span.setAttribute('request.id', crypto.randomUUID())

			try {
				const result = await doWork()
				span.setStatus({ code: SpanStatusCode.OK })
				return new Response(result)
			} catch (error) {
				span.recordException(error)
				span.setStatus({ code: SpanStatusCode.ERROR })
				throw error
			} finally {
				span.end()
			}
		})
	},
}

Limitations

• Timing Accuracy: The Workers runtime does not expose accurate timing information to protect against Spectre attacks. CPU-bound work may show 0ms duration. The clock only updates on I/O operations.
• RPC-Style DO Calls: Direct RPC method calls to Durable Objects (e.g., await stub.myMethod()) are not auto-instrumented. Use fetch-style calls (await stub.fetch(request)) for automatic tracing.

Examples

See the examples directory for complete working examples:

Tracing:

• Basic Worker - HTTP handler with KV and D1
• Quickstart Guide - Step-by-step tutorial

Logging:

• Basic Logging - Simple logging setup
• Advanced Logging - Traces + logs correlation
• Logs Only - Logging without tracing
• Child Loggers - Context inheritance with child loggers

Resources

• Logging Documentation - Complete guide to OpenTelemetry Logs
• OpenTelemetry Documentation
• Cloudflare Workers Documentation
• Semantic Conventions

License

BSD-3-Clause

Contributing

Contributions welcome! This is a fork maintained by @context-labs, originally from evanderkoogh/otel-cf-workers.