autotel-edge 3.0.0

package/dist/sampling.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/sampling/index.ts"],"names":[],"mappings":"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","file":"sampling.js","sourcesContent":["/**\n * Sampling strategies for autotel-edge\n *\n * Provides intelligent sampling to reduce telemetry costs while capturing critical data.\n *\n * Key strategies:\n * - Always trace errors and slow requests (critical for debugging)\n * - Adaptive sampling based on load\n * - Baseline random sampling for normal traffic\n *\n * @example\n * ```typescript\n * import { createAdaptiveTailSampler } from 'autotel-edge/sampling'\n *\n * export default instrument(handler, {\n *   sampling: {\n *     tailSampler: createAdaptiveTailSampler({\n *       baselineSampleRate: 0.1,  // 10% of normal requests\n *       slowThresholdMs: 1000,     // Requests > 1s are \"slow\"\n *     })\n *   }\n * })\n * ```\n */\n\nimport type { TailSampleFn, LocalTrace } from '../types';\nimport type { ReadableSpan } from '@opentelemetry/sdk-trace-base';\n\nexport interface AdaptiveSamplerOptions {\n  /**\n   * Baseline sample rate for normal (successful, fast) requests\n   * @default 0.1 (10%)\n   */\n  baselineSampleRate?: number;\n\n  /**\n   * Threshold in milliseconds for \"slow\" requests\n   * Requests taking longer than this will always be trace\n   * @default 1000ms\n   */\n  slowThresholdMs?: number;\n\n  /**\n   * Always trace error spans\n   * @default true\n   */\n  alwaysSampleErrors?: boolean;\n\n  /**\n   * Always trace slow spans\n   * @default true\n   */\n  alwaysSampleSlow?: boolean;\n}\n\n/**\n * Create an adaptive tail sampler\n *\n * This sampler ensures you never miss critical issues while keeping costs down:\n * - Always traces errors (status code = ERROR)\n * - Always traces slow requests (duration >= slowThresholdMs)\n * - Uses baseline sample rate for successful fast requests\n *\n * **Recommended for production use.**\n *\n * @example\n * ```typescript\n * const tailSampler = createAdaptiveTailSampler({\n *   baselineSampleRate: 0.1,    // 10% of normal requests\n *   slowThresholdMs: 1000,       // Requests > 1s are \"slow\"\n *   alwaysSampleErrors: true,    // Always trace errors\n *   alwaysSampleSlow: true       // Always trace slow requests\n * })\n * ```\n */\nexport function createAdaptiveTailSampler(\n  options: AdaptiveSamplerOptions = {},\n): TailSampleFn {\n  const baselineSampleRate = options.baselineSampleRate ?? 0.1;\n  const slowThresholdMs = options.slowThresholdMs ?? 1000;\n  const alwaysSampleErrors = options.alwaysSampleErrors ?? true;\n  const alwaysSampleSlow = options.alwaysSampleSlow ?? true;\n\n  if (baselineSampleRate < 0 || baselineSampleRate > 1) {\n    throw new Error('Baseline sample rate must be between 0 and 1');\n  }\n\n  // Store baseline decisions using trace ID\n  const baselineDecisions = new Map<string, boolean>();\n\n  return (traceInfo: LocalTrace): boolean => {\n    const { traceId, localRootSpan } = traceInfo;\n\n    // Get or create baseline decision for this trace\n    if (!baselineDecisions.has(traceId)) {\n      baselineDecisions.set(traceId, Math.random() < baselineSampleRate);\n    }\n    const baselineDecision = baselineDecisions.get(traceId)!;\n\n    // Always keep errors (SpanStatusCode.ERROR = 2)\n    if (alwaysSampleErrors && localRootSpan.status.code === 2) {\n      return true;\n    }\n\n    // Always keep slow requests\n    if (alwaysSampleSlow) {\n      const duration = getDurationMs(localRootSpan);\n      if (duration >= slowThresholdMs) {\n        return true;\n      }\n    }\n\n    // Otherwise, use baseline decision\n    return baselineDecision;\n  };\n}\n\n/**\n * Create a simple random tail sampler\n *\n * Samples a fixed percentage of all traces regardless of outcome.\n *\n * @example\n * ```typescript\n * const tailSampler = createRandomTailSampler(0.1) // 10% of all requests\n * ```\n */\nexport function createRandomTailSampler(sampleRate: number): TailSampleFn {\n  if (sampleRate < 0 || sampleRate > 1) {\n    throw new Error('Sample rate must be between 0 and 1');\n  }\n\n  const decisions = new Map<string, boolean>();\n\n  return (traceInfo: LocalTrace): boolean => {\n    const { traceId } = traceInfo;\n\n    if (!decisions.has(traceId)) {\n      decisions.set(traceId, Math.random() < sampleRate);\n    }\n\n    return decisions.get(traceId)!;\n  };\n}\n\n/**\n * Create a tail sampler that keeps all errors\n *\n * Useful for debugging - captures all failures while dropping successful requests.\n *\n * @example\n * ```typescript\n * const tailSampler = createErrorOnlyTailSampler()\n * ```\n */\nexport function createErrorOnlyTailSampler(): TailSampleFn {\n  return (traceInfo: LocalTrace): boolean => {\n    // SpanStatusCode.ERROR = 2\n    return traceInfo.localRootSpan.status.code === 2;\n  };\n}\n\n/**\n * Create a tail sampler that keeps slow requests\n *\n * Useful for performance debugging - captures slow requests while dropping fast ones.\n *\n * @example\n * ```typescript\n * const tailSampler = createSlowOnlyTailSampler(1000) // Keep requests > 1s\n * ```\n */\nexport function createSlowOnlyTailSampler(thresholdMs: number): TailSampleFn {\n  return (traceInfo: LocalTrace): boolean => {\n    const duration = getDurationMs(traceInfo.localRootSpan);\n    return duration >= thresholdMs;\n  };\n}\n\n/**\n * Combine multiple tail samplers with OR logic\n *\n * Keeps a trace if ANY sampler returns true.\n *\n * @example\n * ```typescript\n * const tailSampler = combineTailSamplers(\n *   createErrorOnlyTailSampler(),\n *   createSlowOnlyTailSampler(1000),\n *   createRandomTailSampler(0.01)  // 1% baseline\n * )\n * ```\n */\nexport function combineTailSamplers(...samplers: TailSampleFn[]): TailSampleFn {\n  if (samplers.length === 0) {\n    throw new Error('combineTailSamplers requires at least one sampler');\n  }\n\n  return (traceInfo: LocalTrace): boolean => {\n    return samplers.some((sampler) => sampler(traceInfo));\n  };\n}\n\n/**\n * Create a tail sampler based on custom predicate\n *\n * @example\n * ```typescript\n * // Keep traces with specific attributes\n * const tailSampler = createCustomTailSampler((trace) => {\n *   const attrs = trace.localRootSpan.attributes\n *   return attrs['user.id'] === 'vip_123'\n * })\n * ```\n */\nexport function createCustomTailSampler(\n  predicate: (traceInfo: LocalTrace) => boolean,\n): TailSampleFn {\n  return predicate;\n}\n\n/**\n * Helper: Get span duration in milliseconds\n */\nfunction getDurationMs(span: ReadableSpan): number {\n  const start = span.startTime[0] * 1000 + span.startTime[1] / 1_000_000;\n  const end = span.endTime[0] * 1000 + span.endTime[1] / 1_000_000;\n  return end - start;\n}\n\n/**\n * Common presets for quick setup\n */\nexport const SamplingPresets = {\n  /**\n   * Production: 10% baseline, all errors, all slow (>1s)\n   * Recommended for most production workloads\n   */\n  production: (): TailSampleFn =>\n    createAdaptiveTailSampler({\n      baselineSampleRate: 0.1,\n      slowThresholdMs: 1000,\n    }),\n\n  /**\n   * High-traffic: 1% baseline, all errors, all slow (>2s)\n   * For high-volume services where cost is a concern\n   */\n  highTraffic: (): TailSampleFn =>\n    createAdaptiveTailSampler({\n      baselineSampleRate: 0.01,\n      slowThresholdMs: 2000,\n    }),\n\n  /**\n   * Debugging: All errors, all slow (>500ms), 50% baseline\n   * For active debugging sessions\n   */\n  debugging: (): TailSampleFn =>\n    createAdaptiveTailSampler({\n      baselineSampleRate: 0.5,\n      slowThresholdMs: 500,\n    }),\n\n  /**\n   * Development: 100% sampling\n   * For local development and testing\n   */\n  development: (): TailSampleFn => () => true,\n\n  /**\n   * Errors only: Capture all failures, drop all successes\n   * For error-focused monitoring\n   */\n  errorsOnly: (): TailSampleFn => createErrorOnlyTailSampler(),\n};\n"]}

package/dist/testing.d.ts

@@ -0,0 +1,2 @@
+
+export {  }

package/dist/testing.js

@@ -0,0 +1,3 @@
+
+//# sourceMappingURL=testing.js.map
+//# sourceMappingURL=testing.js.map

package/dist/testing.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"testing.js"}

