autotel-cloudflare 2.12.0 → 2.14.0

package/src/bindings/images.ts

@@ -0,0 +1,182 @@
+/**
+ * Images binding instrumentation
+ *
+ * The Images binding uses a fluent chain: input() -> transform() -> draw() -> output()
+ * We only create a span at the terminal output() call to avoid intermediate noise.
+ * info() is a standalone operation and gets its own span.
+ */
+
+import {
+  trace,
+  SpanKind,
+  SpanStatusCode,
+} from '@opentelemetry/api';
+import type { WorkerTracer } from 'autotel-edge';
+import { wrap, setAttr } from './common';
+
+const pipelineMetaSymbol = Symbol('images-pipeline-meta');
+
+interface PipelineMeta {
+  operationCount: number;
+}
+
+interface ImagesLike {
+  info(blob: ReadableStream | ArrayBuffer | Blob): Promise<{ width: number; height: number; format: string }>;
+  input(blob: ReadableStream | ArrayBuffer | Blob): ImageTransformerLike;
+}
+
+interface ImageTransformerLike {
+  transform(options: unknown): ImageTransformerLike;
+  draw(image: unknown, options?: unknown): ImageTransformerLike;
+  output(options?: unknown): Promise<ImageOutputLike>;
+}
+
+interface ImageOutputLike {
+  response(): Response;
+  blob(): Promise<Blob>;
+  arrayBuffer(): Promise<ArrayBuffer>;
+}
+
+function proxyTransformer(transformer: ImageTransformerLike, meta: PipelineMeta, bindingName: string): ImageTransformerLike {
+  const handler: ProxyHandler<ImageTransformerLike> = {
+    get(target, prop) {
+      const value = Reflect.get(target, prop);
+
+      if ((prop === 'transform' || prop === 'draw') && typeof value === 'function') {
+        return new Proxy(value, {
+          apply: (fnTarget, _thisArg, args) => {
+            meta.operationCount++;
+            const result = Reflect.apply(fnTarget, target, args);
+            // If the result is the transformer itself (fluent chain), return our proxy
+            if (result === target || (result && typeof result === 'object' && 'output' in result)) {
+              return proxyTransformer(result as ImageTransformerLike, meta, bindingName);
+            }
+            return result;
+          },
+        });
+      }
+
+      if (prop === 'output' && typeof value === 'function') {
+        return new Proxy(value, {
+          apply: (fnTarget, _thisArg, args) => {
+            const tracer = trace.getTracer('autotel-edge') as WorkerTracer;
+            const [formatOrOptions] = args;
+
+            const attributes: Record<string, string | number> = {
+              'images.system': 'cloudflare-images',
+              'images.pipeline.operation_count': meta.operationCount,
+            };
+
+            // Capture output format
+            if (typeof formatOrOptions === 'string') {
+              attributes['images.output.format'] = formatOrOptions;
+            } else if (formatOrOptions && typeof formatOrOptions === 'object') {
+              const fmt = (formatOrOptions as any).format;
+              if (fmt) attributes['images.output.format'] = fmt;
+            }
+
+            return tracer.startActiveSpan(
+              `Images ${bindingName}: output`,
+              {
+                kind: SpanKind.CLIENT,
+                attributes,
+              },
+              async (span) => {
+                try {
+                  const result = await Reflect.apply(fnTarget, target, args);
+                  span.setStatus({ code: SpanStatusCode.OK });
+                  return result;
+                } 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;
+    },
+  };
+
+  const proxy = new Proxy(transformer, handler);
+  Object.defineProperty(proxy, pipelineMetaSymbol, {
+    value: meta,
+    writable: false,
+    enumerable: false,
+    configurable: false,
+  });
+  return proxy;
+}
+
+/**
+ * Instrument Images binding
+ */
+export function instrumentImages<T extends ImagesLike>(images: T, bindingName?: string): T {
+  const name = bindingName || 'images';
+
+  const handler: ProxyHandler<T> = {
+    get(target, prop) {
+      const value = Reflect.get(target, prop);
+
+      if (prop === 'info' && typeof value === 'function') {
+        return new Proxy(value, {
+          apply: (fnTarget, thisArg, args) => {
+            const tracer = trace.getTracer('autotel-edge') as WorkerTracer;
+
+            return tracer.startActiveSpan(
+              `Images ${name}: info`,
+              {
+                kind: SpanKind.CLIENT,
+                attributes: {
+                  'images.system': 'cloudflare-images',
+                  'images.operation': 'info',
+                },
+              },
+              async (span) => {
+                try {
+                  const result = await Reflect.apply(fnTarget, thisArg, args);
+                  setAttr(span, 'images.width', result?.width);
+                  setAttr(span, 'images.height', result?.height);
+                  setAttr(span, 'images.format', result?.format);
+                  span.setStatus({ code: SpanStatusCode.OK });
+                  return result;
+                } 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();
+                }
+              },
+            );
+          },
+        });
+      }
+
+      if (prop === 'input' && typeof value === 'function') {
+        return new Proxy(value, {
+          apply: (fnTarget, thisArg, args) => {
+            const transformer = Reflect.apply(fnTarget, thisArg, args) as ImageTransformerLike;
+            const meta: PipelineMeta = { operationCount: 0 };
+            return proxyTransformer(transformer, meta, name);
+          },
+        });
+      }
+
+      return value;
+    },
+  };
+
+  return wrap(images, handler);
+}

package/src/bindings/index.ts

@@ -10,3 +10,11 @@ export {
   instrumentServiceBinding,
   instrumentBindings,
 } from './bindings';
+export { instrumentAI } from './ai';
+export { instrumentVectorize } from './vectorize';
+export { instrumentHyperdrive } from './hyperdrive';
+export { instrumentQueueProducer } from './queue-producer';
+export { instrumentAnalyticsEngine } from './analytics-engine';
+export { instrumentImages } from './images';
+export { instrumentRateLimiter } from './rate-limiter';
+export { instrumentBrowserRendering } from './browser-rendering';

package/src/bindings/queue-producer.test.ts

@@ -0,0 +1,192 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { instrumentQueueProducer } from './queue-producer';
+import { trace, SpanStatusCode, SpanKind } from '@opentelemetry/api';
+
+describe('Queue Producer Binding Instrumentation', () => {
+  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();
+  });
+
+  function createMockQueue(overrides: Partial<Queue> = {}): Queue {
+    return {
+      send: vi.fn(async () => ({ messageId: 'msg-123', outcome: 'ok' })),
+      sendBatch: vi.fn(async () => ({})),
+      ...overrides,
+    } as unknown as Queue;
+  }
+
+  describe('send()', () => {
+    it('should create span with PRODUCER kind and correct attributes', async () => {
+      const mockQueue = createMockQueue();
+      const instrumented = instrumentQueueProducer(mockQueue, 'my-queue');
+
+      await instrumented.send({ data: 'test-payload' });
+
+      expect(mockTracer.startActiveSpan).toHaveBeenCalledTimes(1);
+
+      const [spanName, options] = mockTracer.startActiveSpan.mock.calls[0];
+      expect(spanName).toBe('Queue my-queue: send');
+      expect(options.kind).toBe(SpanKind.PRODUCER);
+      expect(options.attributes['messaging.system']).toBe('cloudflare-queues');
+      expect(options.attributes['messaging.operation.type']).toBe('publish');
+      expect(options.attributes['messaging.operation']).toBe('send');
+      expect(options.attributes['messaging.destination.name']).toBe('my-queue');
+    });
+
+    it('should record messageId from result when available', async () => {
+      const mockQueue = createMockQueue({
+        send: vi.fn(async () => ({ messageId: 'msg-456', outcome: 'ok' })) as any,
+      });
+      const instrumented = instrumentQueueProducer(mockQueue, 'my-queue');
+
+      await instrumented.send({ data: 'test-payload' });
+
+      expect(mockSpan.setAttribute).toHaveBeenCalledWith('messaging.message.id', 'msg-456');
+      expect(mockSpan.setStatus).toHaveBeenCalledWith({ code: SpanStatusCode.OK });
+      expect(mockSpan.end).toHaveBeenCalled();
+    });
+
+    it('should not set messageId attribute when result has no messageId', async () => {
+      const mockQueue = createMockQueue({
+        send: vi.fn(async () => ({})) as any,
+      });
+      const instrumented = instrumentQueueProducer(mockQueue, 'my-queue');
+
+      await instrumented.send({ data: 'test-payload' });
+
+      // setAttr uses the common helper which skips undefined/null values
+      const messageIdCalls = mockSpan.setAttribute.mock.calls.filter(
+        (call: any) => call[0] === 'messaging.message.id'
+      );
+      expect(messageIdCalls.length).toBe(0);
+    });
+
+    it('should handle errors in send()', async () => {
+      const sendError = new Error('Queue full');
+      const mockQueue = createMockQueue({
+        send: vi.fn(async () => {
+          throw sendError;
+        }) as any,
+      });
+      const instrumented = instrumentQueueProducer(mockQueue, 'my-queue');
+
+      await expect(instrumented.send({ data: 'test-payload' })).rejects.toThrow('Queue full');
+
+      expect(mockSpan.recordException).toHaveBeenCalledWith(sendError);
+      expect(mockSpan.setStatus).toHaveBeenCalledWith({
+        code: SpanStatusCode.ERROR,
+        message: 'Queue full',
+      });
+      expect(mockSpan.end).toHaveBeenCalled();
+    });
+
+    it('should use default queue name when none provided', async () => {
+      const mockQueue = createMockQueue();
+      const instrumented = instrumentQueueProducer(mockQueue);
+
+      await instrumented.send({ data: 'test-payload' });
+
+      const [spanName, options] = mockTracer.startActiveSpan.mock.calls[0];
+      expect(spanName).toBe('Queue queue: send');
+      expect(options.attributes['messaging.destination.name']).toBe('queue');
+    });
+  });
+
+  describe('sendBatch()', () => {
+    it('should create span with batch_message_count', async () => {
+      const mockQueue = createMockQueue();
+      const instrumented = instrumentQueueProducer(mockQueue, 'my-queue');
+
+      const messages = [
+        { body: { data: 'msg-1' } },
+        { body: { data: 'msg-2' } },
+        { body: { data: 'msg-3' } },
+      ];
+
+      await instrumented.sendBatch(messages);
+
+      expect(mockTracer.startActiveSpan).toHaveBeenCalledTimes(1);
+
+      const [spanName, options] = mockTracer.startActiveSpan.mock.calls[0];
+      expect(spanName).toBe('Queue my-queue: sendBatch');
+      expect(options.kind).toBe(SpanKind.PRODUCER);
+      expect(options.attributes['messaging.system']).toBe('cloudflare-queues');
+      expect(options.attributes['messaging.operation.type']).toBe('publish');
+      expect(options.attributes['messaging.operation']).toBe('sendBatch');
+      expect(options.attributes['messaging.destination.name']).toBe('my-queue');
+      expect(options.attributes['messaging.batch.message_count']).toBe(3);
+    });
+
+    it('should set OK status and end span on success', async () => {
+      const mockQueue = createMockQueue();
+      const instrumented = instrumentQueueProducer(mockQueue, 'my-queue');
+
+      await instrumented.sendBatch([{ body: { data: 'msg-1' } }]);
+
+      expect(mockSpan.setStatus).toHaveBeenCalledWith({ code: SpanStatusCode.OK });
+      expect(mockSpan.end).toHaveBeenCalled();
+    });
+
+    it('should handle errors in sendBatch()', async () => {
+      const batchError = new Error('Batch limit exceeded');
+      const mockQueue = createMockQueue({
+        sendBatch: vi.fn(async () => {
+          throw batchError;
+        }) as any,
+      });
+      const instrumented = instrumentQueueProducer(mockQueue, 'my-queue');
+
+      const messages = [{ body: { data: 'msg-1' } }, { body: { data: 'msg-2' } }];
+
+      await expect(instrumented.sendBatch(messages)).rejects.toThrow('Batch limit exceeded');
+
+      expect(mockSpan.recordException).toHaveBeenCalledWith(batchError);
+      expect(mockSpan.setStatus).toHaveBeenCalledWith({
+        code: SpanStatusCode.ERROR,
+        message: 'Batch limit exceeded',
+      });
+      expect(mockSpan.end).toHaveBeenCalled();
+    });
+  });
+
+  describe('non-instrumented methods', () => {
+    it('should pass through non-instrumented properties', () => {
+      const mockQueue = createMockQueue();
+      (mockQueue as any).customProp = 'test-value';
+
+      const instrumented = instrumentQueueProducer(mockQueue, 'my-queue');
+
+      expect((instrumented as any).customProp).toBe('test-value');
+    });
+  });
+});

package/src/bindings/queue-producer.ts

@@ -0,0 +1,105 @@
+/**
+ * Queue producer binding instrumentation
+ */
+
+import {
+  trace,
+  SpanKind,
+  SpanStatusCode,
+} from '@opentelemetry/api';
+import type { WorkerTracer } from 'autotel-edge';
+import { wrap, setAttr } from './common';
+
+/**
+ * Instrument Queue producer binding
+ */
+export function instrumentQueueProducer<T extends Queue>(queue: T, queueName?: string): T {
+  const name = queueName || 'queue';
+
+  const handler: ProxyHandler<T> = {
+    get(target, prop) {
+      const value = Reflect.get(target, prop);
+
+      if (prop === 'send' && typeof value === 'function') {
+        return new Proxy(value, {
+          apply: (fnTarget, thisArg, args) => {
+            const tracer = trace.getTracer('autotel-edge') as WorkerTracer;
+
+            return tracer.startActiveSpan(
+              `Queue ${name}: send`,
+              {
+                kind: SpanKind.PRODUCER,
+                attributes: {
+                  'messaging.system': 'cloudflare-queues',
+                  'messaging.operation.type': 'publish',
+                  'messaging.operation': 'send',
+                  'messaging.destination.name': name,
+                },
+              },
+              async (span) => {
+                try {
+                  const result = await Reflect.apply(fnTarget, thisArg, args);
+                  setAttr(span, 'messaging.message.id', (result as any)?.messageId);
+                  span.setStatus({ code: SpanStatusCode.OK });
+                  return result;
+                } 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();
+                }
+              },
+            );
+          },
+        });
+      }
+
+      if (prop === 'sendBatch' && typeof value === 'function') {
+        return new Proxy(value, {
+          apply: (fnTarget, thisArg, args) => {
+            const [messages] = args as [{ body: unknown }[]];
+            const tracer = trace.getTracer('autotel-edge') as WorkerTracer;
+
+            return tracer.startActiveSpan(
+              `Queue ${name}: sendBatch`,
+              {
+                kind: SpanKind.PRODUCER,
+                attributes: {
+                  'messaging.system': 'cloudflare-queues',
+                  'messaging.operation.type': 'publish',
+                  'messaging.operation': 'sendBatch',
+                  'messaging.destination.name': name,
+                  'messaging.batch.message_count': Array.isArray(messages) ? messages.length : 0,
+                },
+              },
+              async (span) => {
+                try {
+                  const result = await Reflect.apply(fnTarget, thisArg, args);
+                  span.setStatus({ code: SpanStatusCode.OK });
+                  return result;
+                } 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(queue, handler);
+}

package/src/bindings/rate-limiter.test.ts

@@ -0,0 +1,124 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { instrumentRateLimiter } from './rate-limiter';
+import { trace, SpanStatusCode, SpanKind } from '@opentelemetry/api';
+
+describe('Rate Limiter Instrumentation', () => {
+  let mockTracer: any;
+  let mockSpan: any;
+  let getTracerSpy: any;
+  let mockLimiter: 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);
+
+    mockLimiter = {
+      limit: vi.fn(async () => ({ success: true })),
+      someOtherMethod: vi.fn(() => 'passthrough-value'),
+    };
+  });
+
+  afterEach(() => {
+    getTracerSpy.mockRestore();
+  });
+
+  describe('limit()', () => {
+    it('should create span with correct attributes', async () => {
+      const instrumented = instrumentRateLimiter(mockLimiter, 'my-limiter');
+
+      await instrumented.limit({ key: 'user-123' });
+
+      expect(mockTracer.startActiveSpan).toHaveBeenCalledTimes(1);
+
+      const [spanName, spanOptions] = mockTracer.startActiveSpan.mock.calls[0];
+      expect(spanName).toBe('RateLimiter my-limiter: limit');
+      expect(spanOptions.kind).toBe(SpanKind.CLIENT);
+      expect(spanOptions.attributes['rate_limiter.system']).toBe('cloudflare-rate-limiter');
+      expect(spanOptions.attributes['rate_limiter.key']).toBe('user-123');
+    });
+
+    it('should record success from result', async () => {
+      const instrumented = instrumentRateLimiter(mockLimiter, 'my-limiter');
+
+      await instrumented.limit({ key: 'user-123' });
+
+      expect(mockSpan.setAttribute).toHaveBeenCalledWith('rate_limiter.success', true);
+      expect(mockSpan.setStatus).toHaveBeenCalledWith({ code: SpanStatusCode.OK });
+      expect(mockSpan.end).toHaveBeenCalled();
+    });
+
+    it('should record success=false when rate limited', async () => {
+      mockLimiter.limit = vi.fn(async () => ({ success: false }));
+
+      const instrumented = instrumentRateLimiter(mockLimiter, 'my-limiter');
+
+      const result = await instrumented.limit({ key: 'user-456' });
+
+      expect(result.success).toBe(false);
+      expect(mockSpan.setAttribute).toHaveBeenCalledWith('rate_limiter.success', false);
+      expect(mockSpan.setStatus).toHaveBeenCalledWith({ code: SpanStatusCode.OK });
+      expect(mockSpan.end).toHaveBeenCalled();
+    });
+
+    it('should handle errors by recording exception and rethrowing', async () => {
+      const error = new Error('Rate limiter unavailable');
+      mockLimiter.limit = vi.fn(async () => {
+        throw error;
+      });
+
+      const instrumented = instrumentRateLimiter(mockLimiter, 'my-limiter');
+
+      await expect(instrumented.limit({ key: 'user-789' })).rejects.toThrow('Rate limiter unavailable');
+
+      expect(mockSpan.recordException).toHaveBeenCalledWith(error);
+      expect(mockSpan.setStatus).toHaveBeenCalledWith({
+        code: SpanStatusCode.ERROR,
+        message: 'Rate limiter unavailable',
+      });
+      expect(mockSpan.end).toHaveBeenCalled();
+    });
+
+    it('should use default binding name when none provided', async () => {
+      const instrumented = instrumentRateLimiter(mockLimiter);
+
+      await instrumented.limit({ key: 'user-123' });
+
+      const spanName = mockTracer.startActiveSpan.mock.calls[0][0];
+      expect(spanName).toBe('RateLimiter rate-limiter: limit');
+    });
+  });
+
+  describe('Non-instrumented methods', () => {
+    it('should pass through non-instrumented methods unchanged', () => {
+      const instrumented = instrumentRateLimiter(mockLimiter, 'my-limiter');
+
+      const result = instrumented.someOtherMethod();
+
+      expect(result).toBe('passthrough-value');
+      expect(mockLimiter.someOtherMethod).toHaveBeenCalled();
+      // No span should be created for non-instrumented methods
+      expect(mockTracer.startActiveSpan).not.toHaveBeenCalled();
+    });
+  });
+});

package/src/bindings/rate-limiter.ts

@@ -0,0 +1,69 @@
+/**
+ * Rate Limiter binding instrumentation
+ */
+
+import {
+  trace,
+  SpanKind,
+  SpanStatusCode,
+} from '@opentelemetry/api';
+import type { WorkerTracer } from 'autotel-edge';
+import { wrap, setAttr } from './common';
+
+interface RateLimiterLike {
+  limit(options: { key: string }): Promise<{ success: boolean }>;
+}
+
+/**
+ * Instrument Rate Limiter binding (manual only — not auto-detected)
+ */
+export function instrumentRateLimiter<T extends RateLimiterLike>(limiter: T, bindingName?: string): T {
+  const name = bindingName || 'rate-limiter';
+
+  const handler: ProxyHandler<T> = {
+    get(target, prop) {
+      const value = Reflect.get(target, prop);
+
+      if (prop === 'limit' && typeof value === 'function') {
+        return new Proxy(value, {
+          apply: (fnTarget, thisArg, args) => {
+            const [options] = args as [{ key: string }];
+            const tracer = trace.getTracer('autotel-edge') as WorkerTracer;
+
+            return tracer.startActiveSpan(
+              `RateLimiter ${name}: limit`,
+              {
+                kind: SpanKind.CLIENT,
+                attributes: {
+                  'rate_limiter.system': 'cloudflare-rate-limiter',
+                  'rate_limiter.key': options?.key,
+                },
+              },
+              async (span) => {
+                try {
+                  const result = await Reflect.apply(fnTarget, thisArg, args);
+                  setAttr(span, 'rate_limiter.success', result?.success);
+                  span.setStatus({ code: SpanStatusCode.OK });
+                  return result;
+                } 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(limiter, handler);
+}