autotel-cloudflare
Version:
The #1 OpenTelemetry package for Cloudflare Workers - complete bindings coverage, native CF OTel integration, advanced sampling
541 lines (418 loc) • 15.2 kB
Markdown
**The
[](https://www.npmjs.com/package/autotel-cloudflare)
[](https://bundlephobia.com/package/autotel-cloudflare)
[](https://opensource.org/licenses/MIT)
- ✅ **Native Cloudflare OTel integration** - Works with `wrangler.toml` destinations
- ✅ **Complete bindings coverage** - KV, R2, D1, DO, AI, Vectorize, Hyperdrive, and more
- ✅ **Multiple API styles** - `instrument()`, `wrapModule()`, `wrapDurableObject()`, functional
- ✅ **Advanced sampling** - Adaptive tail sampling (10% baseline, 100% errors/slow)
- ✅ **Events integration** - Product analytics with trace correlation
- ✅ **Zero vendor lock-in** - OTLP compatible, works with any backend
- ✅ **Tree-shakeable** - Import only what you need
- ✅ **TypeScript native** - Full type safety
## DX Direction
The package direction is to make Cloudflare observability feel the same across Workers, Queues, Durable Objects, alarms, and Workflows:
- use Cloudflare-native wrappers to create the root span
- use the `trace(..., (ctx) => ...)` factory form for business logic
- prefer span attributes and one execution snapshot over scattered info logs
See [docs/CLOUDFLARE-DX.md](../../docs/CLOUDFLARE-DX.md) for the design target and review rules.
```bash
npm install autotel-cloudflare
pnpm add autotel-cloudflare
yarn add autotel-cloudflare
```
For just structured logs (no tracing setup required), import from `autotel-cloudflare/logger`:
```ts
import { createEdgeLogger } from 'autotel-cloudflare/logger'
const log = createEdgeLogger('my-worker', { level: 'info' })
export default {
async fetch() {
log.info({ user_id: 'u1' }, 'request handled')
return new Response('ok')
},
}
```
`autotel-cloudflare/logger` is the edge-clean entry: it re-exports `createEdgeLogger` from `autotel-edge/logger` plus the Cloudflare execution-logger helpers (`createWorkersLogger`, `getRequestLogger`, `getQueueLogger`). The root `autotel-cloudflare` import pulls in tracing, `AsyncLocalStorage`, and the wrappers — only use it when you want spans.
## Quick Start
### 1. Configure Cloudflare Native OTel (wrangler.toml)
```toml
[observability.traces]
enabled = true
destinations = ["honeycomb"]
head_sampling_rate = 1.0
```
```typescript
import { wrapModule, trace } from 'autotel-cloudflare'
// Zero-boilerplate function tracing
const processOrder = trace(async (orderId: string, kv: KVNamespace) => {
const order = await kv.get(orderId) // Auto-instrumented!
return order
})
export default wrapModule(
{
service: { name: 'my-worker' },
instrumentBindings: true, // Auto-instrument KV, R2, D1, etc.
sampling: 'adaptive' // 10% baseline, 100% errors/slow
},
{
async fetch(req, env, ctx) {
return Response.json(await processOrder('123', env.ORDERS_KV))
}
}
)
```
Inspired by workers-honeycomb-logger:
```typescript
import { wrapModule } from 'autotel-cloudflare'
const handler = {
async fetch(req, env, ctx) {
return new Response('Hello')
}
}
export default wrapModule(
{ service: { name: 'my-worker' } },
handler
)
```
### Style 2: instrument
```typescript
import { instrument } from 'autotel-cloudflare'
export default instrument(
{
async fetch(req, env, ctx) {
return new Response('Hello')
}
},
{ service: { name: 'my-worker' } }
)
```
Filter which fetch routes are instrumented and map route patterns to service names:
```typescript
import { wrapModule } from 'autotel-cloudflare'
export default wrapModule(
{
service: { name: 'edge-gateway' },
handlers: {
fetch: {
include: ['/api/**'],
exclude: ['/api/internal/**', '/health'],
routes: {
'/api/auth/**': { service: 'auth-service' },
'/api/**': { service: 'api-service' },
},
},
},
},
{
async fetch(req) {
return new Response('ok')
},
},
)
```
Zero-boilerplate function tracing:
```typescript
import { trace, span } from 'autotel-cloudflare'
// Automatic trace name inference
export const createUser = trace(async (data: UserData) => {
return await db.insert(data)
})
// Factory pattern for context access
export const processPayment = trace(ctx => async (amount: number) => {
ctx.setAttribute('amount', amount)
await span('validate.card', () => validateCard())
await span('charge.card', () => chargeCard(amount))
return { success: true }
})
```
Use `createWorkersLogger()` for request-scoped snapshots with Cloudflare context pre-filled.
```typescript
import { wrapModule, createWorkersLogger } from 'autotel-cloudflare'
export default wrapModule(
{ service: { name: 'checkout-worker' } },
{
async fetch(request) {
const log = createWorkersLogger(request, {
headers: ['x-request-id'],
})
log.info('checkout.started')
log.set({ checkout: { stage: 'validated' } })
log.emitNow({ status: 200 })
return new Response('ok')
},
},
)
```
All bindings are automatically instrumented when `instrumentBindings: true`:
```typescript
// KV
await env.MY_KV.get('key') // → Span: "KV MY_KV: get"
await env.MY_KV.put('key', 'value') // → Span: "KV MY_KV: put"
// R2
await env.MY_R2.get('file.txt') // → Span: "R2 MY_R2: get"
await env.MY_R2.put('file.txt', data) // → Span: "R2 MY_R2: put"
// D1
await env.MY_D1.prepare('SELECT * FROM users').all() // → Span: "D1 MY_D1: all"
// Durable Objects
await env.MY_DO.get(id).fetch(req) // → Span: "DO MY_DO: fetch"
// Workers AI
await env.AI.run('@cf/meta/llama', { prompt: '...' }) // → Span: "AI: run"
// Vectorize
await env.VECTOR.query(vector) // → Span: "Vectorize VECTOR: query"
// Service Bindings
await env.MY_SERVICE.fetch(req) // → Span: "Service MY_SERVICE: fetch"
// Queue
await env.MY_QUEUE.send({ data }) // → Span: "Queue MY_QUEUE: send"
// Analytics Engine
await env.ANALYTICS.writeDataPoint({ ... }) // → Span: "Analytics: writeDataPoint"
```
**Supported Bindings:**
- ✅ KV (get, put, delete, list, getWithMetadata)
- ✅ R2 (head, get, put, delete, list, createMultipartUpload)
- ✅ D1 (prepare, batch, exec, dump)
- ✅ Durable Objects (fetch, alarm)
- ✅ Workflows (get, create, getInstance)
- ✅ Workers AI (run)
- ✅ Vectorize (insert, query, getByIds, deleteByIds, upsert)
- ✅ Hyperdrive (all queries)
- ✅ Service Bindings (fetch)
- ✅ Queue (send, sendBatch)
- ✅ Analytics Engine (writeDataPoint)
- ✅ Email (send, forward)
## Sampling Strategies
### Adaptive Sampling (Recommended)
```typescript
import { SamplingPresets } from 'autotel-cloudflare/sampling'
wrapModule(
{
service: { name: 'my-worker' },
sampling: {
tailSampler: SamplingPresets.production()
// 10% baseline, 100% errors, 100% slow requests (>1s)
}
},
handler
)
```
```typescript
// Development - 100% sampling
sampling: { tailSampler: SamplingPresets.development() }
// Production - 10% baseline, all errors, slow >1s
sampling: { tailSampler: SamplingPresets.production() }
// High traffic - 1% baseline, all errors, slow >1s
sampling: { tailSampler: SamplingPresets.highTraffic() }
// Debugging - errors only
sampling: { tailSampler: SamplingPresets.debugging() }
// Or use shorthand
sampling: 'adaptive' // Same as SamplingPresets.production()
sampling: 'error-only' // Same as SamplingPresets.debugging()
```
```typescript
import { createCustomTailSampler } from 'autotel-cloudflare/sampling'
const customSampler = createCustomTailSampler((trace) => {
const span = trace.localRootSpan
// Always sample /api/* endpoints
if (span.attributes['http.route']?.toString().startsWith('/api/')) {
return true
}
// Sample all errors
if (span.status.code === SpanStatusCode.ERROR) {
return true
}
// Sample slow requests
const duration = (span.endTime[0] - span.startTime[0]) / 1_000_000
if (duration > 1000) {
return true
}
return Math.random() < 0.1 // 10% of everything else
})
```
```typescript
import { wrapDurableObject } from 'autotel-cloudflare'
class Counter implements DurableObject {
async fetch(request: Request) {
// Auto-traced with span "Counter: fetch"
const count = await this.state.storage.get('count') || 0
await this.state.storage.put('count', count + 1)
return new Response(String(count + 1))
}
async alarm() {
// Auto-traced with span "Counter: alarm"
console.log('Alarm triggered')
}
}
export default wrapDurableObject(
{ service: { name: 'counter-do' } },
Counter
)
```
## Events Integration
Track product events with automatic trace correlation:
```typescript
import { publishEvent } from 'autotel-cloudflare/events'
wrapModule(
{
service: { name: 'my-worker' },
// Configure event subscribers
subscribers: [
async (event) => {
// Send to your analytics platform
await fetch('https://analytics.example.com/events', {
method: 'POST',
body: JSON.stringify(event)
})
}
]
},
{
async fetch(req, env, ctx) {
// Track user events
await publishEvent({
name: 'order.completed',
userId: '123',
properties: {
orderId: 'abc',
amount: 99.99
}
// Automatically includes current trace ID
})
return new Response('OK')
}
}
)
```
```typescript
import { wrapModule, SamplingPresets } from 'autotel-cloudflare'
export default wrapModule(
{
// Service identification
service: {
name: 'my-worker',
version: '1.0.0',
namespace: 'production'
},
// Auto-instrument bindings
instrumentBindings: true,
// Global instrumentations
instrumentation: {
instrumentGlobalFetch: true, // Trace all fetch() calls
instrumentGlobalCache: true, // Trace cache API
disabled: false // Set true to disable all tracing
},
// Sampling strategy
sampling: {
tailSampler: SamplingPresets.production()
},
// Handler-specific config
handlers: {
fetch: {
postProcess: (span, { request, response }) => {
// Add custom attributes
const url = new URL(request.url)
if (url.pathname.startsWith('/api/')) {
span.setAttribute('api.endpoint', url.pathname)
}
}
}
}
},
handler
)
```
```typescript
// Configuration can be a function
export default wrapModule(
(env, trigger) => ({
service: { name: env.SERVICE_NAME || 'my-worker' },
exporter: {
url: env.OTEL_ENDPOINT,
headers: { 'x-api-key': env.API_KEY }
},
sampling: {
tailSampler: env.ENVIRONMENT === 'production'
? SamplingPresets.production()
: SamplingPresets.development()
}
}),
handler
)
```
```typescript
// Main export (everything — pulls AsyncLocalStorage, needs nodejs_compat)
import { wrapModule, trace, instrument } from 'autotel-cloudflare'
// Tree-shakeable entry points
import { instrumentKV, instrumentR2 } from 'autotel-cloudflare/bindings'
import { instrumentDO } from 'autotel-cloudflare/handlers'
import { SamplingPresets } from 'autotel-cloudflare/sampling'
import { publishEvent } from 'autotel-cloudflare/events'
import { createEdgeLogger } from 'autotel-cloudflare/logger'
import { createTraceCollector } from 'autotel-cloudflare/testing'
```
Workers run on V8 isolates, not Node. Anything that transitively imports `node:async_hooks` (used by `AsyncLocalStorageContextManager` for span context) or `node:buffer` requires `compatibility_flags = ["nodejs_compat"]` in your `wrangler.toml`. The `/logger` subpath stays clear of those.
| Entry | Edge-safe without `nodejs_compat`? | Notes |
| --- | --- | --- |
| `autotel-cloudflare` | No — needs `nodejs_compat` | Pulls `AsyncLocalStorage` (span context) and `Buffer` transitively via `autotel-edge` root |
| `autotel-cloudflare/logger` | Yes | Edge-clean. `createEdgeLogger`, `createWorkersLogger`, `getRequestLogger`, `getQueueLogger`, `getWorkflowLogger`, `getActorLogger` |
| `autotel-cloudflare/bindings` | No — needs `nodejs_compat` | Wrappers create spans, require context manager |
| `autotel-cloudflare/handlers` | No — needs `nodejs_compat` | DO/Workflow wrappers create spans |
| `autotel-cloudflare/sampling` | Yes | Pure samplers, no runtime imports |
| `autotel-cloudflare/events` | No — needs `nodejs_compat` | Pulls trace context for correlation |
| `autotel-cloudflare/testing` | Yes (test-only) | Collectors live in test runtime; do not ship to Workers |
| `autotel-cloudflare/actors` | No — needs `nodejs_compat` | Builds on DO wrappers |
| `autotel-cloudflare/agents` | No — needs `nodejs_compat` | Builds on DO wrappers |
| `autotel-cloudflare/parse-error` | Yes | Pure error normaliser |
Rule of thumb: if you only need logs, import `autotel-cloudflare/logger` and skip `nodejs_compat`. If you want spans, add `nodejs_compat` and import from the root.
- [autotel-edge](../autotel-edge) — vendor-agnostic foundation re-exported by this package
- [autotel](../autotel) — Node.js entry, full SDK with auto-instrumentation
- [autotel-drizzle](../autotel-drizzle) — Drizzle ORM spans (Node only)
## Testing
```typescript
import { createTraceCollector, assertTraceCreated } from 'autotel-cloudflare/testing'
describe('my worker', () => {
it('creates traces', async () => {
const collector = createTraceCollector()
await myFunction()
assertTraceCreated(collector, 'myFunction')
})
})
```
See [apps/cloudflare-example](../../apps/cloudflare-example) for a complete working example with:
- ✅ All bindings instrumented (KV, R2, D1, etc.)
- ✅ Multiple handler types (fetch, scheduled, queue, email)
- ✅ Durable Objects
- ✅ Custom spans and attributes
- ✅ Error handling
- ✅ Sampling strategies
- ✅ Events tracking
## License
MIT © [Jag Reehal](https://github.com/jagreehal)
## Links
- [GitHub Repository](https://github.com/jagreehal/autotel)
- [Documentation](https://github.com/jagreehal/autotel#readme)
- [Issues](https://github.com/jagreehal/autotel/issues)
- [autotel-edge](../autotel-edge) - Vendor-agnostic foundation