package/dist/types-Dj85cPUj.d.ts

@@ -0,0 +1,182 @@
+import { Span, TextMapPropagator, SpanOptions, Context, Attributes } from '@opentelemetry/api';
+import { ReadableSpan, Sampler, SpanExporter, SpanProcessor } from '@opentelemetry/sdk-trace-base';
+
+/**
+ * Shared types for autotel-edge
+ */
+
+/**
+ * Trigger types for edge handlers
+ * Can be a Request or any vendor-specific trigger type
+ */
+type Trigger = Request | DOConstructorTrigger | 'do-alarm' | unknown;
+interface DOConstructorTrigger {
+    id: string;
+    name?: string;
+}
+/**
+ * Config types
+ */
+interface OTLPExporterConfig {
+    url: string;
+    headers?: Record<string, string>;
+}
+type ExporterConfig = OTLPExporterConfig | SpanExporter;
+interface ServiceConfig {
+    name: string;
+    namespace?: string;
+    version?: string;
+}
+interface ParentRatioSamplingConfig {
+    acceptRemote?: boolean;
+    ratio: number;
+}
+type HeadSamplerConf = Sampler | ParentRatioSamplingConfig;
+interface SamplingConfig<HS extends HeadSamplerConf = HeadSamplerConf> {
+    headSampler?: HS;
+    tailSampler?: TailSampleFn;
+}
+interface InstrumentationOptions {
+    instrumentGlobalFetch?: boolean;
+    instrumentGlobalCache?: boolean;
+    /**
+     * Disable instrumentation entirely (useful for local development)
+     * When enabled, the handler is returned as-is without any instrumentation
+     * @default false
+     */
+    disabled?: boolean;
+}
+/**
+ * Utility types
+ */
+type OrPromise<T> = T | Promise<T>;
+/**
+ * Adapter event types
+ */
+type FunnelStepStatus = 'started' | 'completed' | 'abandoned' | 'failed' | (string & {});
+type OutcomeStatus = 'success' | 'failure' | 'partial' | (string & {});
+interface EdgeEventBase {
+    [key: string]: unknown;
+    service: string;
+    timestamp: number;
+    attributes: Record<string, unknown>;
+    traceId?: string;
+    spanId?: string;
+    correlationId?: string;
+    name: string;
+}
+interface EdgeTrackEvent extends EdgeEventBase {
+    type: 'event';
+    event: string;
+}
+interface EdgeFunnelStepEvent extends EdgeEventBase {
+    type: 'funnel-step';
+    funnel: string;
+    status: FunnelStepStatus;
+}
+interface EdgeOutcomeEvent extends EdgeEventBase {
+    type: 'outcome';
+    operation: string;
+    outcome: OutcomeStatus;
+}
+interface EdgeValueEvent extends EdgeEventBase {
+    type: 'value';
+    metric: string;
+    value: number;
+}
+type EdgeEvent = EdgeTrackEvent | EdgeFunnelStepEvent | EdgeOutcomeEvent | EdgeValueEvent;
+type EdgeSubscriber = (event: EdgeEvent) => OrPromise<void>;
+interface FetcherConfig {
+    includeTraceContext?: boolean | ((request: Request) => boolean);
+}
+interface PostProcessParams {
+    /**
+     * The request object that was passed to the fetch handler.
+     */
+    request: Request;
+    /**
+     * The generated response object.
+     */
+    response: Response;
+    /**
+     * A readable version of the span object that can be used to access the span's attributes and events.
+     */
+    readable: ReadableSpan;
+}
+interface FetchHandlerConfig {
+    /**
+     * Whether to enable context propagation for incoming requests to `fetch`.
+     * This enables or disables distributed tracing from W3C Trace Context headers.
+     * @default true
+     */
+    acceptTraceContext?: boolean | ((request: Request) => boolean);
+    /**
+     * Allows further customization of the generated span, based on the request/response data.
+     */
+    postProcess?: (span: Span, ctx: PostProcessParams) => void;
+}
+interface HandlerConfig {
+    fetch?: FetchHandlerConfig;
+}
+interface EdgeConfigBase {
+    service: ServiceConfig;
+    handlers?: HandlerConfig;
+    fetch?: FetcherConfig;
+    postProcessor?: PostProcessorFn;
+    sampling?: SamplingConfig;
+    propagator?: TextMapPropagator;
+    instrumentation?: InstrumentationOptions;
+    subscribers?: EdgeSubscriber[];
+}
+interface EdgeConfigExporter extends EdgeConfigBase {
+    exporter: ExporterConfig;
+}
+interface EdgeConfigSpanProcessors extends EdgeConfigBase {
+    spanProcessors: SpanProcessor | SpanProcessor[];
+}
+type EdgeConfig = EdgeConfigExporter | EdgeConfigSpanProcessors;
+interface ResolvedEdgeConfig extends EdgeConfigBase {
+    handlers: Required<HandlerConfig>;
+    fetch: Required<FetcherConfig>;
+    postProcessor: PostProcessorFn;
+    sampling: Required<SamplingConfig<Sampler>>;
+    spanProcessors: SpanProcessor[];
+    propagator: TextMapPropagator;
+    instrumentation: InstrumentationOptions;
+    subscribers: EdgeSubscriber[];
+}
+/**
+ * Function types
+ */
+type ResolveConfigFn<Env = any> = (env: Env, trigger: Trigger) => EdgeConfig;
+type ConfigurationOption = EdgeConfig | ResolveConfigFn;
+type PostProcessorFn = (spans: ReadableSpan[]) => ReadableSpan[];
+type TailSampleFn = (traceInfo: LocalTrace) => boolean;
+interface LocalTrace {
+    traceId: string;
+    spans: ReadableSpan[];
+    localRootSpan: ReadableSpan;
+}
+/**
+ * Span processor with flush support
+ */
+type TraceFlushableSpanProcessor = SpanProcessor & {
+    forceFlush: (traceId?: string) => Promise<void>;
+};
+/**
+ * Handler instrumentation
+ */
+interface InitialSpanInfo {
+    name: string;
+    options: SpanOptions;
+    context?: Context;
+}
+interface HandlerInstrumentation<T extends Trigger, R extends any> {
+    getInitialSpanInfo: (trigger: T) => InitialSpanInfo;
+    getAttributesFromResult?: (result: Awaited<R>) => Attributes;
+    instrumentTrigger?: (trigger: T) => T;
+    executionSucces?: (span: Span, trigger: T, result: Awaited<R>) => void;
+    executionFailed?: (span: Span, trigger: T, error?: any) => void;
+}
+
+export type { ConfigurationOption as C, EdgeEvent as E, FunnelStepStatus as F, HandlerInstrumentation as H, InstrumentationOptions as I, LocalTrace as L, OrPromise as O, PostProcessorFn as P, ResolvedEdgeConfig as R, ServiceConfig as S, TailSampleFn as T, OutcomeStatus as a, EdgeTrackEvent as b, EdgeFunnelStepEvent as c, EdgeOutcomeEvent as d, EdgeValueEvent as e, OTLPExporterConfig as f, EdgeConfig as g, Trigger as h, ExporterConfig as i, SamplingConfig as j, ResolveConfigFn as k, TraceFlushableSpanProcessor as l, InitialSpanInfo as m, EdgeSubscriber as n };

