autotel-cloudflare 2.11.0 → 2.13.0

package/src/bindings/analytics-engine.test.ts

@@ -0,0 +1,160 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { instrumentAnalyticsEngine } from './analytics-engine';
+import { trace, SpanStatusCode, SpanKind } from '@opentelemetry/api';
+
+describe('Analytics Engine Instrumentation', () => {
+  let mockTracer: any;
+  let mockSpan: any;
+  let getTracerSpy: any;
+  let mockAE: any;
+
+  beforeEach(() => {
+    mockSpan = {
+      spanContext: () => ({
+        traceId: 'test-trace-id',
+        spanId: 'test-span-id',
+        traceFlags: 1,
+      }),
+      setAttribute: vi.fn(),
+      setAttributes: vi.fn(),
+      setStatus: vi.fn(),
+      recordException: vi.fn(),
+      end: vi.fn(),
+      isRecording: () => true,
+      updateName: vi.fn(),
+      addEvent: vi.fn(),
+    };
+
+    mockTracer = {
+      startActiveSpan: vi.fn((name, options, fn) => {
+        return fn(mockSpan);
+      }),
+    };
+
+    getTracerSpy = vi.spyOn(trace, 'getTracer').mockReturnValue(mockTracer as any);
+
+    mockAE = {
+      writeDataPoint: vi.fn(),
+      someOtherMethod: vi.fn(() => 'passthrough-value'),
+    };
+  });
+
+  afterEach(() => {
+    getTracerSpy.mockRestore();
+  });
+
+  describe('writeDataPoint()', () => {
+    it('should create span with correct attributes', () => {
+      const instrumented = instrumentAnalyticsEngine(mockAE, 'my-dataset');
+
+      instrumented.writeDataPoint({
+        indexes: ['idx1'],
+        doubles: [1, 2],
+        blobs: ['blob1'],
+      });
+
+      expect(mockTracer.startActiveSpan).toHaveBeenCalledTimes(1);
+
+      const [spanName, spanOptions] = mockTracer.startActiveSpan.mock.calls[0];
+      expect(spanName).toBe('AnalyticsEngine my-dataset: writeDataPoint');
+      expect(spanOptions.kind).toBe(SpanKind.CLIENT);
+      expect(spanOptions.attributes['analytics.system']).toBe('cloudflare-analytics-engine');
+      expect(spanOptions.attributes['analytics.operation']).toBe('writeDataPoint');
+    });
+
+    it('should record indexes_count, doubles_count, blobs_count', () => {
+      const instrumented = instrumentAnalyticsEngine(mockAE, 'my-dataset');
+
+      instrumented.writeDataPoint({
+        indexes: ['idx1', 'idx2'],
+        doubles: [1, 2, 3],
+        blobs: ['blob1'],
+      });
+
+      const spanOptions = mockTracer.startActiveSpan.mock.calls[0][1];
+      expect(spanOptions.attributes['analytics.indexes_count']).toBe(2);
+      expect(spanOptions.attributes['analytics.doubles_count']).toBe(3);
+      expect(spanOptions.attributes['analytics.blobs_count']).toBe(1);
+    });
+
+    it('should handle a single index (non-array) by recording indexes_count as 1', () => {
+      const instrumented = instrumentAnalyticsEngine(mockAE, 'my-dataset');
+
+      instrumented.writeDataPoint({
+        indexes: 'single-index' as any,
+      });
+
+      const spanOptions = mockTracer.startActiveSpan.mock.calls[0][1];
+      expect(spanOptions.attributes['analytics.indexes_count']).toBe(1);
+    });
+
+    it('should work with no datapoint argument', () => {
+      const instrumented = instrumentAnalyticsEngine(mockAE);
+
+      instrumented.writeDataPoint(undefined as any);
+
+      expect(mockTracer.startActiveSpan).toHaveBeenCalledTimes(1);
+
+      const spanOptions = mockTracer.startActiveSpan.mock.calls[0][1];
+      expect(spanOptions.attributes['analytics.system']).toBe('cloudflare-analytics-engine');
+      expect(spanOptions.attributes['analytics.operation']).toBe('writeDataPoint');
+      // No count attributes should be set when no datapoint
+      expect(spanOptions.attributes['analytics.indexes_count']).toBeUndefined();
+      expect(spanOptions.attributes['analytics.doubles_count']).toBeUndefined();
+      expect(spanOptions.attributes['analytics.blobs_count']).toBeUndefined();
+
+      expect(mockSpan.setStatus).toHaveBeenCalledWith({ code: SpanStatusCode.OK });
+      expect(mockSpan.end).toHaveBeenCalled();
+    });
+
+    it('should handle errors by recording exception and rethrowing', () => {
+      const error = new Error('writeDataPoint failed');
+      mockAE.writeDataPoint = vi.fn(() => {
+        throw error;
+      });
+
+      const instrumented = instrumentAnalyticsEngine(mockAE, 'my-dataset');
+
+      expect(() => instrumented.writeDataPoint({ indexes: ['idx1'] })).toThrow('writeDataPoint failed');
+
+      expect(mockSpan.recordException).toHaveBeenCalledWith(error);
+      expect(mockSpan.setStatus).toHaveBeenCalledWith({
+        code: SpanStatusCode.ERROR,
+        message: 'writeDataPoint failed',
+      });
+      expect(mockSpan.end).toHaveBeenCalled();
+    });
+
+    it('should use default dataset name when none provided', () => {
+      const instrumented = instrumentAnalyticsEngine(mockAE);
+
+      instrumented.writeDataPoint({ indexes: ['idx1'] });
+
+      const spanName = mockTracer.startActiveSpan.mock.calls[0][0];
+      expect(spanName).toBe('AnalyticsEngine analytics-engine: writeDataPoint');
+    });
+
+    it('should set OK status and end span on success', () => {
+      const instrumented = instrumentAnalyticsEngine(mockAE, 'my-dataset');
+
+      instrumented.writeDataPoint({ doubles: [42] });
+
+      expect(mockSpan.setStatus).toHaveBeenCalledWith({ code: SpanStatusCode.OK });
+      expect(mockSpan.end).toHaveBeenCalled();
+      expect(mockAE.writeDataPoint).toHaveBeenCalledWith({ doubles: [42] });
+    });
+  });
+
+  describe('Non-instrumented methods', () => {
+    it('should pass through non-instrumented methods unchanged', () => {
+      const instrumented = instrumentAnalyticsEngine(mockAE, 'my-dataset');
+
+      const result = instrumented.someOtherMethod();
+
+      expect(result).toBe('passthrough-value');
+      expect(mockAE.someOtherMethod).toHaveBeenCalled();
+      // No span should be created for non-instrumented methods
+      expect(mockTracer.startActiveSpan).not.toHaveBeenCalled();
+    });
+  });
+});

