autotel-edge 3.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Jag Reehal 2025
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,333 @@
+# autotel-edge
+
+**Vendor-agnostic OpenTelemetry for edge runtimes** - the foundation for Cloudflare Workers, Vercel Edge, Netlify Edge, Deno Deploy, and more.
+
+[![npm version](https://badge.fury.io/js/autotel-edge.svg)](https://www.npmjs.com/package/autotel-edge)
+[![Bundle Size](https://img.shields.io/bundlephobia/minzip/autotel-edge)](https://bundlephobia.com/package/autotel-edge)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Overview
+
+`autotel-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 **[autotel-cloudflare](../autotel-cloudflare)** instead, which includes complete Cloudflare bindings instrumentation (KV, R2, D1, etc.) and handler wrappers.
+
+### When to Use autotel-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 `autotel-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
+
+```bash
+npm install autotel-edge
+# or
+pnpm add autotel-edge
+# or
+yarn add autotel-edge
+```
+
+## Quick Start
+
+### Basic Usage
+
+```typescript
+import { trace, init } from 'autotel-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)
+
+```typescript
+import { trace } from 'autotel-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:
+
+```typescript
+// Core API
+import { trace, span, init } from 'autotel-edge'
+
+// Sampling strategies
+import { createAdaptiveSampler, SamplingPresets } from 'autotel-edge/sampling'
+
+// Events system
+import { createEdgeSubscribers, publishEvent } from 'autotel-edge/events'
+
+// Logger
+import { createEdgeLogger } from 'autotel-edge/logger'
+
+// Testing utilities
+import { createTraceCollector, assertTraceCreated } from 'autotel-edge/testing'
+```
+
+## Sampling Strategies
+
+### Adaptive Sampling (Recommended for Production)
+
+```typescript
+import { SamplingPresets } from 'autotel-edge/sampling'
+
+init({
+  service: { name: 'my-app' },
+  exporter: { url: '...' },
+  sampling: {
+    tailSampler: SamplingPresets.production()
+    // 10% baseline, 100% errors, 100% slow requests (>1s)
+  }
+})
+```
+
+### Available Presets
+
+```typescript
+import { SamplingPresets } from 'autotel-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
+
+```typescript
+import { createCustomTailSampler } from 'autotel-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:
+
+```typescript
+import { publishEvent } from 'autotel-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:
+
+```typescript
+import { createEdgeLogger } from 'autotel-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
+
+```typescript
+import { createTraceCollector, assertTraceCreated } from 'autotel-edge/testing'
+
+// In your tests
+const collector = createTraceCollector()
+
+await myFunction()
+
+assertTraceCreated(collector, 'myFunction')
+```
+
+## Supported Runtimes
+
+- ✅ Cloudflare Workers (use [autotel-cloudflare](../autotel-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
+
+```typescript
+init({
+  service: {
+    name: 'my-edge-function',
+    version: '1.0.0',
+    namespace: 'production'
+  }
+})
+```
+
+### Exporter Configuration
+
+```typescript
+init({
+  exporter: {
+    url: 'https://api.honeycomb.io/v1/traces',
+    headers: {
+      'x-honeycomb-team': process.env.HONEYCOMB_API_KEY
+    }
+  }
+})
+```
+
+### Dynamic Configuration
+
+```typescript
+// 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.
+
+```typescript
+// 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.
+
+```typescript
+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.
+
+```typescript
+init({
+  service: { name: 'my-app' },
+  exporter: { url: '...' },
+  sampling: { tailSampler: SamplingPresets.production() }
+})
+```
+
+## Bundle Size
+
+- **Core:** ~20KB minified (~8KB gzipped)
+- **With all entry points:** ~25KB minified (~10KB gzipped)
+- **Tree-shakeable:** Import only what you need
+
+## Vendor Packages
+
+- **[autotel-cloudflare](../autotel-cloudflare)** - Cloudflare Workers (with KV, R2, D1, etc.)
+- **autotel-vercel** - Coming soon
+- **autotel-netlify** - Coming soon
+
+## 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)

package/dist/chunk-F32WSLNX.js

@@ -0,0 +1,309 @@
+import { ExportResultCode, W3CTraceContextPropagator } from '@opentelemetry/core';
+import { OTLPExporterError } from '@opentelemetry/otlp-exporter-base';
+import { JsonTraceSerializer } from '@opentelemetry/otlp-transformer';
+import { ParentBasedSampler, AlwaysOnSampler } from '@opentelemetry/sdk-trace-base';
+import { createContextKey, context } from '@opentelemetry/api';
+
+// src/core/exporter.ts
+var PACKAGE_VERSION = "3.0.0";
+var defaultHeaders = {
+  accept: "application/json",
+  "content-type": "application/json",
+  "user-agent": `autotel-edge v${PACKAGE_VERSION}`
+};
+var OTLPExporter = class {
+  headers;
+  url;
+  constructor(config) {
+    this.url = config.url;
+    this.headers = Object.assign({}, defaultHeaders, config.headers);
+  }
+  export(items, resultCallback) {
+    this._export(items).then(() => {
+      resultCallback({ code: ExportResultCode.SUCCESS });
+    }).catch((error) => {
+      resultCallback({ code: ExportResultCode.FAILED, error });
+    });
+  }
+  _export(items) {
+    return new Promise((resolve, reject) => {
+      try {
+        this.send(items, resolve, reject);
+      } catch (error) {
+        reject(error);
+      }
+    });
+  }
+  send(items, onSuccess, onError) {
+    const decoder = new TextDecoder();
+    const exportMessage = JsonTraceSerializer.serializeRequest(items);
+    const body = decoder.decode(exportMessage);
+    const params = {
+      method: "POST",
+      headers: this.headers,
+      body
+    };
+    fetch(this.url, params).then((response) => {
+      if (response.ok) {
+        onSuccess();
+      } else {
+        onError(
+          new OTLPExporterError(
+            `Exporter received a statusCode: ${response.status}`
+          )
+        );
+      }
+    }).catch((error) => {
+      onError(
+        new OTLPExporterError(
+          `Exception during export: ${error.toString()}`,
+          error.code,
+          error.stack
+        )
+      );
+    });
+  }
+  async shutdown() {
+  }
+};
+
+// src/types.ts
+function isSpanProcessorConfig(config) {
+  return !!config.spanProcessors;
+}
+
+// src/core/spanprocessor.ts
+var SpanProcessorWithFlush = class {
+  exporter;
+  postProcessor;
+  spans = /* @__PURE__ */ new Map();
+  constructor(exporter, postProcessor) {
+    this.exporter = exporter;
+    this.postProcessor = postProcessor;
+  }
+  onStart(_span, _parentContext) {
+  }
+  onEnd(span) {
+    const traceId = span.spanContext().traceId;
+    if (!this.spans.has(traceId)) {
+      this.spans.set(traceId, []);
+    }
+    this.spans.get(traceId).push(span);
+  }
+  /**
+   * Force flush spans for a specific trace
+   */
+  async forceFlush(traceId) {
+    if (traceId) {
+      const spans = this.spans.get(traceId);
+      if (spans && spans.length > 0) {
+        await this.exportSpans(spans);
+        this.spans.delete(traceId);
+      }
+    } else {
+      const promises = [];
+      for (const [id, spans] of this.spans.entries()) {
+        promises.push(this.exportSpans(spans));
+        this.spans.delete(id);
+      }
+      await Promise.all(promises);
+    }
+  }
+  async shutdown() {
+    await this.forceFlush();
+    if (this.exporter) {
+      await this.exporter.shutdown();
+    }
+  }
+  /**
+   * Export spans with post-processing
+   * Errors are caught and logged but don't throw to prevent worker instability
+   */
+  async exportSpans(spans) {
+    if (spans.length === 0) return;
+    if (!this.exporter) return;
+    let processedSpans = spans;
+    if (this.postProcessor) {
+      try {
+        processedSpans = this.postProcessor(spans);
+      } catch (error) {
+        console.error("[autotel-edge] Post-processor error:", error);
+        processedSpans = spans;
+      }
+    }
+    return new Promise((resolve) => {
+      this.exporter.export(processedSpans, (result) => {
+        if (result.code === 0) {
+          resolve();
+        } else {
+          console.error(
+            "[autotel-edge] Exporter error:",
+            result.error?.message || "Unknown error"
+          );
+          resolve();
+        }
+      });
+    });
+  }
+};
+var TailSamplingSpanProcessor = class {
+  wrapped;
+  tailSampler;
+  traces = /* @__PURE__ */ new Map();
+  constructor(exporter, postProcessor, tailSampler) {
+    this.wrapped = new SpanProcessorWithFlush(exporter, postProcessor);
+    this.tailSampler = tailSampler;
+  }
+  onStart(span, parentContext) {
+    this.wrapped.onStart(span, parentContext);
+  }
+  onEnd(span) {
+    const traceId = span.spanContext().traceId;
+    const spanId = span.spanContext().spanId;
+    const parentSpanId = "parentSpanId" in span ? span.parentSpanId : void 0;
+    if (!this.traces.has(traceId)) {
+      this.traces.set(traceId, {
+        traceId,
+        spans: [],
+        localRootSpan: void 0
+        // Will be set when we identify the local root
+      });
+    }
+    const trace = this.traces.get(traceId);
+    const hasLocalParent = parentSpanId && trace.spans.some((s) => s.spanContext().spanId === parentSpanId);
+    if (!hasLocalParent) {
+      trace.localRootSpan = span;
+    }
+    trace.spans.push(span);
+    const isDefinitiveRoot = !parentSpanId;
+    const shouldAutoFlush = isDefinitiveRoot && trace.localRootSpan && trace.localRootSpan.spanContext().spanId === spanId;
+    if (shouldAutoFlush) {
+      if (this.tailSampler) {
+        const shouldKeep = this.tailSampler(trace);
+        if (shouldKeep) {
+          for (const bufferedSpan of trace.spans) {
+            this.wrapped.onEnd(bufferedSpan);
+          }
+          void this.wrapped.forceFlush(traceId);
+        }
+      } else {
+        for (const bufferedSpan of trace.spans) {
+          this.wrapped.onEnd(bufferedSpan);
+        }
+        void this.wrapped.forceFlush(traceId);
+      }
+      this.traces.delete(traceId);
+    }
+  }
+  async forceFlush(traceId) {
+    if (traceId) {
+      const trace = this.traces.get(traceId);
+      if (trace) {
+        if (!trace.localRootSpan && trace.spans.length > 0) {
+          trace.localRootSpan = trace.spans[0];
+        }
+        if (this.tailSampler) {
+          const shouldKeep = this.tailSampler(trace);
+          if (shouldKeep) {
+            for (const bufferedSpan of trace.spans) {
+              this.wrapped.onEnd(bufferedSpan);
+            }
+          }
+        } else {
+          for (const bufferedSpan of trace.spans) {
+            this.wrapped.onEnd(bufferedSpan);
+          }
+        }
+        this.traces.delete(traceId);
+      }
+    }
+    return this.wrapped.forceFlush(traceId);
+  }
+  async shutdown() {
+    this.traces.clear();
+    return this.wrapped.shutdown();
+  }
+};
+
+// src/core/config.ts
+var CONFIG_KEY = createContextKey("autotel-edge-config");
+function getActiveConfig() {
+  const value = context.active().getValue(CONFIG_KEY);
+  return value ?? null;
+}
+function setConfig(config) {
+  return context.active().setValue(CONFIG_KEY, config);
+}
+function parseConfig(config) {
+  const headSampler = config.sampling?.headSampler ?? new ParentBasedSampler({
+    root: new AlwaysOnSampler()
+  });
+  const parsedHeadSampler = typeof headSampler === "object" && "ratio" in headSampler ? createParentRatioSampler(headSampler) : headSampler;
+  const tailSampler = config.sampling?.tailSampler ?? ((traceInfo) => {
+    const localRootSpan = traceInfo.localRootSpan;
+    const ctx = localRootSpan.spanContext();
+    return (ctx.traceFlags & 1) === 1 || localRootSpan.status.code === 2;
+  });
+  const spanProcessors = isSpanProcessorConfig(config) ? Array.isArray(config.spanProcessors) ? config.spanProcessors : [config.spanProcessors] : [
+    // Use TailSamplingSpanProcessor to enable tail sampling
+    new TailSamplingSpanProcessor(
+      typeof config.exporter === "object" && "url" in config.exporter ? new OTLPExporter(config.exporter) : config.exporter,
+      config.postProcessor,
+      tailSampler
+      // Wire up the tail sampler!
+    )
+  ];
+  const resolved = {
+    service: config.service,
+    handlers: {
+      fetch: config.handlers?.fetch ?? {}
+    },
+    fetch: {
+      includeTraceContext: config.fetch?.includeTraceContext ?? true
+    },
+    postProcessor: config.postProcessor ?? ((spans) => spans),
+    sampling: {
+      headSampler: parsedHeadSampler,
+      tailSampler
+    },
+    spanProcessors,
+    propagator: config.propagator ?? new W3CTraceContextPropagator(),
+    instrumentation: {
+      instrumentGlobalFetch: config.instrumentation?.instrumentGlobalFetch ?? true,
+      instrumentGlobalCache: config.instrumentation?.instrumentGlobalCache ?? false,
+      disabled: config.instrumentation?.disabled ?? false
+    },
+    subscribers: config.subscribers ?? []
+  };
+  return resolved;
+}
+function createParentRatioSampler(config) {
+  const { ratio, acceptRemote = true } = config;
+  const ratioSampler = {
+    shouldSample: () => ({
+      decision: Math.random() < ratio ? 1 : 0,
+      // RECORD_AND_SAMPLED : NOT_RECORD
+      attributes: {}
+    }),
+    toString: () => `ParentRatioSampler{ratio=${ratio}}`
+  };
+  if (acceptRemote) {
+    return new ParentBasedSampler({ root: ratioSampler });
+  }
+  return ratioSampler;
+}
+function createInitialiser(config) {
+  if (typeof config === "function") {
+    return (env, trigger) => {
+      const conf = parseConfig(config(env, trigger));
+      return conf;
+    };
+  } else {
+    const parsed = parseConfig(config);
+    return () => parsed;
+  }
+}
+
+export { OTLPExporter, createInitialiser, getActiveConfig, parseConfig, setConfig };
+//# sourceMappingURL=chunk-F32WSLNX.js.map
+//# sourceMappingURL=chunk-F32WSLNX.js.map