package/package.json

@@ -0,0 +1,88 @@
+{
+  "name": "autotel-edge",
+  "version": "3.0.0",
+  "description": "Vendor-agnostic OpenTelemetry for edge runtimes - foundation for Cloudflare, Vercel, Netlify, Deno",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./sampling": {
+      "types": "./dist/sampling.d.ts",
+      "import": "./dist/sampling.js"
+    },
+    "./events": {
+      "types": "./dist/events.d.ts",
+      "import": "./dist/events.js"
+    },
+    "./logger": {
+      "types": "./dist/logger.d.ts",
+      "import": "./dist/logger.js"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "import": "./dist/testing.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "keywords": [
+    "opentelemetry",
+    "otel",
+    "edge",
+    "serverless",
+    "observability",
+    "tracing",
+    "vendor-agnostic",
+    "cloudflare",
+    "vercel",
+    "netlify",
+    "deno"
+  ],
+  "author": "Jag Reehal <jag@jagreehal.com> (https://jagreehal.com)",
+  "license": "MIT",
+  "dependencies": {
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/core": "^2.2.0",
+    "@opentelemetry/otlp-exporter-base": "^0.208.0",
+    "@opentelemetry/otlp-transformer": "^0.208.0",
+    "@opentelemetry/resources": "^2.2.0",
+    "@opentelemetry/sdk-trace-base": "^2.2.0",
+    "@opentelemetry/semantic-conventions": "^1.38.0"
+  },
+  "devDependencies": {
+    "@opentelemetry/context-async-hooks": "^2.2.0",
+    "@types/node": "^24.10.1",
+    "rimraf": "^6.1.2",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.13",
+    "vitest-mock-extended": "^3.1.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jagreehal/autotel",
+    "directory": "packages/autotel-edge"
+  },
+  "bugs": {
+    "url": "https://github.com/jagreehal/autotel/issues"
+  },
+  "homepage": "https://github.com/jagreehal/autotel/tree/main/packages/autotel-edge#readme",
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "lint": "npx eslint src/**/*.ts",
+    "lint:fix": "npx eslint src/**/*.ts --fix",
+    "type-check": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "clean": "rimraf dist"
+  }
+}

