@oxy.so/telemetry 2.0.0 → 2.2.0

package/src/collector.ts

@@ -1,24 +1,19 @@
-import { metadataFromHeaders, type TelemetryHeaders } from './server.js';
+import {
+  OXY_REGION_HEADER,
+  OXY_SOURCE_REGION_HEADER,
+  type TrafficAggregate,
+  type TrafficFlow,
+  type TrafficType,
+} from './index.js';
+import { metadataFromHeaders, sourceRegionFromEdgePop, type TelemetryHeaders } from './server.js';
 
-export type TrafficScope = 'internal' | 'external';
-export type TrafficDirection = 'inbound' | 'outbound';
-export type TrafficType = 'identity' | 'ai' | 'communication' | 'media' | 'platform';
-export interface TrafficFlow {
-  region: string;
-  sourceRegion?: string;
-  targetRegion?: string;
-  sourceService?: string;
-  targetService?: string;
-  service: string;
-  scope: TrafficScope;
-  direction: TrafficDirection;
-  activityType: TrafficType;
-}
-export interface TrafficAggregate extends TrafficFlow {
-  requests: number;
-  windowStartedAt: string;
-  emittedAt: string;
-}
+export type {
+  TrafficAggregate,
+  TrafficDirection,
+  TrafficFlow,
+  TrafficScope,
+  TrafficType,
+} from './index.js';
 
 const TYPES: Record<string, TrafficType> = {
   auth: 'identity',
@@ -58,6 +53,49 @@ export function trafficType(path: string): TrafficType {
   return TYPES[parts[0] ?? ''] ?? 'platform';
 }
 
+/** Which side of a request a reporter is observing. */
+export type ObservationDirection = 'inbound' | 'outbound';
+
+/**
+ * Every path a reporter does not observe, in ONE table. Each entry says which
+ * directions it applies to: the inbound and outbound sets differ today (an
+ * outbound call to a probe or to `/platform-stats` IS recorded), and that is
+ * preserved exactly. Unifying them is a separate, deliberate decision.
+ */
+export const UNOBSERVED_PATHS: readonly {
+  readonly directions: ObservationDirection | 'both';
+  readonly matches: (path: string) => boolean;
+}[] = [
+  {
+    directions: 'inbound',
+    matches: (path) =>
+      /^\/(?:api\/)?(?:health|ready|live|platform-stats|platform-activity|infra-status)(?:\/|$)/.test(
+        path,
+      ),
+  },
+  {
+    directions: 'inbound',
+    matches: (path) => /^\/(?:api\/)?platform-infrastructure(?:\/|$)/.test(path),
+  },
+  { directions: 'outbound', matches: (path) => path === '/platform-infrastructure' },
+  { directions: 'both', matches: (path) => path.startsWith('/internal/activity') },
+  { directions: 'both', matches: (path) => path.startsWith('/auth/service-token') },
+  { directions: 'inbound', matches: (path) => path.startsWith('/cdn-cgi/') },
+];
+
+/**
+ * Is this path part of what a reporter observes in this direction? Collection
+ * itself, service-token minting and (inbound) probes and the dashboard
+ * transport are control traffic: observing them would feed back into the very
+ * activity they carry.
+ */
+export function isObservedPath(path: string, direction: ObservationDirection): boolean {
+  return !UNOBSERVED_PATHS.some(
+    (entry) =>
+      (entry.directions === 'both' || entry.directions === direction) && entry.matches(path),
+  );
+}
+
 export function createTrafficCollector(
   publish: (events: TrafficAggregate[]) => Promise<unknown>,
   now = Date.now,
@@ -112,17 +150,10 @@ export function trafficMiddleware(
   region: string,
 ) {
   return (request: HttpRequest, response: HttpResponse, next: () => void): void => {
-    response.setHeader?.('X-Oxy-Region', region);
+    response.setHeader?.(OXY_REGION_HEADER, region);
     const path = request.path ?? request.url ?? '/';
     // Never report collection itself, probes or the dashboard transport.
-    if (
-      /^\/(?:api\/)?(?:health|ready|live|platform-stats|platform-activity|platform-infrastructure|infra-status)(?:\/|$)/.test(
-        path,
-      ) ||
-      path.startsWith('/internal/activity') ||
-      path.startsWith('/auth/service-token') ||
-      path.startsWith('/cdn-cgi/')
-    ) {
+    if (!isObservedPath(path, 'inbound')) {
       next();
       return;
     }
@@ -136,12 +167,10 @@ export function trafficMiddleware(
         .replace(/[^a-z0-9-]/g, '-')
         .slice(0, 40);
       const internal = Boolean(name);
-      const forwardedRegion = request.headers['x-oxy-source-region'];
+      const forwardedRegion = request.headers[OXY_SOURCE_REGION_HEADER.toLowerCase()];
       const peerRegion = internal
         ? normalizeInfrastructureRegion(forwardedRegion)
-        : edgePop
-          ? `edge-${edgePop}`
-          : undefined;
+        : sourceRegionFromEdgePop(edgePop);
       return {
         region,
         service,
@@ -196,12 +225,7 @@ export function instrumentTrafficFetch(
       typeof input === 'string' ? input : input instanceof URL ? input.href : input.url,
     );
     // Collection/auth control traffic cannot generate a feedback loop.
-    if (
-      url.pathname.startsWith('/internal/activity') ||
-      url.pathname.startsWith('/auth/service-token') ||
-      url.pathname === '/platform-infrastructure'
-    )
-      return fetcher(input, init);
+    if (!isObservedPath(url.pathname, 'outbound')) return fetcher(input, init);
     const peer = resolveEndpoint(url);
     const flow: TrafficFlow = {
       service,
@@ -217,7 +241,7 @@ export function instrumentTrafficFetch(
     const headers = new Headers(
       init?.headers ?? (input instanceof Request ? input.headers : undefined),
     );
-    if (peer) headers.set('X-Oxy-Source-Region', region);
+    if (peer) headers.set(OXY_SOURCE_REGION_HEADER, region);
     let response: Response;
     try {
       response = await fetcher(input, { ...init, headers });
@@ -226,7 +250,7 @@ export function instrumentTrafficFetch(
       throw error;
     }
     const targetRegion = peer
-      ? normalizeInfrastructureRegion(response.headers.get('X-Oxy-Region') ?? undefined)
+      ? normalizeInfrastructureRegion(response.headers.get(OXY_REGION_HEADER) ?? undefined)
       : undefined;
     collector.record({ ...flow, targetRegion });
     collector.record({
@@ -245,11 +269,12 @@ export function instrumentTrafficFetch(
 // to be an internal service. Region is infrastructure metadata, never IP geo.
 const OXY_API_SERVICES: Record<string, string> = {
   'api.oxy.so': 'oxy-api',
-  'api.website.oxy.so': 'website',
   'website-api.oxy.so': 'website',
   'api.mention.earth': 'mention',
   'api.mercaria.co': 'mercaria',
+  // Old Alia app builds still call it; goes when api.alia.onl is retired (Gemies ADR 0034).
   'api.alia.onl': 'alia',
+  'api.gemies.ai': 'gemies',
   'kaana.ai': 'kaana',
   'api.homiio.com': 'homiio',
   'api.syra.fm': 'syra',

package/src/index.ts

@@ -1,18 +1,79 @@
+/** Request header a browser sends: the ephemeral anonymous activity ID. */
 export const OXY_ACTIVITY_ID_HEADER = 'X-Oxy-Activity-Id';
+/** Request header a browser sends: the three-letter Cloudflare PoP code. */
 export const OXY_EDGE_REGION_HEADER = 'X-Oxy-Edge-Region';
+/** Response header a reporting service sets: the region that processed the request. */
+export const OXY_REGION_HEADER = 'X-Oxy-Region';
+/** Request header one Oxy service sends another: the caller's infrastructure region. */
+export const OXY_SOURCE_REGION_HEADER = 'X-Oxy-Source-Region';
+
+/**
+ * Request headers a browser may send and a CORS allow-list must therefore
+ * permit (`Access-Control-Allow-Headers`). `X-Oxy-Source-Region` is service to
+ * service only and is deliberately absent. The list is derived from the
+ * constants above, so a CORS list built from it cannot drift from them.
+ */
+export const OXY_TELEMETRY_REQUEST_HEADERS: readonly string[] = Object.freeze([
+  OXY_ACTIVITY_ID_HEADER,
+  OXY_EDGE_REGION_HEADER,
+]);
+
+/**
+ * Response headers a browser client may need to read
+ * (`Access-Control-Expose-Headers`).
+ */
+export const OXY_TELEMETRY_EXPOSED_HEADERS: readonly string[] = Object.freeze([OXY_REGION_HEADER]);
 
 export interface AnonymousActivityMetadata {
   activityId?: string;
   edgePop?: string;
 }
 
-export interface ActivityAggregate {
+export type TrafficScope = 'internal' | 'external';
+export type TrafficDirection = 'inbound' | 'outbound';
+export type TrafficType = 'identity' | 'ai' | 'communication' | 'media' | 'platform';
+
+/** One observed flow, as a reporter records it. */
+export interface TrafficFlow {
+  region: string;
   sourceRegion?: string;
-  targetRegion: string;
+  targetRegion?: string;
+  sourceService?: string;
+  targetService?: string;
   service: string;
+  scope: TrafficScope;
+  direction: TrafficDirection;
+  activityType: TrafficType;
+}
+
+/**
+ * A flow with its request count and window: the exact shape the API's strict
+ * `platformActivityBatchSchema` accepts on `POST /internal/activity`.
+ */
+export interface TrafficAggregate extends TrafficFlow {
   requests: number;
-  activeClients: number;
   windowStartedAt: string;
   emittedAt: string;
-  direction: 'inbound';
+}
+
+/**
+ * The `platform_activity` socket payload: an aggregate plus the approximate
+ * active-client count for its origin.
+ */
+export type ActivityAggregate = TrafficAggregate & { activeClients: number };
+
+/** One region in the `platform_infrastructure` snapshot. */
+export interface InfrastructureNode {
+  region: string;
+  label: string;
+  coordinates: [number, number];
+  services: string[];
+  instances: number;
+  status: 'online' | 'degraded' | 'offline' | 'unknown';
+}
+
+/** The `platform_infrastructure` socket payload. */
+export interface InfrastructureSnapshot {
+  emittedAt: string;
+  nodes: InfrastructureNode[];
 }

package/src/metrics.ts

@@ -0,0 +1,302 @@
+/**
+ * Operational metrics for Oxy services, published as CloudWatch Embedded Metric
+ * Format (EMF) log lines.
+ *
+ * WHY EMF ON STDOUT: every Oxy backend runs on ECS with the `awslogs` driver, and
+ * CloudWatch Logs extracts metrics from any log event shaped as EMF — no agent,
+ * no sidecar, no scraper, no IAM grant beyond the logging the task already has.
+ * A registry that only an HTTP scrape can read (Prometheus) measures into a void
+ * when nothing scrapes it, which is how Mention's counters lost every value on
+ * every deploy.
+ *
+ * WHY AGGREGATED: values are folded in memory and flushed once per interval as
+ * ONE line per (metric, label set), not one line per observation. A latency is
+ * kept as a distribution (`Values`/`Counts`), so CloudWatch still answers
+ * SampleCount, p50 and p99 for it — the request COUNT is the distribution's
+ * SampleCount, so a service needs no separate counter for it.
+ *
+ * WHY MOST LABELS ARE NOT DIMENSIONS: every distinct combination of dimension
+ * values is a billed custom metric. Route x method as dimensions once measured
+ * 405 metrics and ~80 % of the account's CloudWatch bill (Mention #1334). So a
+ * label becomes a DIMENSION only when a metric definition names it in
+ * `dimensionSets`, and only labels with a small, closed value set belong there.
+ * Every other label is written as a plain property of the line: free to store,
+ * and grouped in Logs Insights (`stats sum(RequestLatency.Count) by Route`).
+ */
+
+export type MetricUnit =
+  | 'Count'
+  | 'Milliseconds'
+  | 'Seconds'
+  | 'Bytes'
+  | 'Percent'
+  | 'Count/Second'
+  | 'None';
+
+/**
+ * `sum` adds every value in the interval (a counter), `distribution` keeps the
+ * values for percentiles (a latency or a size), and `gauge` keeps the last one.
+ */
+export type MetricKind = 'sum' | 'distribution' | 'gauge';
+
+export interface MetricDefinition {
+  /** CloudWatch metric name; also the field holding its value on the line. */
+  readonly name: string;
+  readonly unit: MetricUnit;
+  readonly kind: MetricKind;
+  /**
+   * Label names promoted to CloudWatch dimensions. Each inner list is one
+   * dimension set, published IN ADDITION to the always-present `[Service]`
+   * set. Only closed, small value sets belong here: each distinct combination
+   * is a billed custom metric.
+   */
+  readonly dimensionSets?: readonly (readonly string[])[];
+}
+
+export type MetricLabels = Readonly<Record<string, string>>;
+
+export interface EmfPublisherOptions {
+  /** CloudWatch namespace, e.g. `Oxy/Api`. */
+  readonly namespace: string;
+  /** Value of the `Service` dimension every metric carries. */
+  readonly service: string;
+  /** Flush period. Default 60 s, CloudWatch's standard resolution. */
+  readonly flushIntervalMs?: number;
+  /**
+   * Distinct (metric, label set) series held per interval. A label value that
+   * traffic can mint must not be able to grow memory or log volume without
+   * bound, so past this many every NEW series is folded into one whose labels
+   * all read `other`. Default 2000.
+   */
+  readonly maxSeries?: number;
+  /** Where each line goes. Default: one line on stdout. */
+  readonly write?: (line: string) => void;
+  /** Clock, for tests. */
+  readonly now?: () => number;
+}
+
+export interface EmfPublisher {
+  /** Fold one observation into the current interval. Never throws. */
+  record(metric: MetricDefinition, value: number, labels?: MetricLabels): void;
+  /** Write the current interval now and start a new one. */
+  flush(): void;
+  /** Flush and stop the timer, for graceful shutdown. */
+  stop(): void;
+}
+
+/** One HTTP request: SampleCount is the request count, percentiles the latency. */
+export const HTTP_REQUEST_LATENCY: MetricDefinition = {
+  name: 'RequestLatency',
+  unit: 'Milliseconds',
+  kind: 'distribution',
+  dimensionSets: [['StatusClass'], ['Caller']],
+};
+
+/** One request a rate limiter refused (429), per calling application. */
+export const HTTP_RATE_LIMITED: MetricDefinition = {
+  name: 'RateLimited',
+  unit: 'Count',
+  kind: 'sum',
+  dimensionSets: [['Caller']],
+};
+
+/** `2xx`, `4xx`, … — a closed set, safe as a dimension. */
+export function statusClass(status: number): string {
+  return Number.isInteger(status) && status >= 100 && status <= 599
+    ? `${Math.floor(status / 100)}xx`
+    : 'other';
+}
+
+/** EMF allows at most 100 distinct values per metric on one line. */
+const MAX_DISTRIBUTION_VALUES = 100;
+/** Neighbouring values within ~5 % share a bucket, which bounds the set. */
+const BUCKET_BASE = 1.05;
+const LABEL_NAME = /^[A-Za-z][A-Za-z0-9_]{0,63}$/;
+const MAX_LABEL_VALUE_LENGTH = 128;
+const RESERVED = new Set(['_aws', 'Service']);
+
+interface Series {
+  metric: MetricDefinition;
+  labels: Record<string, string>;
+  sum: number;
+  last: number;
+  count: number;
+  min: number;
+  max: number;
+  buckets: Map<number, number>;
+}
+
+/** Representative value of a bucket: values within ~5 % collapse together. */
+function bucketOf(value: number): number {
+  if (value <= 0) return 0;
+  const exponent = Math.round(Math.log(value) / Math.log(BUCKET_BASE));
+  return Number((BUCKET_BASE ** exponent).toPrecision(3));
+}
+
+/** Merge adjacent buckets (keeping the larger value) until EMF accepts them. */
+function boundedDistribution(buckets: Map<number, number>): { values: number[]; counts: number[] } {
+  let entries = [...buckets.entries()].sort(([left], [right]) => left - right);
+  while (entries.length > MAX_DISTRIBUTION_VALUES) {
+    const merged: [number, number][] = [];
+    for (let index = 0; index < entries.length; index += 2) {
+      const [value, count] = entries[index];
+      const next = entries[index + 1];
+      merged.push(next ? [next[0], count + next[1]] : [value, count]);
+    }
+    entries = merged;
+  }
+  return { values: entries.map(([value]) => value), counts: entries.map(([, count]) => count) };
+}
+
+function cleanLabels(
+  metric: MetricDefinition,
+  labels: MetricLabels | undefined,
+): Record<string, string> {
+  const clean: Record<string, string> = {};
+  for (const [name, raw] of Object.entries(labels ?? {})) {
+    if (!LABEL_NAME.test(name) || RESERVED.has(name) || name === metric.name) continue;
+    const value = String(raw).slice(0, MAX_LABEL_VALUE_LENGTH);
+    clean[name] = value.length > 0 ? value : 'unknown';
+  }
+  // A dimension named by the definition must be present on every line, or
+  // CloudWatch drops the metric from that line.
+  for (const set of metric.dimensionSets ?? []) {
+    for (const name of set) clean[name] ??= 'unknown';
+  }
+  return clean;
+}
+
+function seriesKey(metric: MetricDefinition, labels: Record<string, string>): string {
+  const pairs = Object.keys(labels)
+    .sort()
+    .map((name) => `${name}=${labels[name]}`);
+  return `${metric.name}\u0000${pairs.join('\u0000')}`;
+}
+
+interface StdoutHost {
+  process?: { stdout?: { write?: (chunk: string) => unknown } };
+}
+
+/** One line on stdout. Reached through `globalThis`: this package carries no Node types. */
+function defaultWrite(line: string): void {
+  (globalThis as StdoutHost).process?.stdout?.write?.(`${line}\n`);
+}
+
+/** Set by ECS on every task: the one reliable signal that `awslogs` is capturing stdout. */
+const ECS_METADATA_ENV = 'ECS_CONTAINER_METADATA_URI_V4';
+
+/**
+ * `createEmfPublisher` on ECS, `null` everywhere else (a laptop, CI, a test):
+ * the gate oxy-api and Mention each repeated. `env` is injectable for tests.
+ */
+export function createEmfPublisherIfDeployed(
+  options: EmfPublisherOptions,
+  env: Readonly<Record<string, string | undefined>> = (
+    globalThis as { process?: { env?: Record<string, string | undefined> } }
+  ).process?.env ?? {},
+): EmfPublisher | null {
+  return env[ECS_METADATA_ENV] ? createEmfPublisher(options) : null;
+}
+
+export function createEmfPublisher(options: EmfPublisherOptions): EmfPublisher {
+  const flushIntervalMs = options.flushIntervalMs ?? 60_000;
+  const maxSeries = options.maxSeries ?? 2_000;
+  const write = options.write ?? defaultWrite;
+  const now = options.now ?? Date.now;
+  let series = new Map<string, Series>();
+
+  const line = (entry: Series, timestamp: number): string => {
+    const { metric } = entry;
+    const dimensions = [
+      ['Service'],
+      ...(metric.dimensionSets ?? []).map((set) => ['Service', ...set]),
+    ];
+    let value: unknown;
+    if (metric.kind === 'sum') value = entry.sum;
+    else if (metric.kind === 'gauge') value = entry.last;
+    else {
+      const { values, counts } = boundedDistribution(entry.buckets);
+      value = {
+        Values: values,
+        Counts: counts,
+        Max: entry.max,
+        Min: entry.min,
+        Count: entry.count,
+        Sum: entry.sum,
+      };
+    }
+    return JSON.stringify({
+      _aws: {
+        Timestamp: timestamp,
+        CloudWatchMetrics: [
+          {
+            Namespace: options.namespace,
+            Dimensions: dimensions,
+            Metrics: [{ Name: metric.name, Unit: metric.unit }],
+          },
+        ],
+      },
+      ...entry.labels,
+      Service: options.service,
+      [metric.name]: value,
+    });
+  };
+
+  const flush = (): void => {
+    if (series.size === 0) return;
+    const current = series;
+    series = new Map();
+    const timestamp = now();
+    for (const entry of current.values()) {
+      try {
+        write(line(entry, timestamp));
+      } catch {
+        // Metrics are best effort; a failed write must never reach a request.
+      }
+    }
+  };
+
+  const timer = setInterval(flush, flushIntervalMs);
+  (timer as { unref?: () => void }).unref?.();
+
+  return {
+    record(metric, value, labels) {
+      if (!Number.isFinite(value)) return;
+      if (metric.kind !== 'gauge' && value < 0) return;
+      let clean = cleanLabels(metric, labels);
+      let key = seriesKey(metric, clean);
+      if (!series.has(key) && series.size >= maxSeries) {
+        clean = Object.fromEntries(Object.keys(clean).map((name) => [name, 'other']));
+        key = seriesKey(metric, clean);
+      }
+      let entry = series.get(key);
+      if (!entry) {
+        entry = {
+          metric,
+          labels: clean,
+          sum: 0,
+          last: 0,
+          count: 0,
+          min: Number.POSITIVE_INFINITY,
+          max: Number.NEGATIVE_INFINITY,
+          buckets: new Map(),
+        };
+        series.set(key, entry);
+      }
+      entry.sum += value;
+      entry.last = value;
+      entry.count += 1;
+      entry.min = Math.min(entry.min, value);
+      entry.max = Math.max(entry.max, value);
+      if (metric.kind === 'distribution') {
+        const bucket = bucketOf(value);
+        entry.buckets.set(bucket, (entry.buckets.get(bucket) ?? 0) + 1);
+      }
+    },
+    flush,
+    stop() {
+      clearInterval(timer);
+      flush();
+    },
+  };
+}

package/src/server.ts

@@ -1,16 +1,27 @@
-import type { ActivityAggregate, AnonymousActivityMetadata } from './index.js';
+import {
+  type ActivityAggregate,
+  type AnonymousActivityMetadata,
+  OXY_ACTIVITY_ID_HEADER,
+  OXY_EDGE_REGION_HEADER,
+} from './index.js';
 
 export const DEFAULT_PRESENCE_BUCKET_MS = 30_000;
+/** @deprecated Unused by any Oxy repo; `presenceKeys` already encodes the window. Removal is planned for the next major. */
 export const DEFAULT_ACTIVE_CLIENT_WINDOW_MS = 60_000;
 
 export type TelemetryHeaderValue = string | readonly string[] | undefined;
 export type TelemetryHeaders = Readonly<Record<string, TelemetryHeaderValue>>;
 
+/**
+ * @deprecated Unused by any Oxy repo (presence counting lives in the API). No
+ * replacement; removal is planned for the next major.
+ */
 export interface ActivityCardinalityAdapter {
   add(key: string, activityId: string, ttlSeconds: number): Promise<void>;
   count(keys: readonly string[]): Promise<number>;
 }
 
+/** @deprecated Unused by any Oxy repo; see `activityFlow`. */
 export interface ActivityFlow {
   sourceRegion?: string;
   service: string;
@@ -34,26 +45,47 @@ export function normalizeActivityId(value: TelemetryHeaderValue): string | undef
   return candidate && /^[a-z0-9_-]{16,64}$/i.test(candidate) ? candidate : undefined;
 }
 
+/**
+ * The collector's source region for a normalised edge PoP (`edge-<pop>`), the
+ * one derivation every reporter shares. `undefined` when there is no PoP.
+ */
+export function sourceRegionFromEdgePop(edgePop: string | undefined): string | undefined {
+  return edgePop ? `edge-${edgePop}` : undefined;
+}
+
 export function metadataFromHeaders(headers: TelemetryHeaders): AnonymousActivityMetadata {
-  const forwardedPop = normalizeEdgePop(headers['x-oxy-edge-region']);
+  const forwardedPop = normalizeEdgePop(headers[OXY_EDGE_REGION_HEADER.toLowerCase()]);
   const ray = firstHeaderValue(headers['cf-ray']);
   const rayPop = ray?.match(/-([a-z]{3})$/i)?.[1]?.toLowerCase();
-  const activityId = normalizeActivityId(headers['x-oxy-activity-id']);
+  const activityId = normalizeActivityId(headers[OXY_ACTIVITY_ID_HEADER.toLowerCase()]);
   return {
     ...(activityId ? { activityId } : {}),
     ...(forwardedPop || rayPop ? { edgePop: forwardedPop ?? rayPop } : {}),
   };
 }
 
+/**
+ * @deprecated Unused by any Oxy repo. For the bounded activity category of a
+ * path use `trafficType` from `@oxy.so/telemetry/collector`. Removal is planned
+ * for the next major.
+ */
 export function serviceFromPath(path: string): string {
   const segment = path.split('/').filter(Boolean)[0];
   return segment && /^[a-z][a-z0-9-]{0,31}$/i.test(segment) ? segment.toLowerCase() : 'platform';
 }
 
+/**
+ * @deprecated Unused by any Oxy repo; `createTrafficCollector` keys its own
+ * flows. Removal is planned for the next major.
+ */
 export function activityFlow(sourceRegion: string | undefined, service: string): ActivityFlow {
   return { sourceRegion, service, key: `${sourceRegion ?? ''}|${service}` };
 }
 
+/**
+ * @deprecated Unused outside `presenceKeys`; call `presenceKeys` for the
+ * current and previous bucket keys. Removal is planned for the next major.
+ */
 export function presenceBucket(observedAt: number, bucketMs = DEFAULT_PRESENCE_BUCKET_MS): number {
   if (!Number.isFinite(observedAt) || !Number.isFinite(bucketMs) || bucketMs <= 0) {
     throw new RangeError('observedAt and bucketMs must define a finite positive bucket');
@@ -73,4 +105,5 @@ export function presenceKeys(
   ];
 }
 
+/** @deprecated Unused by any Oxy repo; use `ActivityAggregate` from `@oxy.so/telemetry`. */
 export type ActivityBucket = ActivityAggregate;

package/src/socket.ts

@@ -1,5 +1,5 @@
 import { normalizeInfrastructureRegion, type TrafficFlow, type TrafficType } from './collector.js';
-import { metadataFromHeaders, type TelemetryHeaders } from './server.js';
+import { metadataFromHeaders, sourceRegionFromEdgePop, type TelemetryHeaders } from './server.js';
 
 export interface TrafficSocket {
   handshake: { headers: TelemetryHeaders };
@@ -63,9 +63,7 @@ export function observeTrafficSocket(
     const edgePop = metadataFromHeaders(socket.handshake.headers).edgePop;
     const peerRegion = peerService
       ? normalizeInfrastructureRegion(peer?.region)
-      : edgePop
-        ? `edge-${edgePop}`
-        : undefined;
+      : sourceRegionFromEdgePop(edgePop);
     collector.record({
       region,
       service,
@@ -125,9 +123,7 @@ export function observeTrafficWebSocket(
     const edgePop = metadataFromHeaders(options.headers ?? {}).edgePop;
     const peerRegion = peerService
       ? normalizeInfrastructureRegion(peer?.region)
-      : edgePop
-        ? `edge-${edgePop}`
-        : undefined;
+      : sourceRegionFromEdgePop(edgePop);
     collector.record({
       service,
       region,