package/src/bindings/analytics-engine.ts

@@ -0,0 +1,78 @@
+/**
+ * Analytics Engine binding instrumentation
+ */
+
+import {
+  trace,
+  SpanKind,
+  SpanStatusCode,
+} from '@opentelemetry/api';
+import type { WorkerTracer } from 'autotel-edge';
+import { wrap } from './common';
+
+/**
+ * Instrument Analytics Engine binding
+ */
+export function instrumentAnalyticsEngine<T extends AnalyticsEngineDataset>(ae: T, datasetName?: string): T {
+  const name = datasetName || 'analytics-engine';
+
+  const handler: ProxyHandler<T> = {
+    get(target, prop) {
+      const value = Reflect.get(target, prop);
+
+      if (prop === 'writeDataPoint' && typeof value === 'function') {
+        return new Proxy(value, {
+          apply: (fnTarget, thisArg, args) => {
+            const [dataPoint] = args as [AnalyticsEngineDataPoint | undefined];
+            const tracer = trace.getTracer('autotel-edge') as WorkerTracer;
+
+            const attributes: Record<string, string | number> = {
+              'analytics.system': 'cloudflare-analytics-engine',
+              'analytics.operation': 'writeDataPoint',
+            };
+
+            if (dataPoint) {
+              if (dataPoint.indexes) {
+                attributes['analytics.indexes_count'] = Array.isArray(dataPoint.indexes) ? dataPoint.indexes.length : 1;
+              }
+              if (dataPoint.doubles) {
+                attributes['analytics.doubles_count'] = dataPoint.doubles.length;
+              }
+              if (dataPoint.blobs) {
+                attributes['analytics.blobs_count'] = dataPoint.blobs.length;
+              }
+            }
+
+            return tracer.startActiveSpan(
+              `AnalyticsEngine ${name}: writeDataPoint`,
+              {
+                kind: SpanKind.CLIENT,
+                attributes,
+              },
+              (span) => {
+                try {
+                  // writeDataPoint is synchronous/void
+                  Reflect.apply(fnTarget, thisArg, args);
+                  span.setStatus({ code: SpanStatusCode.OK });
+                } catch (error) {
+                  span.recordException(error as Error);
+                  span.setStatus({
+                    code: SpanStatusCode.ERROR,
+                    message: error instanceof Error ? error.message : String(error),
+                  });
+                  throw error;
+                } finally {
+                  span.end();
+                }
+              },
+            );
+          },
+        });
+      }
+
+      return value;
+    },
+  };
+
+  return wrap(ae, handler);
+}

