autotel-cloudflare 2.12.0 → 2.13.0

package/src/wrappers/cf-attributes.test.ts

@@ -0,0 +1,275 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { instrument } from './instrument';
+import { trace, SpanStatusCode, SpanKind } from '@opentelemetry/api';
+
+describe('CF Attributes extraction via instrument()', () => {
+  let mockTracer: any;
+  let mockSpan: any;
+  let getTracerSpy: any;
+  let capturedSpanOptions: 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(),
+    };
+
+    capturedSpanOptions = null;
+
+    mockTracer = {
+      startActiveSpan: vi.fn((...args: any[]) => {
+        // startActiveSpan can be called with (name, options, context, fn) or (name, options, fn)
+        // The fetch instrumentation calls it with 4 args: (name, options, parentContext, fn)
+        const fn = args.at(-1);
+        if (args.length >= 2) {
+          capturedSpanOptions = args[1];
+        }
+        return fn(mockSpan);
+      }),
+      setHeadSampler: vi.fn(),
+      forceFlush: vi.fn(async () => {}),
+    };
+
+    getTracerSpy = vi.spyOn(trace, 'getTracer').mockReturnValue(mockTracer as any);
+  });
+
+  afterEach(() => {
+    getTracerSpy.mockRestore();
+  });
+
+  function createMockCtx() {
+    return {
+      waitUntil: vi.fn(),
+      passThroughOnException: vi.fn(),
+    } as any;
+  }
+
+  it('should extract CF attributes when request has .cf object', async () => {
+    const handler = {
+      async fetch(request: Request) {
+        return new Response('OK', { status: 200 });
+      },
+    };
+
+    const instrumented = instrument(handler, {
+      service: { name: 'test-worker' },
+    });
+
+    const request = new Request('http://example.com/test');
+    // Attach .cf properties to the request (Cloudflare Workers runtime does this)
+    Object.defineProperty(request, 'cf', {
+      value: {
+        colo: 'SJC',
+        country: 'US',
+        city: 'San Jose',
+        region: 'California',
+        continent: 'NA',
+        timezone: 'America/Los_Angeles',
+        latitude: '37.3382',
+        longitude: '-121.8863',
+        asn: 13_335,
+        asOrganization: 'Cloudflare Inc',
+        httpProtocol: 'HTTP/2',
+        tlsVersion: 'TLSv1.3',
+        clientTcpRtt: 5,
+      },
+      writable: false,
+      enumerable: true,
+    });
+
+    const env = {} as any;
+    const ctx = createMockCtx();
+
+    await instrumented.fetch!(request, env, ctx);
+
+    expect(capturedSpanOptions).toBeDefined();
+    const attrs = capturedSpanOptions.attributes;
+
+    expect(attrs['cloudflare.colo']).toBe('SJC');
+    expect(attrs['cloudflare.country']).toBe('US');
+    expect(attrs['cloudflare.city']).toBe('San Jose');
+    expect(attrs['cloudflare.region']).toBe('California');
+    expect(attrs['cloudflare.continent']).toBe('NA');
+    expect(attrs['cloudflare.timezone']).toBe('America/Los_Angeles');
+    expect(attrs['cloudflare.latitude']).toBe('37.3382');
+    expect(attrs['cloudflare.longitude']).toBe('-121.8863');
+    expect(attrs['cloudflare.asn']).toBe(13_335);
+    expect(attrs['cloudflare.as_organization']).toBe('Cloudflare Inc');
+    expect(attrs['cloudflare.http_protocol']).toBe('HTTP/2');
+    expect(attrs['cloudflare.tls_version']).toBe('TLSv1.3');
+    expect(attrs['cloudflare.client_tcp_rtt']).toBe(5);
+  });
+
+  it('should extract CF ray_id from cf-ray header', async () => {
+    const handler = {
+      async fetch(request: Request) {
+        return new Response('OK', { status: 200 });
+      },
+    };
+
+    const instrumented = instrument(handler, {
+      service: { name: 'test-worker' },
+    });
+
+    const request = new Request('http://example.com/test', {
+      headers: {
+        'cf-ray': '8a1b2c3d4e5f6-SJC',
+      },
+    });
+    Object.defineProperty(request, 'cf', {
+      value: { colo: 'SJC' },
+      writable: false,
+      enumerable: true,
+    });
+
+    const env = {} as any;
+    const ctx = createMockCtx();
+
+    await instrumented.fetch!(request, env, ctx);
+
+    expect(capturedSpanOptions).toBeDefined();
+    const attrs = capturedSpanOptions.attributes;
+    expect(attrs['cloudflare.ray_id']).toBe('8a1b2c3d4e5f6-SJC');
+    expect(attrs['cloudflare.colo']).toBe('SJC');
+  });
+
+  it('should not include CF attributes when request.cf is undefined', async () => {
+    const handler = {
+      async fetch(request: Request) {
+        return new Response('OK', { status: 200 });
+      },
+    };
+
+    const instrumented = instrument(handler, {
+      service: { name: 'test-worker' },
+    });
+
+    // Standard request without .cf (local dev / Miniflare scenario)
+    const request = new Request('http://example.com/test');
+    const env = {} as any;
+    const ctx = createMockCtx();
+
+    await instrumented.fetch!(request, env, ctx);
+
+    expect(capturedSpanOptions).toBeDefined();
+    const attrs = capturedSpanOptions.attributes;
+
+    // Standard HTTP attributes should still be present
+    expect(attrs['http.request.method']).toBe('GET');
+    expect(attrs['url.full']).toBe('http://example.com/test');
+
+    // No cloudflare.* attributes should be present
+    const cfKeys = Object.keys(attrs).filter(k => k.startsWith('cloudflare.'));
+    expect(cfKeys).toHaveLength(0);
+  });
+
+  it('should correctly map all CF fields to cloudflare.* attribute names', async () => {
+    const handler = {
+      async fetch(request: Request) {
+        return new Response('OK', { status: 200 });
+      },
+    };
+
+    const instrumented = instrument(handler, {
+      service: { name: 'test-worker' },
+    });
+
+    const request = new Request('http://example.com/test', {
+      headers: { 'cf-ray': 'abc123-LAX' },
+    });
+    Object.defineProperty(request, 'cf', {
+      value: {
+        colo: 'LAX',
+        country: 'US',
+        city: 'Los Angeles',
+        region: 'California',
+        continent: 'NA',
+        timezone: 'America/Los_Angeles',
+        latitude: '34.0522',
+        longitude: '-118.2437',
+        asn: 13_335,
+        asOrganization: 'Cloudflare Inc',
+        httpProtocol: 'HTTP/3',
+        tlsVersion: 'TLSv1.3',
+        clientTcpRtt: 10,
+      },
+      writable: false,
+      enumerable: true,
+    });
+
+    const env = {} as any;
+    const ctx = createMockCtx();
+
+    await instrumented.fetch!(request, env, ctx);
+
+    const attrs = capturedSpanOptions.attributes;
+
+    // Verify the exact mapping from CF property names to attribute names
+    const expectedMappings: Record<string, [string, any]> = {
+      'cloudflare.colo': ['colo', 'LAX'],
+      'cloudflare.ray_id': ['cf-ray header', 'abc123-LAX'],
+      'cloudflare.country': ['country', 'US'],
+      'cloudflare.city': ['city', 'Los Angeles'],
+      'cloudflare.region': ['region', 'California'],
+      'cloudflare.continent': ['continent', 'NA'],
+      'cloudflare.timezone': ['timezone', 'America/Los_Angeles'],
+      'cloudflare.latitude': ['latitude', '34.0522'],
+      'cloudflare.longitude': ['longitude', '-118.2437'],
+      'cloudflare.asn': ['asn', 13_335],
+      'cloudflare.as_organization': ['asOrganization', 'Cloudflare Inc'],
+      'cloudflare.http_protocol': ['httpProtocol', 'HTTP/3'],
+      'cloudflare.tls_version': ['tlsVersion', 'TLSv1.3'],
+      'cloudflare.client_tcp_rtt': ['clientTcpRtt', 10],
+    };
+
+    for (const [attrKey, [, expectedValue]] of Object.entries(expectedMappings)) {
+      expect(attrs[attrKey]).toBe(expectedValue);
+    }
+  });
+
+  it('preserves valid falsy numeric CF attributes (0 values)', async () => {
+    const handler = {
+      async fetch(_request: Request) {
+        return new Response('OK', { status: 200 });
+      },
+    };
+
+    const instrumented = instrument(handler, {
+      service: { name: 'test-worker' },
+    });
+
+    const request = new Request('http://example.com/test');
+    Object.defineProperty(request, 'cf', {
+      value: {
+        latitude: 0,
+        longitude: 0,
+        asn: 0,
+        clientTcpRtt: 0,
+      },
+      writable: false,
+      enumerable: true,
+    });
+
+    const env = {} as any;
+    const ctx = createMockCtx();
+
+    await instrumented.fetch!(request, env, ctx);
+
+    const attrs = capturedSpanOptions.attributes;
+    expect(attrs['cloudflare.latitude']).toBe(0);
+    expect(attrs['cloudflare.longitude']).toBe(0);
+    expect(attrs['cloudflare.asn']).toBe(0);
+    expect(attrs['cloudflare.client_tcp_rtt']).toBe(0);
+  });
+});

