@oxy.so/telemetry 1.1.1 → 2.0.0

package/src/__tests__/collector.test.ts

@@ -1,48 +1,95 @@
 /** @jest-environment node */
 import { EventEmitter } from 'node:events';
-import { createTrafficCollector, instrumentTrafficFetch, trafficMiddleware, trafficType, type TrafficAggregate } from '../collector';
+import {
+  createTrafficCollector,
+  instrumentTrafficFetch,
+  trafficMiddleware,
+  trafficType,
+  type TrafficAggregate,
+} from '../collector';
 
 describe('ecosystem activity collector', () => {
   it('reports all products independently of dashboard viewers and counts errors too', async () => {
     const batches: TrafficAggregate[][] = [];
-    const collector = createTrafficCollector(async events => { batches.push(events); });
+    const collector = createTrafficCollector(async (events) => {
+      batches.push(events);
+    });
     for (const service of ['website', 'mention', 'mercaria', 'alia', 'kaana']) {
       const response = new EventEmitter();
-      trafficMiddleware(collector, service, 'us-west-2')({ path: '/api/files/private-id', headers: { 'cf-ray': 'example-NRT', authorization: 'secret' } }, response, () => {});
+      trafficMiddleware(collector, service, 'us-west-2')(
+        {
+          path: '/api/files/private-id',
+          headers: { 'cf-ray': 'example-NRT', authorization: 'secret' },
+        },
+        response,
+        () => {},
+      );
       response.emit('finish');
       response.emit('close');
     }
     await collector.flush();
     expect(batches[0]).toHaveLength(10);
-    expect(batches[0].filter(event => event.direction === 'inbound')).toHaveLength(5);
-    expect(batches[0].every(event => event.activityType === 'media')).toBe(true);
+    expect(batches[0].filter((event) => event.direction === 'inbound')).toHaveLength(5);
+    expect(batches[0].every((event) => event.activityType === 'media')).toBe(true);
     expect(JSON.stringify(batches)).not.toMatch(/private-id|secret|authorization/);
   });
 
   it('keeps scope, direction and category independent for co-located internal services', async () => {
     const batches: TrafficAggregate[][] = [];
-    const collector = createTrafficCollector(async events => { batches.push(events); });
+    const collector = createTrafficCollector(async (events) => {
+      batches.push(events);
+    });
     const response = new EventEmitter();
-    const request = { path: '/v1/chat/completions', headers: { 'x-oxy-source-region': 'us-west-2' }, serviceApp: undefined as undefined | { appName: string } };
-    trafficMiddleware(collector, 'kaana', 'us-west-2')(request, response, () => { request.serviceApp = { appName: 'oxy-api' }; });
+    const request = {
+      path: '/v1/chat/completions',
+      headers: { 'x-oxy-source-region': 'us-west-2' },
+      serviceApp: undefined as undefined | { appName: string },
+    };
+    trafficMiddleware(collector, 'kaana', 'us-west-2')(request, response, () => {
+      request.serviceApp = { appName: 'oxy-api' };
+    });
     response.emit('finish');
     await collector.flush();
     expect(batches[0]).toEqual([
-      expect.objectContaining({ sourceRegion: 'us-west-2', targetRegion: 'us-west-2', sourceService: 'oxy-api', targetService: 'kaana', direction: 'inbound', scope: 'internal', activityType: 'ai' }),
-      expect.objectContaining({ sourceService: 'kaana', targetService: 'oxy-api', direction: 'outbound', scope: 'internal', activityType: 'ai' }),
+      expect.objectContaining({
+        sourceRegion: 'us-west-2',
+        targetRegion: 'us-west-2',
+        sourceService: 'oxy-api',
+        targetService: 'kaana',
+        direction: 'inbound',
+        scope: 'internal',
+        activityType: 'ai',
+      }),
+      expect.objectContaining({
+        sourceService: 'kaana',
+        targetService: 'oxy-api',
+        direction: 'outbound',
+        scope: 'internal',
+        activityType: 'ai',
+      }),
     ]);
   });
 
   it('does not fabricate a response on abort and excludes telemetry control traffic', async () => {
     const batches: TrafficAggregate[][] = [];
-    const collector = createTrafficCollector(async events => { batches.push(events); });
+    const collector = createTrafficCollector(async (events) => {
+      batches.push(events);
+    });
     for (const path of ['/health', '/api/ready', '/platform-stats/stream', '/internal/activity']) {
       const response = new EventEmitter();
-      trafficMiddleware(collector, 'website', 'us-west-2')({ path, headers: {} }, response, () => {});
+      trafficMiddleware(collector, 'website', 'us-west-2')(
+        { path, headers: {} },
+        response,
+        () => {},
+      );
       response.emit('finish');
     }
     const aborted = new EventEmitter();
-    trafficMiddleware(collector, 'mention', 'us-west-2')({ path: '/messages', headers: {} }, aborted, () => {});
+    trafficMiddleware(collector, 'mention', 'us-west-2')(
+      { path: '/messages', headers: {} },
+      aborted,
+      () => {},
+    );
     aborted.emit('close');
     await collector.flush();
     expect(batches[0]).toHaveLength(1);
@@ -51,41 +98,99 @@ describe('ecosystem activity collector', () => {
 
   it('tracks real outgoing calls and only reports the response when one arrived', async () => {
     const batches: TrafficAggregate[][] = [];
-    const collector = createTrafficCollector(async events => { batches.push(events); });
-    const fetcher = instrumentTrafficFetch(jest.fn(async () => new Response('ok', { headers: { 'X-Oxy-Region': 'eu-central-1' } })) as unknown as typeof fetch, collector, 'alia', 'us-west-2', url => url.hostname === 'api.oxy.so' ? { service: 'oxy-api', region: 'us-west-2' } : undefined);
+    const collector = createTrafficCollector(async (events) => {
+      batches.push(events);
+    });
+    const fetcher = instrumentTrafficFetch(
+      jest.fn(
+        async () => new Response('ok', { headers: { 'X-Oxy-Region': 'eu-central-1' } }),
+      ) as unknown as typeof fetch,
+      collector,
+      'alia',
+      'us-west-2',
+      (url) =>
+        url.hostname === 'api.oxy.so' ? { service: 'oxy-api', region: 'us-west-2' } : undefined,
+    );
     await fetcher('https://api.oxy.so/v1/chat/completions');
     await collector.flush();
-    expect(batches[0].map(event => event.direction)).toEqual(['outbound', 'inbound']);
-    expect(batches[0].every(event => event.scope === 'internal')).toBe(true);
+    expect(batches[0].map((event) => event.direction)).toEqual(['outbound', 'inbound']);
+    expect(batches[0].every((event) => event.scope === 'internal')).toBe(true);
     expect(batches[0][0].targetRegion).toBe('eu-central-1');
     expect(batches[0][1].sourceRegion).toBe('eu-central-1');
-    const failed = instrumentTrafficFetch(jest.fn(async () => { throw new Error('offline'); }) as unknown as typeof fetch, collector, 'alia', 'us-west-2', () => undefined);
+    const failed = instrumentTrafficFetch(
+      jest.fn(async () => {
+        throw new Error('offline');
+      }) as unknown as typeof fetch,
+      collector,
+      'alia',
+      'us-west-2',
+      () => undefined,
+    );
     await expect(failed('https://example.com/files')).rejects.toThrow('offline');
     await collector.flush();
     expect(batches[1]).toHaveLength(1);
-    expect(batches[1][0]).toMatchObject({ scope: 'external', direction: 'outbound', activityType: 'media' });
+    expect(batches[1][0]).toMatchObject({
+      scope: 'external',
+      direction: 'outbound',
+      activityType: 'media',
+    });
   });
 
   it('chunks a busy fleet into ingestible batches and preserves fetch extensions', async () => {
     const batches: TrafficAggregate[][] = [];
-    const collector = createTrafficCollector(async events => { batches.push(events); });
-    for (let index = 0; index < 300; index++) collector.record({ region: 'us-west-2', service: `service-${index}`, scope: 'internal', direction: 'inbound', activityType: 'platform' });
+    const collector = createTrafficCollector(async (events) => {
+      batches.push(events);
+    });
+    for (let index = 0; index < 300; index++)
+      collector.record({
+        region: 'us-west-2',
+        service: `service-${index}`,
+        scope: 'internal',
+        direction: 'inbound',
+        activityType: 'platform',
+      });
     await collector.flush();
-    expect(batches.map(batch => batch.length)).toEqual([256, 44]);
+    expect(batches.map((batch) => batch.length)).toEqual([256, 44]);
     const preconnect = jest.fn();
-    const baseFetch = Object.assign(jest.fn(async () => new Response()), { preconnect }) as unknown as typeof fetch;
-    const wrapped = instrumentTrafficFetch(baseFetch, collector, 'website', 'us-west-2', () => undefined);
+    const baseFetch = Object.assign(
+      jest.fn(async () => new Response()),
+      { preconnect },
+    ) as unknown as typeof fetch;
+    const wrapped = instrumentTrafficFetch(
+      baseFetch,
+      collector,
+      'website',
+      'us-west-2',
+      () => undefined,
+    );
     expect((wrapped as typeof baseFetch & { preconnect: unknown }).preconnect).toBe(preconnect);
   });
 
   it('keeps verified internal attribution when a request aborts', async () => {
     const batches: TrafficAggregate[][] = [];
-    const collector = createTrafficCollector(async events => { batches.push(events); });
+    const collector = createTrafficCollector(async (events) => {
+      batches.push(events);
+    });
     const response = new EventEmitter();
-    trafficMiddleware(collector, 'oxy-api', 'us-west-2')({ path: '/messages', headers: { 'x-oxy-source-region': 'eu-west-1' }, serviceApp: { appName: 'mention' } }, response, () => {});
+    trafficMiddleware(collector, 'oxy-api', 'us-west-2')(
+      {
+        path: '/messages',
+        headers: { 'x-oxy-source-region': 'eu-west-1' },
+        serviceApp: { appName: 'mention' },
+      },
+      response,
+      () => {},
+    );
     response.emit('close');
     await collector.flush();
-    expect(batches[0]).toEqual([expect.objectContaining({ scope: 'internal', direction: 'inbound', sourceRegion: 'eu-west-1', sourceService: 'mention' })]);
+    expect(batches[0]).toEqual([
+      expect.objectContaining({
+        scope: 'internal',
+        direction: 'inbound',
+        sourceRegion: 'eu-west-1',
+        sourceService: 'mention',
+      }),
+    ]);
   });
 
   it('classifies versioned media and inference endpoints without retaining the path', () => {

package/src/__tests__/server.test.ts

@@ -10,11 +10,13 @@ import {
 
 describe('server telemetry primitives', () => {
   it('prefers a validated forwarded PoP and accepts Cloudflare ray fallback', () => {
-    expect(metadataFromHeaders({
-      'x-oxy-edge-region': 'MAD',
-      'cf-ray': 'deadbeef-CDG',
-      'x-oxy-activity-id': 'anonymous-runtime-a1',
-    })).toEqual({ edgePop: 'mad', activityId: 'anonymous-runtime-a1' });
+    expect(
+      metadataFromHeaders({
+        'x-oxy-edge-region': 'MAD',
+        'cf-ray': 'deadbeef-CDG',
+        'x-oxy-activity-id': 'anonymous-runtime-a1',
+      }),
+    ).toEqual({ edgePop: 'mad', activityId: 'anonymous-runtime-a1' });
     expect(metadataFromHeaders({ 'cf-ray': 'deadbeef-CDG' })).toEqual({ edgePop: 'cdg' });
   });
 

package/src/__tests__/socket.test.ts

@@ -8,22 +8,42 @@ class TestSocket extends EventEmitter {
   nsp = { name: '/messages' };
   incoming = new Set<(event: string) => void>();
   outgoing = new Set<(event: string) => void>();
-  onAny(listener: (event: string) => void) { this.incoming.add(listener); }
-  onAnyOutgoing(listener: (event: string) => void) { this.outgoing.add(listener); }
-  offAny(listener: (event: string) => void) { this.incoming.delete(listener); }
-  offAnyOutgoing(listener: (event: string) => void) { this.outgoing.delete(listener); }
+  onAny(listener: (event: string) => void) {
+    this.incoming.add(listener);
+  }
+  onAnyOutgoing(listener: (event: string) => void) {
+    this.outgoing.add(listener);
+  }
+  offAny(listener: (event: string) => void) {
+    this.incoming.delete(listener);
+  }
+  offAnyOutgoing(listener: (event: string) => void) {
+    this.outgoing.delete(listener);
+  }
 }
 
 describe('socket traffic', () => {
   it('records real application directions and strips event identifiers and payloads', () => {
     const socket = new TestSocket();
     const events: TrafficFlow[] = [];
-    observeTrafficSocket(socket, { record: event => events.push(event) }, 'syra', 'us-west-2');
-    socket.incoming.forEach(listener => listener('player:private-track-id'));
-    socket.outgoing.forEach(listener => listener('message:private-user-id'));
+    observeTrafficSocket(socket, { record: (event) => events.push(event) }, 'syra', 'us-west-2');
+    socket.incoming.forEach((listener) => listener('player:private-track-id'));
+    socket.outgoing.forEach((listener) => listener('message:private-user-id'));
     expect(events).toEqual([
-      expect.objectContaining({ scope: 'external', direction: 'inbound', sourceRegion: 'edge-mad', targetRegion: 'us-west-2', activityType: 'media' }),
-      expect.objectContaining({ scope: 'external', direction: 'outbound', sourceRegion: 'us-west-2', targetRegion: 'edge-mad', activityType: 'communication' }),
+      expect.objectContaining({
+        scope: 'external',
+        direction: 'inbound',
+        sourceRegion: 'edge-mad',
+        targetRegion: 'us-west-2',
+        activityType: 'media',
+      }),
+      expect.objectContaining({
+        scope: 'external',
+        direction: 'outbound',
+        sourceRegion: 'us-west-2',
+        targetRegion: 'edge-mad',
+        activityType: 'communication',
+      }),
     ]);
     expect(JSON.stringify(events)).not.toMatch(/private|authorization|track-id|user-id/);
     socket.emit('disconnect');
@@ -34,11 +54,23 @@ describe('socket traffic', () => {
     const socket = new TestSocket();
     const events: TrafficFlow[] = [];
     let peer: { service: string; region: string } | undefined;
-    const stop = observeTrafficSocket(socket, { record: event => events.push(event) }, 'alia', 'us-west-2', { getPeer: () => peer });
+    const stop = observeTrafficSocket(
+      socket,
+      { record: (event) => events.push(event) },
+      'alia',
+      'us-west-2',
+      { getPeer: () => peer },
+    );
     peer = { service: 'mention', region: 'eu-west-1' };
-    socket.incoming.forEach(listener => listener('agent:update'));
-    expect(events[0]).toMatchObject({ scope: 'internal', sourceService: 'mention', sourceRegion: 'eu-west-1', activityType: 'ai' });
-    stop(); stop();
+    socket.incoming.forEach((listener) => listener('agent:update'));
+    expect(events[0]).toMatchObject({
+      scope: 'internal',
+      sourceService: 'mention',
+      sourceRegion: 'eu-west-1',
+      activityType: 'ai',
+    });
+    stop();
+    stop();
     expect(socket.listenerCount('disconnect')).toBe(0);
   });
 
@@ -61,32 +93,39 @@ describe('real Socket.IO transport', () => {
     const server = createServer();
     const sockets = new Server(server);
     const events: TrafficFlow[] = [];
-    sockets.on('connection', socket => {
-      observeTrafficSocket(socket, { record: flow => events.push(flow) }, 'syra', 'us-west-2');
+    sockets.on('connection', (socket) => {
+      observeTrafficSocket(socket, { record: (flow) => events.push(flow) }, 'syra', 'us-west-2');
       socket.on('player:seek', (_position, acknowledge) => {
         acknowledge('ok');
         sockets.emit('player:state', { privateTrackId: 'never-published' });
       });
     });
-    await new Promise<void>(resolve => server.listen(0, '127.0.0.1', resolve));
+    await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve));
     const address = server.address();
     if (!address || typeof address === 'string') throw new Error('Missing listener');
-    const client = io(`http://127.0.0.1:${address.port}`, { transports: ['websocket'], extraHeaders: { 'X-Oxy-Edge-Region': 'NRT' } });
+    const client = io(`http://127.0.0.1:${address.port}`, {
+      transports: ['websocket'],
+      extraHeaders: { 'X-Oxy-Edge-Region': 'NRT' },
+    });
     try {
-      await new Promise<void>((resolve, reject) => { client.once('connect', resolve); client.once('connect_error', reject); });
-      const received = new Promise<void>(resolve => client.once('player:state', () => resolve()));
+      await new Promise<void>((resolve, reject) => {
+        client.once('connect', resolve);
+        client.once('connect_error', reject);
+      });
+      const received = new Promise<void>((resolve) => client.once('player:state', () => resolve()));
       await client.emitWithAck('player:seek', 42);
       await received;
       expect(events).toHaveLength(2);
-      expect(events.map(flow => [flow.direction, flow.scope, flow.activityType])).toEqual([
-        ['inbound', 'external', 'media'], ['outbound', 'external', 'media'],
+      expect(events.map((flow) => [flow.direction, flow.scope, flow.activityType])).toEqual([
+        ['inbound', 'external', 'media'],
+        ['outbound', 'external', 'media'],
       ]);
       expect(events[0].sourceRegion).toBe('edge-nrt');
       expect(events[1].targetRegion).toBe('edge-nrt');
       expect(JSON.stringify(events)).not.toContain('never-published');
     } finally {
       client.disconnect();
-      await new Promise<void>(resolve => sockets.close(() => resolve()));
+      await new Promise<void>((resolve) => sockets.close(() => resolve()));
     }
   });
 });
@@ -97,21 +136,33 @@ describe('raw WebSocket transport', () => {
     const events: TrafficFlow[] = [];
     const original = jest.fn((_data: unknown, callback: (error?: Error) => void) => callback());
     const socket = Object.assign(new EventEmitter(), { readyState: 1, send: original });
-    const stop = observeTrafficWebSocket(socket, { record: flow => events.push(flow) }, 'alia', 'us-west-2', {
-      activityType: 'ai', getPeer: () => ({ service: 'alia-integrations', region: 'eu-west-1' }),
-    });
+    const stop = observeTrafficWebSocket(
+      socket,
+      { record: (flow) => events.push(flow) },
+      'alia',
+      'us-west-2',
+      {
+        activityType: 'ai',
+        getPeer: () => ({ service: 'alia-integrations', region: 'eu-west-1' }),
+      },
+    );
     const callback = jest.fn();
     socket.send({ privateBody: 'not-recorded' }, callback);
     socket.emit('message', Buffer.from('private-message'));
     expect(original).toHaveBeenCalledWith({ privateBody: 'not-recorded' }, callback);
     expect(callback).toHaveBeenCalledTimes(1);
-    expect(events.map(flow => flow.direction)).toEqual(['outbound', 'inbound']);
-    expect(events.every(flow => flow.scope === 'internal' && flow.activityType === 'ai')).toBe(true);
+    expect(events.map((flow) => flow.direction)).toEqual(['outbound', 'inbound']);
+    expect(events.every((flow) => flow.scope === 'internal' && flow.activityType === 'ai')).toBe(
+      true,
+    );
     expect(JSON.stringify(events)).not.toMatch(/private|not-recorded/);
-    original.mockImplementationOnce(() => { throw new Error('send failed'); });
+    original.mockImplementationOnce(() => {
+      throw new Error('send failed');
+    });
     expect(() => socket.send('', callback)).toThrow('send failed');
     expect(events).toHaveLength(2);
-    stop(); stop();
+    stop();
+    stop();
     expect(socket.send).toBe(original);
     expect(socket.listenerCount('message')).toBe(0);
   });

package/src/browser.ts

@@ -3,6 +3,12 @@ import { OXY_ACTIVITY_ID_HEADER, OXY_EDGE_REGION_HEADER } from './index.js';
 export const DEFAULT_ACTIVITY_ID_ROTATION_MS = 5 * 60 * 1_000;
 export const DEFAULT_EDGE_TRACE_TIMEOUT_MS = 1_000;
 export const DEFAULT_EDGE_CACHE_MS = 15_000;
+/**
+ * How long `peekEdgeRegionHeader` trusts a known PoP before refreshing it in the
+ * background. A client's serving PoP rarely changes within minutes, and the
+ * peek never blocks, so this only bounds the trace traffic.
+ */
+export const DEFAULT_EDGE_PEEK_REFRESH_MS = 10 * 60_000;
 
 interface TraceResponse {
   ok: boolean;
@@ -13,6 +19,7 @@ export interface BrowserTelemetryOptions {
   activityIdRotationMs?: number;
   edgeTraceTimeoutMs?: number;
   edgeCacheMs?: number;
+  edgePeekRefreshMs?: number;
   now?: () => number;
   crypto?: Pick<Crypto, 'getRandomValues' | 'randomUUID'>;
   location?: Pick<Location, 'hostname' | 'protocol'>;
@@ -22,10 +29,18 @@ export interface BrowserTelemetryOptions {
 export interface BrowserTelemetry {
   getActivityIdHeader(): Record<string, string>;
   getEdgeRegionHeader(): Promise<Record<string, string>>;
+  /**
+   * The last known edge-region header, synchronously, never waiting on the
+   * trace: `{}` until the first discovery lands. A stale or missing value
+   * starts a refresh in the background.
+   */
+  peekEdgeRegionHeader(): Record<string, string>;
   getHeaders(): Promise<Record<string, string>>;
 }
 
-function createUuid(cryptoApi: Pick<Crypto, 'getRandomValues' | 'randomUUID'> | undefined): string | null {
+function createUuid(
+  cryptoApi: Pick<Crypto, 'getRandomValues' | 'randomUUID'> | undefined,
+): string | null {
   if (!cryptoApi) return null;
   if (typeof cryptoApi.randomUUID === 'function') return cryptoApi.randomUUID();
 
@@ -38,9 +53,11 @@ function createUuid(cryptoApi: Pick<Crypto, 'getRandomValues' | 'randomUUID'> |
 
 function eligibleLocation(location: Pick<Location, 'hostname' | 'protocol'> | undefined): boolean {
   if (!location || (location.protocol !== 'https:' && location.protocol !== 'http:')) return false;
-  return location.hostname !== 'localhost'
-    && location.hostname !== '127.0.0.1'
-    && location.hostname !== '[::1]';
+  return (
+    location.hostname !== 'localhost' &&
+    location.hostname !== '127.0.0.1' &&
+    location.hostname !== '[::1]'
+  );
 }
 
 export function createBrowserTelemetry(options: BrowserTelemetryOptions = {}): BrowserTelemetry {
@@ -54,7 +71,11 @@ export function createBrowserTelemetry(options: BrowserTelemetryOptions = {}): B
     const hasBrowserRuntime = typeof window !== 'undefined' && typeof document !== 'undefined';
     if (!hasInjectedBrowser && !hasBrowserRuntime) return {};
     const now = (options.now ?? Date.now)();
-    if (!activityId || now < activityIdCreatedAt || now - activityIdCreatedAt >= (options.activityIdRotationMs ?? DEFAULT_ACTIVITY_ID_ROTATION_MS)) {
+    if (
+      !activityId ||
+      now < activityIdCreatedAt ||
+      now - activityIdCreatedAt >= (options.activityIdRotationMs ?? DEFAULT_ACTIVITY_ID_ROTATION_MS)
+    ) {
       activityId = createUuid(options.crypto ?? globalThis.crypto);
       if (!activityId) return {};
       activityIdCreatedAt = now;
@@ -63,14 +84,22 @@ export function createBrowserTelemetry(options: BrowserTelemetryOptions = {}): B
   };
 
   const discoverEdgePop = async (): Promise<string | null> => {
-    const browserLocation = options.location ?? (typeof window === 'undefined' ? undefined : window.location);
+    const browserLocation =
+      options.location ?? (typeof window === 'undefined' ? undefined : window.location);
     if (!eligibleLocation(browserLocation)) return null;
     const controller = new AbortController();
-    const timeout = setTimeout(() => controller.abort(), options.edgeTraceTimeoutMs ?? DEFAULT_EDGE_TRACE_TIMEOUT_MS);
+    const timeout = setTimeout(
+      () => controller.abort(),
+      options.edgeTraceTimeoutMs ?? DEFAULT_EDGE_TRACE_TIMEOUT_MS,
+    );
     try {
       const response = await (options.fetchTrace
         ? options.fetchTrace(controller.signal)
-        : fetch('/cdn-cgi/trace', { cache: 'no-store', credentials: 'omit', signal: controller.signal }));
+        : fetch('/cdn-cgi/trace', {
+            cache: 'no-store',
+            credentials: 'omit',
+            signal: controller.signal,
+          }));
       if (!response.ok) return null;
       const match = (await response.text()).match(/^colo=([a-z]{3})$/im);
       return match ? match[1].toLowerCase() : null;
@@ -83,7 +112,11 @@ export function createBrowserTelemetry(options: BrowserTelemetryOptions = {}): B
 
   const getEdgeRegionHeader = async (): Promise<Record<string, string>> => {
     const now = (options.now ?? Date.now)();
-    if (!edgePopPromise || now < edgePopReadAt || now - edgePopReadAt >= (options.edgeCacheMs ?? DEFAULT_EDGE_CACHE_MS)) {
+    if (
+      !edgePopPromise ||
+      now < edgePopReadAt ||
+      now - edgePopReadAt >= (options.edgeCacheMs ?? DEFAULT_EDGE_CACHE_MS)
+    ) {
       edgePopReadAt = now;
       edgePopPromise = discoverEdgePop();
     }
@@ -91,11 +124,36 @@ export function createBrowserTelemetry(options: BrowserTelemetryOptions = {}): B
     return edgePop ? { [OXY_EDGE_REGION_HEADER]: edgePop } : {};
   };
 
+  let peekedPop: string | null = null;
+  let peekRefreshAt = -Infinity;
+  let peekInFlight = false;
+
+  const peekEdgeRegionHeader = (): Record<string, string> => {
+    const now = (options.now ?? Date.now)();
+    if (
+      !peekInFlight &&
+      (now < peekRefreshAt ||
+        now - peekRefreshAt >= (options.edgePeekRefreshMs ?? DEFAULT_EDGE_PEEK_REFRESH_MS))
+    ) {
+      peekRefreshAt = now;
+      peekInFlight = true;
+      void discoverEdgePop()
+        .then((pop) => {
+          if (pop) peekedPop = pop;
+        })
+        .finally(() => {
+          peekInFlight = false;
+        });
+    }
+    return peekedPop ? { [OXY_EDGE_REGION_HEADER]: peekedPop } : {};
+  };
+
   return {
     getActivityIdHeader,
     getEdgeRegionHeader,
+    peekEdgeRegionHeader,
     async getHeaders(): Promise<Record<string, string>> {
-      return { ...await getEdgeRegionHeader(), ...getActivityIdHeader() };
+      return { ...(await getEdgeRegionHeader()), ...getActivityIdHeader() };
     },
   };
 }
@@ -108,5 +166,8 @@ export const getBrowserActivityIdHeader = (): Record<string, string> =>
 export const getBrowserEdgeRegionHeader = (): Promise<Record<string, string>> =>
   defaultBrowserTelemetry.getEdgeRegionHeader();
 
+export const peekBrowserEdgeRegionHeader = (): Record<string, string> =>
+  defaultBrowserTelemetry.peekEdgeRegionHeader();
+
 export const getBrowserTelemetryHeaders = (): Promise<Record<string, string>> =>
   defaultBrowserTelemetry.getHeaders();