package/src/api/logger.test.ts

@@ -0,0 +1,367 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { createEdgeLogger, runWithLogLevel, getActiveLogLevel } from './logger';
+import { trace } from '@opentelemetry/api';
+
+describe('Edge Logger', () => {
+  let consoleLogSpy: any;
+  let consoleErrorSpy: any;
+  let consoleWarnSpy: any;
+  let consoleInfoSpy: any;
+
+  beforeEach(() => {
+    consoleLogSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+    consoleWarnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    consoleInfoSpy = vi.spyOn(console, 'info').mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    consoleLogSpy.mockRestore();
+    consoleErrorSpy.mockRestore();
+    consoleWarnSpy.mockRestore();
+    consoleInfoSpy.mockRestore();
+  });
+
+  describe('createEdgeLogger', () => {
+    it('should create a logger with service name', () => {
+      const logger = createEdgeLogger('test-service');
+      expect(logger).toBeDefined();
+      expect(logger.info).toBeDefined();
+      expect(logger.error).toBeDefined();
+      expect(logger.warn).toBeDefined();
+      expect(logger.debug).toBeDefined();
+    });
+
+    it('should log info messages with service name', () => {
+      const logger = createEdgeLogger('test-service');
+      logger.info('test message', { key: 'value' });
+
+      expect(consoleLogSpy).toHaveBeenCalledOnce();
+      const logOutput = JSON.parse(consoleLogSpy.mock.calls[0][0]);
+
+      expect(logOutput).toMatchObject({
+        level: 'info',
+        service: 'test-service',
+        msg: 'test message',
+        key: 'value',
+      });
+      expect(logOutput.timestamp).toBeDefined();
+    });
+
+    it('should log error messages', () => {
+      const logger = createEdgeLogger('test-service');
+      const error = new Error('test error');
+      logger.error('error occurred', error);
+
+      expect(consoleLogSpy).toHaveBeenCalledOnce();
+      const logOutput = JSON.parse(consoleLogSpy.mock.calls[0][0]);
+
+      expect(logOutput).toMatchObject({
+        level: 'error',
+        service: 'test-service',
+        msg: 'error occurred',
+        error: 'test error',
+      });
+      expect(logOutput.stack).toBeDefined();
+    });
+
+    it('should log warning messages', () => {
+      const logger = createEdgeLogger('test-service');
+      logger.warn('warning message', { reason: 'test' });
+
+      expect(consoleLogSpy).toHaveBeenCalledOnce();
+      const logOutput = JSON.parse(consoleLogSpy.mock.calls[0][0]);
+
+      expect(logOutput).toMatchObject({
+        level: 'warn',
+        service: 'test-service',
+        msg: 'warning message',
+        reason: 'test',
+      });
+    });
+
+    it('should log debug messages when level is set to debug', () => {
+      const logger = createEdgeLogger('test-service', { level: 'debug' });
+      logger.debug('debug message', { detail: 'verbose' });
+
+      expect(consoleLogSpy).toHaveBeenCalledOnce();
+      const logOutput = JSON.parse(consoleLogSpy.mock.calls[0][0]);
+
+      expect(logOutput).toMatchObject({
+        level: 'debug',
+        service: 'test-service',
+        msg: 'debug message',
+        detail: 'verbose',
+      });
+    });
+
+    it('should not log debug messages when level is info (default)', () => {
+      const logger = createEdgeLogger('test-service');
+      logger.debug('debug message', { detail: 'verbose' });
+
+      expect(consoleLogSpy).not.toHaveBeenCalled();
+    });
+
+    it('should include trace context when available', () => {
+      const logger = createEdgeLogger('test-service');
+
+      // Create a mock tracer and span
+      const mockSpan = {
+        spanContext: () => ({
+          traceId: 'test-trace-id-16chars',
+          spanId: 'test-span-id',
+          traceFlags: 1,
+        }),
+        setAttribute: vi.fn(),
+        setStatus: vi.fn(),
+        recordException: vi.fn(),
+        end: vi.fn(),
+        isRecording: () => true,
+        updateName: vi.fn(),
+        addEvent: vi.fn(),
+        setAttributes: vi.fn(),
+      };
+
+      // Mock trace.getActiveSpan to return our span
+      const getActiveSpanSpy = vi.spyOn(trace, 'getActiveSpan').mockReturnValue(mockSpan as any);
+
+      logger.info('message with trace');
+
+      expect(consoleLogSpy).toHaveBeenCalledOnce();
+      const logOutput = JSON.parse(consoleLogSpy.mock.calls[0][0]);
+
+      expect(logOutput).toMatchObject({
+        level: 'info',
+        service: 'test-service',
+        msg: 'message with trace',
+        traceId: 'test-trace-id-16chars',
+        spanId: 'test-span-id',
+        correlationId: 'test-trace-id-16',
+      });
+
+      getActiveSpanSpy.mockRestore();
+    });
+
+    it('should handle non-Error objects', () => {
+      const logger = createEdgeLogger('test-service');
+      const errorObject = { message: 'simple error' };
+      logger.error('error occurred', errorObject);
+
+      expect(consoleLogSpy).toHaveBeenCalledOnce();
+      const logOutput = JSON.parse(consoleLogSpy.mock.calls[0][0]);
+
+      expect(logOutput).toMatchObject({
+        level: 'error',
+        service: 'test-service',
+        msg: 'error occurred',
+        error: '[object Object]',
+      });
+    });
+
+    it('should handle null and undefined context gracefully', () => {
+      const logger = createEdgeLogger('test-service');
+      logger.info('message with null', null as any);
+      logger.info('message with undefined', undefined as any);
+
+      expect(consoleLogSpy).toHaveBeenCalledTimes(2);
+
+      const log1 = JSON.parse(consoleLogSpy.mock.calls[0][0]);
+      const log2 = JSON.parse(consoleLogSpy.mock.calls[1][0]);
+
+      expect(log1.msg).toBe('message with null');
+      expect(log2.msg).toBe('message with undefined');
+    });
+
+    it('should accept a single context object', () => {
+      const logger = createEdgeLogger('test-service');
+      logger.info('message', { a: 1, b: 2, c: 3 });
+
+      expect(consoleLogSpy).toHaveBeenCalledOnce();
+      const logOutput = JSON.parse(consoleLogSpy.mock.calls[0][0]);
+
+      expect(logOutput).toMatchObject({
+        level: 'info',
+        msg: 'message',
+        a: 1,
+        b: 2,
+        c: 3,
+      });
+    });
+
+    it('should preserve timestamp format', () => {
+      const logger = createEdgeLogger('test-service');
+      logger.info('test');
+
+      expect(consoleLogSpy).toHaveBeenCalledOnce();
+      const logOutput = JSON.parse(consoleLogSpy.mock.calls[0][0]);
+
+      expect(logOutput.timestamp).toMatch(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/);
+    });
+  });
+
+  describe('Pretty mode', () => {
+    it('should format logs in pretty mode', () => {
+      const logger = createEdgeLogger('test-service', { pretty: true });
+      logger.info('pretty message', { key: 'value' });
+
+      expect(consoleLogSpy).toHaveBeenCalledOnce();
+      const logOutput = consoleLogSpy.mock.calls[0][0];
+
+      // In pretty mode, output is a formatted string, not JSON
+      expect(typeof logOutput).toBe('string');
+      expect(logOutput).toContain('INFO');
+      expect(logOutput).toContain('test-service');
+      expect(logOutput).toContain('pretty message');
+    });
+
+    it('should format errors in pretty mode', () => {
+      const logger = createEdgeLogger('test-service', { pretty: true });
+      const error = new Error('test error');
+      logger.error('error occurred', error);
+
+      expect(consoleLogSpy).toHaveBeenCalledOnce();
+      const logOutput = consoleLogSpy.mock.calls[0][0];
+
+      expect(typeof logOutput).toBe('string');
+      expect(logOutput).toContain('ERROR');
+      expect(logOutput).toContain('test-service');
+      expect(logOutput).toContain('error occurred');
+    });
+  });
+
+  describe('Edge cases', () => {
+    it('should throw on circular references in context', () => {
+      const logger = createEdgeLogger('test-service');
+      const circular: any = { a: 1 };
+      circular.self = circular;
+
+      // JSON.stringify will throw on circular references
+      expect(() => {
+        logger.info('circular', circular);
+      }).toThrow(/circular/i);
+    });
+
+    it('should handle very long messages', () => {
+      const logger = createEdgeLogger('test-service');
+      const longMessage = 'a'.repeat(10_000);
+
+      logger.info(longMessage);
+
+      expect(consoleLogSpy).toHaveBeenCalledOnce();
+      const logOutput = JSON.parse(consoleLogSpy.mock.calls[0][0]);
+      expect(logOutput.msg).toBe(longMessage);
+    });
+
+    it('should handle special characters in messages', () => {
+      const logger = createEdgeLogger('test-service');
+      const specialMessage = 'Hello\nWorld\t"quoted"\r\nNew Line';
+
+      logger.info(specialMessage);
+
+      expect(consoleLogSpy).toHaveBeenCalledOnce();
+      const logOutput = JSON.parse(consoleLogSpy.mock.calls[0][0]);
+      expect(logOutput.msg).toBe(specialMessage);
+    });
+  });
+
+  describe('Dynamic log level control', () => {
+    it('should override log level via runWithLogLevel', () => {
+      const logger = createEdgeLogger('test-service', { level: 'info' });
+
+      // Normal behavior: debug filtered out
+      logger.debug('outside context');
+      expect(consoleLogSpy).not.toHaveBeenCalled();
+
+      // Inside debug context: debug logged
+      runWithLogLevel('debug', () => {
+        logger.debug('inside debug context');
+      });
+      expect(consoleLogSpy).toHaveBeenCalledOnce();
+
+      // Back to normal: debug filtered out again
+      logger.debug('outside context again');
+      expect(consoleLogSpy).toHaveBeenCalledOnce();
+    });
+
+    it('should support none level to temporarily disable logging', () => {
+      const logger = createEdgeLogger('test-service', { level: 'info' });
+
+      logger.info('before none');
+      const callsBeforeNone = consoleLogSpy.mock.calls.length;
+
+      runWithLogLevel('none', () => {
+        logger.info('inside none context');
+        logger.error('even errors suppressed');
+      });
+      expect(consoleLogSpy.mock.calls.length).toBe(callsBeforeNone); // No new logs
+
+      logger.info('after none');
+      expect(consoleLogSpy.mock.calls.length).toBe(callsBeforeNone + 1);
+    });
+
+    it('should return value from callback', () => {
+      const result = runWithLogLevel('debug', () => {
+        return 42;
+      });
+      expect(result).toBe(42);
+    });
+
+    it('should propagate async results', async () => {
+      const result = await runWithLogLevel('debug', async () => {
+        return 'async value';
+      });
+      expect(result).toBe('async value');
+    });
+
+    it('should allow raising log level temporarily', () => {
+      const logger = createEdgeLogger('test-service', { level: 'error' });
+
+      logger.info('normal info');
+      logger.warn('normal warn');
+      expect(consoleLogSpy).not.toHaveBeenCalled();
+
+      runWithLogLevel('info', () => {
+        logger.info('temporary info');
+        logger.warn('temporary warn');
+      });
+      expect(consoleLogSpy).toHaveBeenCalledTimes(2);
+    });
+
+    it('should isolate log level changes to context', () => {
+      const logger = createEdgeLogger('test-service', { level: 'info' });
+
+      runWithLogLevel('debug', () => {
+        logger.debug('context 1 - debug');
+        expect(consoleLogSpy).toHaveBeenCalledOnce();
+      });
+
+      runWithLogLevel('error', () => {
+        logger.info('context 2 - info should be filtered');
+        expect(consoleLogSpy).toHaveBeenCalledOnce(); // No new logs
+      });
+    });
+  });
+
+  describe('getActiveLogLevel', () => {
+    it('should return undefined when no active level', () => {
+      expect(getActiveLogLevel()).toBeUndefined();
+    });
+
+    it('should return active level inside runWithLogLevel', () => {
+      runWithLogLevel('debug', () => {
+        expect(getActiveLogLevel()).toBe('debug');
+      });
+
+      runWithLogLevel('error', () => {
+        expect(getActiveLogLevel()).toBe('error');
+      });
+    });
+
+    it('should reset after runWithLogLevel completes', () => {
+      runWithLogLevel('debug', () => {
+        expect(getActiveLogLevel()).toBe('debug');
+      });
+      expect(getActiveLogLevel()).toBeUndefined();
+    });
+  });
+});