@oxy.so/telemetry 2.0.0 → 2.2.0

package/README.md

@@ -6,11 +6,13 @@ Redis, React, React Native or Expo.
 
 ## Entry points
 
-- `@oxy.so/telemetry` — shared header names and aggregate interfaces.
+- `@oxy.so/telemetry` — shared header names, the CORS header lists and the wire
+  types (`TrafficAggregate`, `ActivityAggregate`, `InfrastructureSnapshot`).
 - `@oxy.so/telemetry/browser` — ephemeral browser metadata.
 - `@oxy.so/telemetry/collector` — bounded HTTP/custom-transport flow aggregation.
 - `@oxy.so/telemetry/server` — pure validation, route bucketing and cardinality
   keys/interfaces.
+- `@oxy.so/telemetry/metrics` — operational metrics as CloudWatch EMF lines.
 
 Browser code must import the browser entry point explicitly. Server code must
 import the server entry point explicitly; the root entry point has no platform
@@ -19,12 +21,19 @@ side effects.
 ## Browser metadata
 
 ```ts
-import { getBrowserTelemetryHeaders } from '@oxy.so/telemetry/browser';
+import { getBrowserActivityIdHeader, peekBrowserEdgeRegionHeader } from '@oxy.so/telemetry/browser';
 
-const headers = await getBrowserTelemetryHeaders();
+const headers = { ...peekBrowserEdgeRegionHeader(), ...getBrowserActivityIdHeader() };
 await fetch('https://api.oxy.so/session/status', { headers });
 ```
 
+This is what `@oxy.so/core` sends on every request: the peek never waits on the
+trace. `getBrowserEdgeRegionHeader()` is the awaiting variant.
+
+A CORS allow-list for these headers is `OXY_TELEMETRY_REQUEST_HEADERS` (from the
+root entry), and `OXY_TELEMETRY_EXPOSED_HEADERS` for `Access-Control-Expose-Headers`;
+import them instead of repeating the header names.
+
 `X-Oxy-Activity-Id` is generated in memory for the current page runtime and
 rotates every five minutes. It is not placed in a cookie, local storage,
 session storage, IndexedDB or a URL. Closing or reloading the page loses it.
@@ -34,34 +43,32 @@ from the same-origin `/cdn-cgi/trace` endpoint. The helper reads no IP field and
 returns, logs and persists none of the rest of the trace response. Discovery is
 cached for 15 seconds per runtime (including failed discovery), has a one-second timeout and is disabled on loopback.
 
-Use `createBrowserTelemetry()` to create an isolated runtime or inject clock,
-crypto, location and trace-fetch dependencies in tests.
+`createBrowserTelemetry()` builds an isolated runtime with injected clock,
+crypto, location and trace-fetch dependencies; it is the test seam.
 
 ## Server primitives
 
 ```ts
 import {
-  activityFlow,
   metadataFromHeaders,
   presenceKeys,
-  serviceFromPath,
-  type ActivityCardinalityAdapter,
+  sourceRegionFromEdgePop,
 } from '@oxy.so/telemetry/server';
 
 const metadata = metadataFromHeaders(request.headers);
-const sourceRegion = metadata.edgePop ? `edge-${metadata.edgePop}` : undefined;
-const flow = activityFlow(sourceRegion, serviceFromPath(request.path));
+const sourceRegion = sourceRegionFromEdgePop(metadata.edgePop); // 'edge-mad' | undefined
 const keys = sourceRegion ? presenceKeys(sourceRegion, Date.now()) : [];
 ```
 
 Validation accepts a three-letter PoP and a 16–64 character opaque activity ID.
-It ignores IP and forwarding headers. `serviceFromPath` keeps only a bounded,
-static first route segment, so IDs and full paths cannot enter aggregates.
-
-`ActivityCardinalityAdapter` describes the minimal storage boundary for an
-implementation such as Redis HyperLogLog. This package does not instantiate a
+It ignores IP and forwarding headers. This package does not instantiate a
 store, keep server-global maps, start timers or send realtime events.
 
+`serviceFromPath`, `activityFlow`, `presenceBucket`, `ActivityCardinalityAdapter`,
+`ActivityBucket`, `DEFAULT_ACTIVE_CLIENT_WINDOW_MS`, `getBrowserTelemetryHeaders`
+and `createBrowserTelemetry` are deprecated: nothing in Oxy uses them and they go in
+the next major.
+
 ## Active-client definition
 
 An active client is one distinct ephemeral activity ID observed for an edge PoP
