@oxy.so/telemetry 1.2.0 → 2.1.0

package/src/browser.ts

@@ -38,7 +38,9 @@ export interface BrowserTelemetry {
   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();
 
@@ -51,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 {
@@ -67,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;
@@ -76,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;
@@ -96,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();
     }
@@ -110,7 +130,11 @@ export function createBrowserTelemetry(options: BrowserTelemetryOptions = {}): B
 
   const peekEdgeRegionHeader = (): Record<string, string> => {
     const now = (options.now ?? Date.now)();
-    if (!peekInFlight && (now < peekRefreshAt || now - peekRefreshAt >= (options.edgePeekRefreshMs ?? DEFAULT_EDGE_PEEK_REFRESH_MS))) {
+    if (
+      !peekInFlight &&
+      (now < peekRefreshAt ||
+        now - peekRefreshAt >= (options.edgePeekRefreshMs ?? DEFAULT_EDGE_PEEK_REFRESH_MS))
+    ) {
       peekRefreshAt = now;
       peekInFlight = true;
       void discoverEdgePop()
@@ -129,7 +153,7 @@ export function createBrowserTelemetry(options: BrowserTelemetryOptions = {}): B
     getEdgeRegionHeader,
     peekEdgeRegionHeader,
     async getHeaders(): Promise<Record<string, string>> {
-      return { ...await getEdgeRegionHeader(), ...getActivityIdHeader() };
+      return { ...(await getEdgeRegionHeader()), ...getActivityIdHeader() };
     },
   };
 }

package/src/collector.ts

@@ -21,11 +21,34 @@ export interface TrafficAggregate extends TrafficFlow {
 }
 
 const TYPES: Record<string, TrafficType> = {
-  auth: 'identity', session: 'identity', users: 'identity', profiles: 'identity', accounts: 'identity',
-  ai: 'ai', inference: 'ai', models: 'ai', chat: 'ai', completions: 'ai',
-  stream: 'media', tracks: 'media', episodes: 'media', recordings: 'media', rooms: 'media',
-  messages: 'communication', notifications: 'communication', mail: 'communication',
-  media: 'media', files: 'media', assets: 'media', upload: 'media', uploads: 'media', cdn: 'media', storage: 'media', images: 'media', audio: 'media', videos: 'media',
+  auth: 'identity',
+  session: 'identity',
+  users: 'identity',
+  profiles: 'identity',
+  accounts: 'identity',
+  ai: 'ai',
+  inference: 'ai',
+  models: 'ai',
+  chat: 'ai',
+  completions: 'ai',
+  stream: 'media',
+  tracks: 'media',
+  episodes: 'media',
+  recordings: 'media',
+  rooms: 'media',
+  messages: 'communication',
+  notifications: 'communication',
+  mail: 'communication',
+  media: 'media',
+  files: 'media',
+  assets: 'media',
+  upload: 'media',
+  uploads: 'media',
+  cdn: 'media',
+  storage: 'media',
+  images: 'media',
+  audio: 'media',
+  videos: 'media',
 };
 export function trafficType(path: string): TrafficType {
   const parts = path.split('?')[0].split('/').filter(Boolean);
@@ -35,7 +58,10 @@ export function trafficType(path: string): TrafficType {
   return TYPES[parts[0] ?? ''] ?? 'platform';
 }
 
-export function createTrafficCollector(publish: (events: TrafficAggregate[]) => Promise<unknown>, now = Date.now) {
+export function createTrafficCollector(
+  publish: (events: TrafficAggregate[]) => Promise<unknown>,
+  now = Date.now,
+) {
   const pending = new Map<string, { flow: TrafficFlow; requests: number; startedAt: number }>();
   let flushing: Promise<void> | null = null;
   return {
@@ -49,12 +75,22 @@ export function createTrafficCollector(publish: (events: TrafficAggregate[]) =>
       while (flushing) await flushing;
       if (pending.size === 0) return;
       const emittedAt = new Date(now()).toISOString();
-      const events = [...pending.values()].map(({ flow, requests, startedAt }) => ({ ...flow, requests, windowStartedAt: new Date(startedAt).toISOString(), emittedAt }));
+      const events = [...pending.values()].map(({ flow, requests, startedAt }) => ({
+        ...flow,
+        requests,
+        windowStartedAt: new Date(startedAt).toISOString(),
+        emittedAt,
+      }));
       pending.clear();
       flushing = (async () => {
-        for (let offset = 0; offset < events.length; offset += 256) await publish(events.slice(offset, offset + 256));
+        for (let offset = 0; offset < events.length; offset += 256)
+          await publish(events.slice(offset, offset + 256));
       })();
-      try { await flushing; } finally { flushing = null; }
+      try {
+        await flushing;
+      } finally {
+        flushing = null;
+      }
     },
   };
 }
@@ -65,7 +101,10 @@ interface HttpRequest {
   url?: string;
   serviceApp?: { appName?: string };
 }
-interface HttpResponse { once(event: string, listener: () => void): unknown; setHeader?(name: string, value: string): unknown }
+interface HttpResponse {
+  once(event: string, listener: () => void): unknown;
+  setHeader?(name: string, value: string): unknown;
+}
 
 export function trafficMiddleware(
   collector: Pick<ReturnType<typeof createTrafficCollector>, 'record'>,
@@ -76,24 +115,58 @@ export function trafficMiddleware(
     response.setHeader?.('X-Oxy-Region', 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/')) { next(); return; }
+    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/')
+    ) {
+      next();
+      return;
+    }
     const { edgePop } = metadataFromHeaders(request.headers);
     const activityType = trafficType(path);
     let finished = false;
     const inboundFlow = (): TrafficFlow => {
       // Read service identity AFTER the route's shared auth middleware resolved it.
-      const name = request.serviceApp?.appName?.toLowerCase().replace(/[^a-z0-9-]/g, '-').slice(0, 40);
+      const name = request.serviceApp?.appName
+        ?.toLowerCase()
+        .replace(/[^a-z0-9-]/g, '-')
+        .slice(0, 40);
       const internal = Boolean(name);
       const forwardedRegion = request.headers['x-oxy-source-region'];
-      const peerRegion = internal ? normalizeInfrastructureRegion(forwardedRegion) : edgePop ? `edge-${edgePop}` : undefined;
-      return { region, service, activityType, scope: internal ? 'internal' : 'external', direction: 'inbound', sourceRegion: peerRegion, targetRegion: region, sourceService: name, targetService: service };
+      const peerRegion = internal
+        ? normalizeInfrastructureRegion(forwardedRegion)
+        : edgePop
+          ? `edge-${edgePop}`
+          : undefined;
+      return {
+        region,
+        service,
+        activityType,
+        scope: internal ? 'internal' : 'external',
+        direction: 'inbound',
+        sourceRegion: peerRegion,
+        targetRegion: region,
+        sourceService: name,
+        targetService: service,
+      };
     };
     const finish = () => {
       if (finished) return;
       finished = true;
       const flow = inboundFlow();
       collector.record(flow);
-      collector.record({ ...flow, direction: 'outbound', sourceRegion: region, targetRegion: flow.sourceRegion, sourceService: service, targetService: flow.sourceService });
+      collector.record({
+        ...flow,
+        direction: 'outbound',
+        sourceRegion: region,
+        targetRegion: flow.sourceRegion,
+        sourceService: service,
+        targetService: flow.sourceService,
+      });
     };
     response.once('finish', finish);
     // Failed/aborted requests are still real inbound activity. Do not invent a
@@ -107,7 +180,10 @@ export function trafficMiddleware(
   };
 }
 
-export interface ServiceEndpoint { service: string; region: string }
+export interface ServiceEndpoint {
+  service: string;
+  region: string;
+}
 export function instrumentTrafficFetch(
   fetcher: typeof fetch,
   collector: Pick<ReturnType<typeof createTrafficCollector>, 'record'>,
@@ -116,23 +192,51 @@ export function instrumentTrafficFetch(
   resolveEndpoint: (url: URL) => ServiceEndpoint | undefined,
 ): typeof fetch {
   return Object.assign(async (input: RequestInfo | URL, init?: RequestInit) => {
-    const url = new URL(typeof input === 'string' ? input : input instanceof URL ? input.href : input.url);
+    const url = new URL(
+      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 (
+      url.pathname.startsWith('/internal/activity') ||
+      url.pathname.startsWith('/auth/service-token') ||
+      url.pathname === '/platform-infrastructure'
+    )
+      return fetcher(input, init);
     const peer = resolveEndpoint(url);
     const flow: TrafficFlow = {
-      service, region, scope: peer ? 'internal' : 'external', direction: 'outbound',
-      activityType: trafficType(url.pathname), sourceRegion: region, targetRegion: peer?.region,
-      sourceService: service, targetService: peer?.service,
+      service,
+      region,
+      scope: peer ? 'internal' : 'external',
+      direction: 'outbound',
+      activityType: trafficType(url.pathname),
+      sourceRegion: region,
+      targetRegion: peer?.region,
+      sourceService: service,
+      targetService: peer?.service,
     };
-    const headers = new Headers(init?.headers ?? (input instanceof Request ? input.headers : undefined));
+    const headers = new Headers(
+      init?.headers ?? (input instanceof Request ? input.headers : undefined),
+    );
     if (peer) headers.set('X-Oxy-Source-Region', region);
     let response: Response;
-    try { response = await fetcher(input, { ...init, headers }); }
-    catch (error) { collector.record({ ...flow, targetRegion: undefined }); throw error; }
-    const targetRegion = peer ? normalizeInfrastructureRegion(response.headers.get('X-Oxy-Region') ?? undefined) : undefined;
+    try {
+      response = await fetcher(input, { ...init, headers });
+    } catch (error) {
+      collector.record({ ...flow, targetRegion: undefined });
+      throw error;
+    }
+    const targetRegion = peer
+      ? normalizeInfrastructureRegion(response.headers.get('X-Oxy-Region') ?? undefined)
+      : undefined;
     collector.record({ ...flow, targetRegion });
-    collector.record({ ...flow, direction: 'inbound', sourceRegion: targetRegion, targetRegion: region, sourceService: peer?.service, targetService: service });
+    collector.record({
+      ...flow,
+      direction: 'inbound',
+      sourceRegion: targetRegion,
+      targetRegion: region,
+      sourceService: peer?.service,
+      targetService: service,
+    });
     return response;
   }, fetcher) as typeof fetch;
 }
@@ -140,14 +244,25 @@ export function instrumentTrafficFetch(
 // Exact deployed API hosts; an arbitrary caller-supplied hostname cannot claim
 // 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', 'api.alia.onl': 'alia', 'kaana.ai': 'kaana',
-  'api.homiio.com': 'homiio', 'api.syra.fm': 'syra',
-  'mention.earth': 'mention', 'mcp.mention.earth': 'mention-mcp',
-  'api.clarity.surf': 'clarity', 'api.peable.to': 'peable',
-  'api.crowdsource.oxy.so': 'crowdsource', 'api.moovo.now': 'moovo',
-  'api.allo.you': 'allo', 'api.noted.oxy.so': 'noted', 'api.schedio.app': 'schedio', 'api.tnp.network': 'tnp-api',
+  'api.oxy.so': 'oxy-api',
+  'api.website.oxy.so': 'website',
+  'website-api.oxy.so': 'website',
+  'api.mention.earth': 'mention',
+  'api.mercaria.co': 'mercaria',
+  'api.alia.onl': 'alia',
+  'kaana.ai': 'kaana',
+  'api.homiio.com': 'homiio',
+  'api.syra.fm': 'syra',
+  'mention.earth': 'mention',
+  'mcp.mention.earth': 'mention-mcp',
+  'api.clarity.surf': 'clarity',
+  'api.peable.to': 'peable',
+  'api.crowdsource.oxy.so': 'crowdsource',
+  'api.moovo.now': 'moovo',
+  'api.allo.you': 'allo',
+  'api.noted.oxy.so': 'noted',
+  'api.schedio.app': 'schedio',
+  'api.tnp.network': 'tnp-api',
 };
 export function resolveOxyServiceEndpoint(url: URL): ServiceEndpoint | undefined {
   const service = OXY_API_SERVICES[url.hostname];
@@ -185,7 +300,9 @@ const REGION_LOCATIONS: Record<string, { label: string; coordinates: [number, nu
   'me-central-1': { label: 'UAE', coordinates: [54.37, 24.45] },
   'il-central-1': { label: 'Tel Aviv', coordinates: [34.78, 32.09] },
 };
-export function infrastructureLocation(region: string) { return REGION_LOCATIONS[region]; }
+export function infrastructureLocation(region: string) {
+  return REGION_LOCATIONS[region];
+}
 
 export function normalizeInfrastructureRegion(value: unknown): string | undefined {
   return typeof value === 'string' && /^[a-z]{2}(?:-[a-z]+)+-\d$/.test(value) ? value : undefined;

package/src/metrics.ts

@@ -0,0 +1,286 @@
+/**
+ * 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`);
+}
+
+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

@@ -24,7 +24,9 @@ function firstHeaderValue(value: TelemetryHeaderValue): string | undefined {
 }
 
 export function normalizeEdgePop(value: TelemetryHeaderValue): string | undefined {
-  return firstHeaderValue(value)?.match(/^[a-z]{3}$/i)?.[0]?.toLowerCase();
+  return firstHeaderValue(value)
+    ?.match(/^[a-z]{3}$/i)?.[0]
+    ?.toLowerCase();
 }
 
 export function normalizeActivityId(value: TelemetryHeaderValue): string | undefined {
@@ -59,7 +61,11 @@ export function presenceBucket(observedAt: number, bucketMs = DEFAULT_PRESENCE_B
   return Math.floor(observedAt / bucketMs);
 }
 
-export function presenceKeys(sourceRegion: string, observedAt: number, bucketMs = DEFAULT_PRESENCE_BUCKET_MS): readonly [string, string] {
+export function presenceKeys(
+  sourceRegion: string,
+  observedAt: number,
+  bucketMs = DEFAULT_PRESENCE_BUCKET_MS,
+): readonly [string, string] {
   const current = presenceBucket(observedAt, bucketMs);
   return [
     `platform-activity:clients:${sourceRegion}:${current}`,