Package Exports

autolemetry-edge
autolemetry-edge/events
autolemetry-edge/logger
autolemetry-edge/sampling
autolemetry-edge/testing

Readme

autolemetry-edge

Vendor-agnostic OpenTelemetry for edge runtimes - the foundation for Cloudflare Workers, Vercel Edge, Netlify Edge, Deno Deploy, and more.

Overview

autolemetry-edge is a lightweight (~20KB), vendor-agnostic OpenTelemetry implementation designed specifically for edge runtimes. It provides the core functionality for tracing, sampling, events, and logging without any vendor-specific dependencies.

For Cloudflare Workers Users

If you're using Cloudflare Workers, use autolemetry-cloudflare instead, which includes complete Cloudflare bindings instrumentation (KV, R2, D1, etc.) and handler wrappers.

When to Use autolemetry-edge Directly

Use this package directly if you're:

Building for Vercel Edge Functions
Building for Netlify Edge Functions
Building for Deno Deploy
Building a custom edge runtime
Creating a vendor-specific package (like autolemetry-vercel)

Features

✅ Zero-boilerplate functional API - trace(), span(), instrument()
✅ Advanced sampling strategies - Adaptive, error-only, slow-only, custom
✅ Events integration - Product analytics with trace correlation
✅ Zero-dependency logger - Trace-aware logging
✅ Tree-shakeable - Import only what you need
✅ Bundle size optimized - ~~20KB minified (~~8KB gzipped)
✅ OpenTelemetry compliant - Works with any OTLP backend
✅ TypeScript native - Full type safety

Installation

npm install autolemetry-edge
# or
pnpm add autolemetry-edge
# or
yarn add autolemetry-edge

Quick Start

Basic Usage

import { trace, init } from 'autolemetry-edge'

// Initialize once at startup
init({
  service: { name: 'my-edge-function' },
  exporter: {
    url: process.env.OTEL_ENDPOINT || 'http://localhost:4318/v1/traces'
  }
})

// Zero-boilerplate function tracing
export const handler = trace(async (request: Request) => {
  return new Response('Hello World')
})

Factory Pattern (for context access)

import { trace } from 'autolemetry-edge'

// Factory pattern - receives context, returns handler
export const processOrder = trace(ctx => async (orderId: string) => {
  ctx.setAttribute('order.id', orderId)

  // Your business logic
  const order = await getOrder(orderId)

  return order
})

Entry Points (Tree-Shaking)

The package provides multiple entry points for optimal tree-shaking:

// Core API
import { trace, span, init } from 'autolemetry-edge'

// Sampling strategies
import { createAdaptiveSampler, SamplingPresets } from 'autolemetry-edge/sampling'

// Events system
import { createEdgeSubscribers, publishEvent } from 'autolemetry-edge/events'

// Logger
import { createEdgeLogger } from 'autolemetry-edge/logger'

// Testing utilities
import { createTraceCollector, assertTraceCreated } from 'autolemetry-edge/testing'

Sampling Strategies

Adaptive Sampling (Recommended for Production)

import { SamplingPresets } from 'autolemetry-edge/sampling'

init({
  service: { name: 'my-app' },
  exporter: { url: '...' },
  sampling: {
    tailSampler: SamplingPresets.production()
    // 10% baseline, 100% errors, 100% slow requests (>1s)
  }
})

Available Presets

import { SamplingPresets } from 'autolemetry-edge/sampling'

// Development - 100% sampling
SamplingPresets.development()

// Production - 10% baseline, all errors, slow >1s
SamplingPresets.production()

// High traffic - 1% baseline, all errors, slow >1s
SamplingPresets.highTraffic()

// Debugging - errors only
SamplingPresets.debugging()

Custom Sampling

import { createCustomTailSampler } from 'autolemetry-edge/sampling'

const customSampler = createCustomTailSampler((trace) => {
  const span = trace.localRootSpan

  // Sample all /api/* requests
  if (span.attributes['http.route']?.toString().startsWith('/api/')) {
    return true
  }

  // Sample errors
  if (span.status.code === SpanStatusCode.ERROR) {
    return true
  }

  // Drop everything else
  return false
})

Events Integration

Track product events with automatic trace correlation:

import { publishEvent } from 'autolemetry-edge/events'

// Track user events
await publishEvent({
  name: 'order.completed',
  userId: '123',
  properties: {
    orderId: 'abc',
    amount: 99.99
  }
  // Automatically includes current trace ID
})

Logger

Zero-dependency logger with trace context:

import { createEdgeLogger } from 'autolemetry-edge/logger'

const log = createEdgeLogger('my-service')

log.info('Processing request', { userId: '123' })
log.error('Request failed', { error })
// Automatically includes trace ID, span ID

Testing

import { createTraceCollector, assertTraceCreated } from 'autolemetry-edge/testing'

// In your tests
const collector = createTraceCollector()

await myFunction()

assertTraceCreated(collector, 'myFunction')

Supported Runtimes

✅ Cloudflare Workers (use autolemetry-cloudflare)
✅ Vercel Edge Functions
✅ Netlify Edge Functions
✅ Deno Deploy
✅ AWS Lambda@Edge (with caveats)
✅ Any edge runtime with fetch() and AsyncLocalStorage support

Configuration

Service Configuration

init({
  service: {
    name: 'my-edge-function',
    version: '1.0.0',
    namespace: 'production'
  }
})

Exporter Configuration

init({
  exporter: {
    url: 'https://api.honeycomb.io/v1/traces',
    headers: {
      'x-honeycomb-team': process.env.HONEYCOMB_API_KEY
    }
  }
})

Dynamic Configuration

// Configuration can be a function
init((env) => ({
  service: { name: env.SERVICE_NAME },
  exporter: { url: env.OTEL_ENDPOINT }
}))

API Reference

Core Functions

`trace(fn)` / `trace(options, fn)`

Zero-boilerplate function tracing with automatic span management.

// Simple function
const handler = trace(async (request: Request) => {
  return new Response('OK')
})

// With options
const handler = trace({
  name: 'custom-name',
  attributesFromArgs: ([request]) => ({
    'http.method': request.method
  })
}, async (request: Request) => {
  return new Response('OK')
})

// Factory pattern (for context access)
const handler = trace(ctx => async (request: Request) => {
  ctx.setAttribute('custom', 'value')
  return new Response('OK')
})

`span(options, fn)`

Create a named span for a code block.

const result = await span(
  { name: 'database.query', attributes: { table: 'users' } },
  async (span) => {
    const data = await db.query('SELECT * FROM users')
    span.setAttribute('rows', data.length)
    return data
  }
)

`init(config)`

Initialize the OpenTelemetry SDK.

init({
  service: { name: 'my-app' },
  exporter: { url: '...' },
  sampling: { tailSampler: SamplingPresets.production() }
})

JSPM