@@ -105,8 +112,10 @@ follow the actual movement, even when two services share one region.
 identity after route authentication. `instrumentTrafficFetch` observes actual
 outbound calls; internal destination regions come from the peer's `X-Oxy-Region`
 response, not a guessed IP location. Unlocated peers remain unlocated. Health,
-telemetry collection, infrastructure snapshots and service-token minting are
-excluded from observation where applicable to prevent control traffic feedback.
+telemetry collection, infrastructure snapshots, service-token minting and
+`/cdn-cgi/` are excluded from observation to prevent control traffic feedback;
+`isObservedPath(path, direction)` (reading the `UNOBSERVED_PATHS` table) is the one predicate, so an adapter that does its own
+interception imports it instead of copying a pattern.
 Custom transports can call the collector's `record` method explicitly.
 
 Each collector retains at most 512 distinct pending flows and publishes chunks
@@ -115,7 +124,8 @@ durable retry queue. These are live operational observations, not billing or
 lossless historical request totals. No dashboard viewer is needed to collect.
 
 Realtime transport publishes aggregate buckets, not individual metadata. A
-socket event may carry `ActivityAggregate`: request count, approximate active
+socket event carries `ActivityAggregate` (a `TrafficAggregate` plus
+`activeClients`; the infrastructure snapshot is `InfrastructureSnapshot`): request count, approximate active
 clients, source/target regions, service and window timestamps. Transport and
 fan-out are application concerns and intentionally absent from this package.
 
@@ -130,11 +140,65 @@ installed in each service before this can represent the whole ecosystem.
 The authenticated publisher is `createEcosystemTraffic` from `@oxy.so/core/server`.
 It exposes HTTP middleware, `wrapFetch`, `record` for explicit transport events,
 and `stop` for graceful removal. It requires a known infrastructure region (or
-explicit infrastructure coordinates) and one of three ways to authenticate: an
-`OXY_ACTIVITY_API_KEY`/`OXY_ACTIVITY_API_SECRET` pair, an
-`OXY_SERVICE_API_KEY`/`OXY_SERVICE_API_SECRET` pair, or no credential at all
-where the process can attest its workload identity (ADR 0026). Credentials, user
-metadata and paths never enter public snapshots.
+explicit infrastructure coordinates) and registered temporary workload identity
+for own service publication ([ADR 0049](../../docs/adr/0049-first-party-platform-authority.md)).
+The shared OxyServer performs attestation and live binding checks. A process can
+supply `workloadCredentials` from `createAwsWorkloadCredentialProvider()`
+(`@oxy.so/core/server/aws`) for the supported temporary AWS provider chain.
+There is no activity-key or service-key fallback for own publication. External
+customer API credentials remain separate and do not become first-party authority.
+Credentials, user metadata and paths never enter public snapshots. Activity's
+internal/external `scope` field classifies traffic; it is not an OAuth permission.
+
+## Operational metrics (CloudWatch EMF)
+
+```ts
+import { createEmfPublisher, HTTP_REQUEST_LATENCY, statusClass } from '@oxy.so/telemetry/metrics';
+
+const metrics = createEmfPublisher({ namespace: 'Oxy/Api', service: 'oxy-api' });
+metrics.record(HTTP_REQUEST_LATENCY, elapsedMs, {
+  Route: '/users/:id', // a log property: free, grouped in Logs Insights
+  StatusClass: statusClass(res.statusCode), // a dimension: billed per value
+  Caller: 'anonymous',
+});
+// On shutdown:
+metrics.stop();
+```
+
+Observations are aggregated in memory and written once per interval (60 s) as
+one stdout line per (metric, label set). On ECS with the `awslogs` driver,
+CloudWatch Logs extracts the metrics itself: no agent, sidecar or IAM grant.
+A `distribution` keeps a ~5 % bucketed histogram, so CloudWatch answers
+SampleCount (the count) and percentiles for it.
+
+Every distinct combination of DIMENSION values is a billed custom metric, so a
+label is a dimension only when the definition lists it in `dimensionSets`, and
+only closed, small sets belong there (status class, a first-party caller).
+Route, method, table and every other label stay plain properties on the line:
+`stats sum(RequestLatency.Count) by Route` in Logs Insights. At most
+`maxSeries` (default 2000) series are held per interval; past that, new series
+fold into one whose labels read `other`.
+
+On ECS only, `createEmfPublisherIfDeployed(options)` returns the same publisher
+and `null` elsewhere (it checks `ECS_CONTAINER_METADATA_URI_V4`), so a service
+does not repeat that gate.
+
+### Conformance fixture
+
+`fixtures/emf-golden.json` is the cross-language contract for the EMF line format.
+Each case holds a metric `definition`, `service`, `namespace`, a fixed `now`
+(the line's `Timestamp`), optional `maxSeries`, the `observations`
+(`{labels, value}`; the strings `"NaN"`, `"Infinity"` and `"-Infinity"` stand for
+the non-finite numbers JSON cannot carry) and the `expectedLines` the publisher
+must write on flush, in series first-seen order. Lines are compared as parsed
+JSON, not as bytes. `src/__tests__/emfGolden.test.ts` runs every case through the
+real publisher.
+
+Kaana's Go `internal/emf` must consume the same file (a vendored copy that a
+Kaana test keeps byte-identical to this one) and pass every case; change the
+fixture here first. Label values are truncated by UTF-16 code units, so a Go
+implementation counts UTF-16 units, not bytes or runes. The fixture avoids a cut
+inside a surrogate pair, whose result is a lone surrogate that UTF-8 cannot carry.
 
 ## Development
 