package/src/bindings/bindings-detection.test.ts

@@ -0,0 +1,235 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { trace, SpanStatusCode, SpanKind } from '@opentelemetry/api';
+import { instrumentBindings } from './bindings';
+import { isWrapped, wrap } from './common';
+
+describe('instrumentBindings() detection logic', () => {
+  let mockTracer: any;
+  let mockSpan: any;
+  let getTracerSpy: any;
+
+  beforeEach(() => {
+    mockSpan = {
+      spanContext: () => ({
+        traceId: 'test-trace-id',
+        spanId: 'test-span-id',
+        traceFlags: 1,
+      }),
+      setAttribute: vi.fn(),
+      setAttributes: vi.fn(),
+      setStatus: vi.fn(),
+      recordException: vi.fn(),
+      end: vi.fn(),
+      isRecording: () => true,
+      updateName: vi.fn(),
+      addEvent: vi.fn(),
+    };
+
+    mockTracer = {
+      startActiveSpan: vi.fn((name, options, fn) => {
+        return fn(mockSpan);
+      }),
+    };
+
+    getTracerSpy = vi.spyOn(trace, 'getTracer').mockReturnValue(mockTracer as any);
+  });
+
+  afterEach(() => {
+    getTracerSpy.mockRestore();
+  });
+
+  it('should detect R2 (object with get, put, delete, list, head methods)', () => {
+    const mockR2 = {
+      get: vi.fn(),
+      put: vi.fn(),
+      delete: vi.fn(),
+      list: vi.fn(),
+      head: vi.fn(),
+    };
+
+    const result = instrumentBindings({ MY_R2: mockR2 });
+
+    expect(result.MY_R2).not.toBe(mockR2);
+    expect(isWrapped(result.MY_R2)).toBe(true);
+  });
+
+  it('should detect KV (object with get, put, delete, list but NOT head)', () => {
+    const mockKV = {
+      get: vi.fn(),
+      put: vi.fn(),
+      delete: vi.fn(),
+      list: vi.fn(),
+    };
+
+    const result = instrumentBindings({ MY_KV: mockKV });
+
+    expect(result.MY_KV).not.toBe(mockKV);
+    expect(isWrapped(result.MY_KV)).toBe(true);
+  });
+
+  it('should detect D1 (object with prepare, exec methods)', () => {
+    const mockD1 = {
+      prepare: vi.fn(),
+      exec: vi.fn(),
+    };
+
+    const result = instrumentBindings({ MY_DB: mockD1 });
+
+    expect(result.MY_DB).not.toBe(mockD1);
+    expect(isWrapped(result.MY_DB)).toBe(true);
+  });
+
+  it('should detect Vectorize (object with query, insert, upsert, describe methods)', () => {
+    const mockVectorize = {
+      query: vi.fn(),
+      insert: vi.fn(),
+      upsert: vi.fn(),
+      describe: vi.fn(),
+    };
+
+    const result = instrumentBindings({ MY_INDEX: mockVectorize });
+
+    expect(result.MY_INDEX).not.toBe(mockVectorize);
+    expect(isWrapped(result.MY_INDEX)).toBe(true);
+  });
+
+  it('should detect AI (object with run method AND gateway property)', () => {
+    const mockAI = {
+      run: vi.fn(),
+      gateway: {},
+    };
+
+    const result = instrumentBindings({ AI: mockAI });
+
+    expect(result.AI).not.toBe(mockAI);
+    expect(isWrapped(result.AI)).toBe(true);
+  });
+
+  it('should detect Hyperdrive (object with connect method AND connectionString, host properties)', () => {
+    const mockHyperdrive = {
+      connect: vi.fn(),
+      connectionString: 'postgresql://user:pass@host:5432/db',
+      host: 'db.example.com',
+      port: 5432,
+      user: 'user',
+      password: 'pass',
+      database: 'db',
+    };
+
+    const result = instrumentBindings({ HYPERDRIVE: mockHyperdrive });
+
+    expect(result.HYPERDRIVE).not.toBe(mockHyperdrive);
+    expect(isWrapped(result.HYPERDRIVE)).toBe(true);
+  });
+
+  it('should detect Queue Producer (object with send, sendBatch but NOT get)', () => {
+    const mockQueue = {
+      send: vi.fn(),
+      sendBatch: vi.fn(),
+    };
+
+    const result = instrumentBindings({ MY_QUEUE: mockQueue });
+
+    expect(result.MY_QUEUE).not.toBe(mockQueue);
+    expect(isWrapped(result.MY_QUEUE)).toBe(true);
+  });
+
+  it('should detect Analytics Engine (object with writeDataPoint method)', () => {
+    const mockAE = {
+      writeDataPoint: vi.fn(),
+    };
+
+    const result = instrumentBindings({ ANALYTICS: mockAE });
+
+    expect(result.ANALYTICS).not.toBe(mockAE);
+    expect(isWrapped(result.ANALYTICS)).toBe(true);
+  });
+
+  it('should detect Images (object with info, input methods)', () => {
+    const mockImages = {
+      info: vi.fn(),
+      input: vi.fn(),
+    };
+
+    const result = instrumentBindings({ IMAGES: mockImages });
+
+    expect(result.IMAGES).not.toBe(mockImages);
+    expect(isWrapped(result.IMAGES)).toBe(true);
+  });
+
+  it('should detect Service Binding (object with fetch method) - last', () => {
+    const mockService = {
+      fetch: vi.fn(),
+    };
+
+    const result = instrumentBindings({ MY_SERVICE: mockService });
+
+    expect(result.MY_SERVICE).not.toBe(mockService);
+    expect(isWrapped(result.MY_SERVICE)).toBe(true);
+  });
+
+  it('should detect R2 before KV (object with head gets R2, without head gets KV)', () => {
+    const withHead = {
+      get: vi.fn(),
+      put: vi.fn(),
+      delete: vi.fn(),
+      list: vi.fn(),
+      head: vi.fn(),
+    };
+    const withoutHead = {
+      get: vi.fn(),
+      put: vi.fn(),
+      delete: vi.fn(),
+      list: vi.fn(),
+    };
+
+    const result = instrumentBindings({
+      R2_BUCKET: withHead,
+      KV_STORE: withoutHead,
+    });
+
+    // Both should be wrapped but detected as different types
+    expect(isWrapped(result.R2_BUCKET)).toBe(true);
+    expect(isWrapped(result.KV_STORE)).toBe(true);
+    expect(result.R2_BUCKET).not.toBe(withHead);
+    expect(result.KV_STORE).not.toBe(withoutHead);
+  });
+
+  it('should skip already-wrapped bindings', () => {
+    const mockKV = {
+      get: vi.fn(),
+      put: vi.fn(),
+      delete: vi.fn(),
+      list: vi.fn(),
+    };
+
+    // Pre-wrap the binding using the wrap helper
+    const preWrapped = wrap(mockKV, {
+      get(target, prop) {
+        return Reflect.get(target, prop);
+      },
+    });
+
+    const result = instrumentBindings({ MY_KV: preWrapped });
+
+    // Should be the same already-wrapped object, not double-wrapped
+    expect(result.MY_KV).toBe(preWrapped);
+    expect(isWrapped(result.MY_KV)).toBe(true);
+  });
+
+  it('should pass through non-object values (strings, numbers)', () => {
+    const result = instrumentBindings({
+      API_KEY: 'my-secret-key',
+      TIMEOUT: 5000,
+      ENABLED: true,
+      EMPTY: null,
+      UNDEF: undefined,
+    });
+
+    expect(result.API_KEY).toBe('my-secret-key');
+    expect(result.TIMEOUT).toBe(5000);
+    expect(result.ENABLED).toBe(true);
+    expect(result.EMPTY).toBe(null);
+    expect(result.UNDEF).toBe(undefined);
+  });
+});