package/src/wrappers/instrument.ts

@@ -75,6 +75,39 @@ type EmailHandler = (
 /**
  * Create fetch handler instrumentation with config support for postProcess
  */
+/**
+ * Extract Cloudflare-specific attributes from a request
+ */
+function extractCfAttributes(request: Request): Record<string, string | number | boolean> {
+  const cf = (request as any).cf;
+  if (!cf) return {};
+
+  const attrs: Record<string, string | number | boolean> = {};
+  const set = (key: string, value: unknown) => {
+    if (value !== undefined && value !== null) {
+      attrs[key] = value as string | number | boolean;
+    }
+  };
+
+  set('cloudflare.colo', cf.colo);
+  const ray = request.headers.get('cf-ray');
+  if (ray) attrs['cloudflare.ray_id'] = ray;
+  set('cloudflare.country', cf.country);
+  set('cloudflare.city', cf.city);
+  set('cloudflare.region', cf.region);
+  set('cloudflare.continent', cf.continent);
+  set('cloudflare.timezone', cf.timezone);
+  set('cloudflare.latitude', cf.latitude);
+  set('cloudflare.longitude', cf.longitude);
+  set('cloudflare.asn', cf.asn);
+  set('cloudflare.as_organization', cf.asOrganization);
+  set('cloudflare.http_protocol', cf.httpProtocol);
+  set('cloudflare.tls_version', cf.tlsVersion);
+  set('cloudflare.client_tcp_rtt', cf.clientTcpRtt);
+
+  return attrs;
+}
+
 function createFetchInstrumentation(
   config: ResolvedEdgeConfig,
 ): HandlerInstrumentation<Request, Response> {
@@ -82,6 +115,10 @@ function createFetchInstrumentation(
     getInitialSpanInfo: (request: Request): InitialSpanInfo => {
       const url = new URL(request.url);
 
+      const cfAttrs = (config as any).extractCfAttributes === false
+        ? {}
+        : extractCfAttributes(request);
+
       return {
         name: `${request.method} ${url.pathname}`,
         options: {
@@ -89,6 +126,7 @@ function createFetchInstrumentation(
           attributes: {
             'http.request.method': request.method,
             'url.full': request.url,
+            ...cfAttrs,
           },
         },
         context: propagation.extract(api_context.active(), request.headers),

package/dist/chunk-5NL62W4L.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/bindings/common.ts"],"names":[],"mappings":";AAOO,IAAM,iBAAN,MAAqB;AAAA,EAClB,WAA+B,EAAC;AAAA,EAExC,MAAM,OAAA,EAAiC;AACrC,IAAA,IAAA,CAAK,QAAA,CAAS,KAAK,OAAO,CAAA;AAAA,EAC5B;AAAA,EAEA,MAAM,IAAA,GAAsB;AAC1B,IAAA,MAAM,OAAA,CAAQ,UAAA,CAAW,IAAA,CAAK,QAAQ,CAAA;AAAA,EACxC;AACF,CAAA;AAKO,SAAS,sBAAsB,GAAA,EAGpC;AACA,EAAA,MAAM,OAAA,GAAU,IAAI,cAAA,EAAe;AAEnC,EAAA,MAAM,OAAA,GAAU,IAAI,KAAA,CAAM,GAAA,EAAK;AAAA,IAC7B,GAAA,CAAI,QAAQ,IAAA,EAAM;AAChB,MAAA,IAAI,SAAS,WAAA,EAAa;AACxB,QAAA,OAAO,CAAC,OAAA,KAA8B;AACpC,UAAA,OAAA,CAAQ,MAAM,OAAO,CAAA;AACrB,UAAA,OAAO,MAAA,CAAO,UAAU,OAAO,CAAA;AAAA,QACjC,CAAA;AAAA,MACF;AACA,MAAA,OAAO,OAAA,CAAQ,GAAA,CAAI,MAAA,EAAQ,IAAI,CAAA;AAAA,IACjC;AAAA,GACD,CAAA;AAED,EAAA,OAAO,EAAE,GAAA,EAAK,OAAA,EAAS,OAAA,EAAQ;AACjC;AAKA,IAAM,YAAA,0BAAsB,QAAQ,CAAA;AAI7B,SAAS,UAAa,IAAA,EAA6B;AACxD,EAAA,OAAO,IAAA,IAAQ,CAAC,CAAE,IAAA,CAAoB,YAAY,CAAA;AACpD;AAEO,SAAS,OAAyB,IAAA,EAAY;AACnD,EAAA,IAAI,IAAA,IAAQ,SAAA,CAAU,IAAI,CAAA,EAAG;AAC3B,IAAA,OAAO,KAAK,YAAY,CAAA;AAAA,EAC1B,CAAA,MAAO;AACL,IAAA,OAAO,IAAA;AAAA,EACT;AACF;AAEO,SAAS,IAAA,CACd,MACA,OAAA,EACY;AACZ,EAAA,MAAM,KAAA,GAAQ,IAAI,KAAA,CAAM,IAAA,EAAM,OAAO,CAAA;AACrC,EAAA,MAAA,CAAO,cAAA,CAAe,OAAO,YAAA,EAAc;AAAA,IACzC,KAAA,EAAO,IAAA;AAAA,IACP,QAAA,EAAU,KAAA;AAAA,IACV,UAAA,EAAY,KAAA;AAAA,IACZ,YAAA,EAAc;AAAA,GACf,CAAA;AACD,EAAA,OAAO,KAAA;AACT","file":"chunk-5NL62W4L.js","sourcesContent":["/**\n * Common instrumentation utilities\n */\n\n/**\n * Promise tracker for waitUntil\n */\nexport class PromiseTracker {\n  private promises: Promise<unknown>[] = [];\n\n  track(promise: Promise<unknown>): void {\n    this.promises.push(promise);\n  }\n\n  async wait(): Promise<void> {\n    await Promise.allSettled(this.promises);\n  }\n}\n\n/**\n * Proxy ExecutionContext to track waitUntil promises\n */\nexport function proxyExecutionContext(ctx: ExecutionContext): {\n  ctx: ExecutionContext;\n  tracker: PromiseTracker;\n} {\n  const tracker = new PromiseTracker();\n\n  const proxied = new Proxy(ctx, {\n    get(target, prop) {\n      if (prop === 'waitUntil') {\n        return (promise: Promise<unknown>) => {\n          tracker.track(promise);\n          return target.waitUntil(promise);\n        };\n      }\n      return Reflect.get(target, prop);\n    },\n  });\n\n  return { ctx: proxied, tracker };\n}\n\n/**\n * Helper to wrap/unwrap proxied objects\n */\nconst unwrapSymbol = Symbol('unwrap');\n\ntype Wrapped<T> = { [unwrapSymbol]: T } & T;\n\nexport function isWrapped<T>(item: T): item is Wrapped<T> {\n  return item && !!(item as Wrapped<T>)[unwrapSymbol];\n}\n\nexport function unwrap<T extends object>(item: T): T {\n  if (item && isWrapped(item)) {\n    return item[unwrapSymbol];\n  } else {\n    return item;\n  }\n}\n\nexport function wrap<T extends object>(\n  item: T,\n  handler: ProxyHandler<T>,\n): Wrapped<T> {\n  const proxy = new Proxy(item, handler) as Wrapped<T>;\n  Object.defineProperty(proxy, unwrapSymbol, {\n    value: item,\n    writable: false,\n    enumerable: false,\n    configurable: false,\n  });\n  return proxy;\n}\n"]}