package/dist/cjs/browser.js

@@ -30,6 +30,12 @@ function eligibleLocation(location) {
         location.hostname !== '127.0.0.1' &&
         location.hostname !== '[::1]');
 }
+/**
+ * @deprecated No Oxy repo constructs its own runtime: use the module-level
+ * `getBrowserActivityIdHeader`, `getBrowserEdgeRegionHeader` and
+ * `peekBrowserEdgeRegionHeader`. The factory remains the test seam. Removal from
+ * the public surface is planned for the next major.
+ */
 function createBrowserTelemetry(options = {}) {
     let activityId = null;
     let activityIdCreatedAt = 0;
@@ -125,5 +131,10 @@ const getBrowserEdgeRegionHeader = () => defaultBrowserTelemetry.getEdgeRegionHe
 exports.getBrowserEdgeRegionHeader = getBrowserEdgeRegionHeader;
 const peekBrowserEdgeRegionHeader = () => defaultBrowserTelemetry.peekEdgeRegionHeader();
 exports.peekBrowserEdgeRegionHeader = peekBrowserEdgeRegionHeader;
+/**
+ * @deprecated Unused by any Oxy repo. `@oxy.so/core` sends
+ * `peekBrowserEdgeRegionHeader()` and `getBrowserActivityIdHeader()` per request.
+ * Removal is planned for the next major.
+ */
 const getBrowserTelemetryHeaders = () => defaultBrowserTelemetry.getHeaders();
 exports.getBrowserTelemetryHeaders = getBrowserTelemetryHeaders;

package/dist/cjs/collector.js

@@ -1,12 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.UNOBSERVED_PATHS = void 0;
 exports.trafficType = trafficType;
+exports.isObservedPath = isObservedPath;
 exports.createTrafficCollector = createTrafficCollector;
 exports.trafficMiddleware = trafficMiddleware;
 exports.instrumentTrafficFetch = instrumentTrafficFetch;
 exports.resolveOxyServiceEndpoint = resolveOxyServiceEndpoint;
 exports.infrastructureLocation = infrastructureLocation;
 exports.normalizeInfrastructureRegion = normalizeInfrastructureRegion;
+const index_js_1 = require("./index.js");
 const server_js_1 = require("./server.js");
 const TYPES = {
     auth: 'identity',
@@ -48,6 +51,35 @@ function trafficType(path) {
         parts.shift();
     return TYPES[parts[0] ?? ''] ?? 'platform';
 }
+/**
+ * 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.
+ */
+exports.UNOBSERVED_PATHS = [
+    {
+        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.
+ */
+function isObservedPath(path, direction) {
+    return !exports.UNOBSERVED_PATHS.some((entry) => (entry.directions === 'both' || entry.directions === direction) && entry.matches(path));
+}
 function createTrafficCollector(publish, now = Date.now) {
     const pending = new Map();
     let flushing = null;
@@ -88,13 +120,10 @@ function createTrafficCollector(publish, now = Date.now) {
 }
 function trafficMiddleware(collector, service, region) {
     return (request, response, next) => {
-        response.setHeader?.('X-Oxy-Region', region);
+        response.setHeader?.(index_js_1.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;
         }
@@ -108,12 +137,10 @@ function trafficMiddleware(collector, service, region) {
                 .replace(/[^a-z0-9-]/g, '-')
                 .slice(0, 40);
             const internal = Boolean(name);
-            const forwardedRegion = request.headers['x-oxy-source-region'];
+            const forwardedRegion = request.headers[index_js_1.OXY_SOURCE_REGION_HEADER.toLowerCase()];
             const peerRegion = internal
                 ? normalizeInfrastructureRegion(forwardedRegion)
-                : edgePop
-                    ? `edge-${edgePop}`
-                    : undefined;
+                : (0, server_js_1.sourceRegionFromEdgePop)(edgePop);
             return {
                 region,
                 service,
@@ -157,9 +184,7 @@ function instrumentTrafficFetch(fetcher, collector, service, region, resolveEndp
     return Object.assign(async (input, init) => {
         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')
+        if (!isObservedPath(url.pathname, 'outbound'))
             return fetcher(input, init);
         const peer = resolveEndpoint(url);
         const flow = {
@@ -175,7 +200,7 @@ function instrumentTrafficFetch(fetcher, collector, service, region, resolveEndp
         };
         const headers = new Headers(init?.headers ?? (input instanceof Request ? input.headers : undefined));
         if (peer)
-            headers.set('X-Oxy-Source-Region', region);
+            headers.set(index_js_1.OXY_SOURCE_REGION_HEADER, region);
         let response;
         try {
             response = await fetcher(input, { ...init, headers });
@@ -185,7 +210,7 @@ function instrumentTrafficFetch(fetcher, collector, service, region, resolveEndp
             throw error;
         }
         const targetRegion = peer
-            ? normalizeInfrastructureRegion(response.headers.get('X-Oxy-Region') ?? undefined)
+            ? normalizeInfrastructureRegion(response.headers.get(index_js_1.OXY_REGION_HEADER) ?? undefined)
             : undefined;
         collector.record({ ...flow, targetRegion });
         collector.record({
@@ -203,11 +228,12 @@ function instrumentTrafficFetch(fetcher, collector, service, region, resolveEndp
 // to be an internal service. Region is infrastructure metadata, never IP geo.
 const OXY_API_SERVICES = {
     '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/dist/cjs/index.js

@@ -1,5 +1,26 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.OXY_EDGE_REGION_HEADER = exports.OXY_ACTIVITY_ID_HEADER = void 0;
+exports.OXY_TELEMETRY_EXPOSED_HEADERS = exports.OXY_TELEMETRY_REQUEST_HEADERS = exports.OXY_SOURCE_REGION_HEADER = exports.OXY_REGION_HEADER = exports.OXY_EDGE_REGION_HEADER = exports.OXY_ACTIVITY_ID_HEADER = void 0;
+/** Request header a browser sends: the ephemeral anonymous activity ID. */
 exports.OXY_ACTIVITY_ID_HEADER = 'X-Oxy-Activity-Id';
+/** Request header a browser sends: the three-letter Cloudflare PoP code. */
 exports.OXY_EDGE_REGION_HEADER = 'X-Oxy-Edge-Region';
+/** Response header a reporting service sets: the region that processed the request. */
+exports.OXY_REGION_HEADER = 'X-Oxy-Region';
+/** Request header one Oxy service sends another: the caller's infrastructure region. */
+exports.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.
+ */
+exports.OXY_TELEMETRY_REQUEST_HEADERS = Object.freeze([
+    exports.OXY_ACTIVITY_ID_HEADER,
+    exports.OXY_EDGE_REGION_HEADER,
+]);
+/**
+ * Response headers a browser client may need to read
+ * (`Access-Control-Expose-Headers`).
+ */
+exports.OXY_TELEMETRY_EXPOSED_HEADERS = Object.freeze([exports.OXY_REGION_HEADER]);

package/dist/cjs/metrics.js

@@ -0,0 +1,218 @@
+"use strict";
+/**
+ * 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`).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HTTP_RATE_LIMITED = exports.HTTP_REQUEST_LATENCY = void 0;
+exports.statusClass = statusClass;
+exports.createEmfPublisherIfDeployed = createEmfPublisherIfDeployed;
+exports.createEmfPublisher = createEmfPublisher;
+/** One HTTP request: SampleCount is the request count, percentiles the latency. */
+exports.HTTP_REQUEST_LATENCY = {
+    name: 'RequestLatency',
+    unit: 'Milliseconds',
+    kind: 'distribution',
+    dimensionSets: [['StatusClass'], ['Caller']],
+};
+/** One request a rate limiter refused (429), per calling application. */
+exports.HTTP_RATE_LIMITED = {
+    name: 'RateLimited',
+    unit: 'Count',
+    kind: 'sum',
+    dimensionSets: [['Caller']],
+};
+/** `2xx`, `4xx`, … — a closed set, safe as a dimension. */
+function statusClass(status) {
+    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']);
+/** Representative value of a bucket: values within ~5 % collapse together. */
+function bucketOf(value) {
+    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) {
+    let entries = [...buckets.entries()].sort(([left], [right]) => left - right);
+    while (entries.length > MAX_DISTRIBUTION_VALUES) {
+        const merged = [];
+        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, labels) {
+    const clean = {};
+    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] ?? (clean[name] = 'unknown');
+    }
+    return clean;
+}
+function seriesKey(metric, labels) {
+    const pairs = Object.keys(labels)
+        .sort()
+        .map((name) => `${name}=${labels[name]}`);
+    return `${metric.name}\u0000${pairs.join('\u0000')}`;
+}
+/** One line on stdout. Reached through `globalThis`: this package carries no Node types. */
+function defaultWrite(line) {
+    globalThis.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.
+ */
+function createEmfPublisherIfDeployed(options, env = globalThis.process?.env ?? {}) {
+    return env[ECS_METADATA_ENV] ? createEmfPublisher(options) : null;
+}
+function createEmfPublisher(options) {
+    const flushIntervalMs = options.flushIntervalMs ?? 60000;
+    const maxSeries = options.maxSeries ?? 2000;
+    const write = options.write ?? defaultWrite;
+    const now = options.now ?? Date.now;
+    let series = new Map();
+    const line = (entry, timestamp) => {
+        const { metric } = entry;
+        const dimensions = [
+            ['Service'],
+            ...(metric.dimensionSets ?? []).map((set) => ['Service', ...set]),
+        ];
+        let value;
+        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 = () => {
+        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.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/dist/cjs/server.js

@@ -3,12 +3,15 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.DEFAULT_ACTIVE_CLIENT_WINDOW_MS = exports.DEFAULT_PRESENCE_BUCKET_MS = void 0;
 exports.normalizeEdgePop = normalizeEdgePop;
 exports.normalizeActivityId = normalizeActivityId;
+exports.sourceRegionFromEdgePop = sourceRegionFromEdgePop;
 exports.metadataFromHeaders = metadataFromHeaders;
 exports.serviceFromPath = serviceFromPath;
 exports.activityFlow = activityFlow;
 exports.presenceBucket = presenceBucket;
 exports.presenceKeys = presenceKeys;
+const index_js_1 = require("./index.js");
 exports.DEFAULT_PRESENCE_BUCKET_MS = 30000;
+/** @deprecated Unused by any Oxy repo; `presenceKeys` already encodes the window. Removal is planned for the next major. */
 exports.DEFAULT_ACTIVE_CLIENT_WINDOW_MS = 60000;
 function firstHeaderValue(value) {
     if (typeof value === 'string')
@@ -25,23 +28,43 @@ function normalizeActivityId(value) {
     const candidate = firstHeaderValue(value);
     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.
+ */
+function sourceRegionFromEdgePop(edgePop) {
+    return edgePop ? `edge-${edgePop}` : undefined;
+}
 function metadataFromHeaders(headers) {
-    const forwardedPop = normalizeEdgePop(headers['x-oxy-edge-region']);
+    const forwardedPop = normalizeEdgePop(headers[index_js_1.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[index_js_1.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.
+ */
 function serviceFromPath(path) {
     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.
+ */
 function activityFlow(sourceRegion, service) {
     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.
+ */
 function presenceBucket(observedAt, bucketMs = exports.DEFAULT_PRESENCE_BUCKET_MS) {
     if (!Number.isFinite(observedAt) || !Number.isFinite(bucketMs) || bucketMs <= 0) {
         throw new RangeError('observedAt and bucketMs must define a finite positive bucket');

package/dist/cjs/socket.js

@@ -49,9 +49,7 @@ function observeTrafficSocket(socket, collector, service, region, options = {})
         const edgePop = (0, server_js_1.metadataFromHeaders)(socket.handshake.headers).edgePop;
         const peerRegion = peerService
             ? (0, collector_js_1.normalizeInfrastructureRegion)(peer?.region)
-            : edgePop
-                ? `edge-${edgePop}`
-                : undefined;
+            : (0, server_js_1.sourceRegionFromEdgePop)(edgePop);
         collector.record({
             region,
             service,
@@ -90,9 +88,7 @@ function observeTrafficWebSocket(socket, collector, service, region, options = {
         const edgePop = (0, server_js_1.metadataFromHeaders)(options.headers ?? {}).edgePop;
         const peerRegion = peerService
             ? (0, collector_js_1.normalizeInfrastructureRegion)(peer?.region)
-            : edgePop
-                ? `edge-${edgePop}`
-                : undefined;
+            : (0, server_js_1.sourceRegionFromEdgePop)(edgePop);
         collector.record({
             service,
             region,