package/src/bindings/bindings.ts

@@ -23,7 +23,13 @@ import {
   SpanStatusCode,
 } from '@opentelemetry/api';
 import { WorkerTracer } from 'autotel-edge';
-import { wrap } from './common';
+import { wrap, isWrapped } from './common';
+import { instrumentAI } from './ai';
+import { instrumentVectorize } from './vectorize';
+import { instrumentHyperdrive } from './hyperdrive';
+import { instrumentQueueProducer } from './queue-producer';
+import { instrumentAnalyticsEngine } from './analytics-engine';
+import { instrumentImages } from './images';
 
 /**
  * Instrument KV namespace
@@ -554,68 +560,113 @@ export function instrumentServiceBinding<F extends Fetcher>(fetcher: F, serviceN
   return wrap(fetcher, fetcherHandler);
 }
 
+/**
+ * Detection helpers
+ */
+const hasMethod = (obj: any, m: string): boolean =>
+  typeof obj?.[m] === 'function';
+
+const hasExactMethods = (obj: any, methods: string[]): boolean =>
+  methods.every(m => hasMethod(obj, m));
+
 /**
  * Auto-instrument all Cloudflare bindings in the environment
+ *
+ * Detection order (most specific first):
+ * 1. R2 — get, put, delete, list, head
+ * 2. KV — get, put, delete, list (not head)
+ * 3. D1 — prepare, exec
+ * 4. Vectorize — query, insert, upsert, describe
+ * 5. AI — run + (gateway or models discriminator)
+ * 6. Hyperdrive — connect + connectionString + host
+ * 7. Queue Producer — send, sendBatch (not get)
+ * 8. Analytics Engine — writeDataPoint
+ * 9. Images — info, input
+ * 10. Service Binding — fetch (broadest, must be last)
+ *
+ * Not auto-detected (manual only):
+ * - Rate Limiter — limit() alone too generic
+ * - Browser Rendering — indistinguishable from Service Binding
  */
 export function instrumentBindings(env: Record<string, any>): Record<string, any> {
   const instrumented: Record<string, any> = {};
-  
+
   for (const [key, value] of Object.entries(env)) {
     if (!value || typeof value !== 'object') {
       instrumented[key] = value;
       continue;
     }
-    
-    // Check for KV namespace
-    if ('get' in value && 'put' in value && 'delete' in value && 'list' in value) {
-      // Likely KV namespace
-      try {
-        instrumented[key] = instrumentKV(value as KVNamespace, key);
-        continue;
-      } catch {
-        // Not KV, continue checking
-      }
+
+    // Skip already-instrumented bindings
+    if (isWrapped(value)) {
+      instrumented[key] = value;
+      continue;
     }
-    
-    // Check for R2 bucket
-    if ('get' in value && 'put' in value && 'delete' in value && 'list' in value && 'head' in value) {
-      // Likely R2 bucket
-      try {
-        instrumented[key] = instrumentR2(value as R2Bucket, key);
-        continue;
-      } catch {
-        // Not R2, continue checking
-      }
+
+    // 1. R2 — most specific (has head)
+    if (hasExactMethods(value, ['get', 'put', 'delete', 'list', 'head'])) {
+      instrumented[key] = instrumentR2(value as R2Bucket, key);
+      continue;
     }
-    
-    // Check for D1 database
-    if ('prepare' in value && 'exec' in value && typeof value.prepare === 'function') {
-      // Likely D1 database
-      try {
-        instrumented[key] = instrumentD1(value as D1Database, key);
-        continue;
-      } catch {
-        // Not D1, continue checking
-      }
+
+    // 2. KV — like R2 but without head
+    if (hasExactMethods(value, ['get', 'put', 'delete', 'list']) && !('head' in value)) {
+      instrumented[key] = instrumentKV(value as KVNamespace, key);
+      continue;
     }
-    
-    // Check for Service Binding (Fetcher)
-    if ('fetch' in value && typeof value.fetch === 'function') {
-      // Likely service binding
-      try {
-        instrumented[key] = instrumentServiceBinding(value as Fetcher, key);
-        continue;
-      } catch {
-        // Not a service binding, continue checking
-      }
+
+    // 3. D1
+    if (hasExactMethods(value, ['prepare', 'exec'])) {
+      instrumented[key] = instrumentD1(value as D1Database, key);
+      continue;
+    }
+
+    // 4. Vectorize
+    if (hasExactMethods(value, ['query', 'insert', 'upsert', 'describe'])) {
+      instrumented[key] = instrumentVectorize(value as VectorizeIndex, key);
+      continue;
     }
-    
-    // For other bindings (Events Engine, Workers AI, Vectorize, Hyperdrive),
-    // they don't have standard interfaces we can detect, so we pass them through
-    // Users can manually instrument them if needed
+
+    // 5. AI — has run() + discriminator properties
+    if (hasMethod(value, 'run') && ('gateway' in value || 'models' in value)) {
+      instrumented[key] = instrumentAI(value as Ai, key);
+      continue;
+    }
+
+    // 6. Hyperdrive — connect + connection properties
+    if (hasMethod(value, 'connect') && 'connectionString' in value && 'host' in value) {
+      instrumented[key] = instrumentHyperdrive(value as Hyperdrive, key);
+      continue;
+    }
+
+    // 7. Queue Producer — send + sendBatch (not get, to avoid KV collision)
+    if (hasExactMethods(value, ['send', 'sendBatch']) && !('get' in value)) {
+      instrumented[key] = instrumentQueueProducer(value as Queue, key);
+      continue;
+    }
+
+    // 8. Analytics Engine
+    if (hasMethod(value, 'writeDataPoint')) {
+      instrumented[key] = instrumentAnalyticsEngine(value as AnalyticsEngineDataset, key);
+      continue;
+    }
+
+    // 9. Images
+    if (hasExactMethods(value, ['info', 'input'])) {
+      instrumented[key] = instrumentImages(value as any, key);
+      continue;
+    }
+
+    // 10. Service Binding (broadest — must be last)
+    if (hasMethod(value, 'fetch')) {
+      instrumented[key] = instrumentServiceBinding(value as Fetcher, key);
+      continue;
+    }
+
+    // Unknown binding type — pass through
     instrumented[key] = value;
   }
-  
+
   return instrumented;
 }