@oxy.so/telemetry 1.2.0 → 2.1.0

package/dist/esm/browser.js

@@ -22,9 +22,9 @@ function createUuid(cryptoApi) {
 function eligibleLocation(location) {
     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 = {}) {
     let activityId = null;
@@ -37,7 +37,9 @@ export function createBrowserTelemetry(options = {}) {
         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 {};
@@ -54,7 +56,11 @@ export function createBrowserTelemetry(options = {}) {
         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);
@@ -69,7 +75,9 @@ export function createBrowserTelemetry(options = {}) {
     };
     const getEdgeRegionHeader = async () => {
         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();
         }
@@ -81,7 +89,9 @@ export function createBrowserTelemetry(options = {}) {
     let peekInFlight = false;
     const peekEdgeRegionHeader = () => {
         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()
@@ -100,7 +110,7 @@ export function createBrowserTelemetry(options = {}) {
         getEdgeRegionHeader,
         peekEdgeRegionHeader,
         async getHeaders() {
-            return { ...await getEdgeRegionHeader(), ...getActivityIdHeader() };
+            return { ...(await getEdgeRegionHeader()), ...getActivityIdHeader() };
         },
     };
 }

package/dist/esm/collector.js

@@ -1,10 +1,33 @@
 import { metadataFromHeaders } from './server.js';
 const TYPES = {
-    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) {
     const parts = path.split('?')[0].split('/').filter(Boolean);
@@ -34,7 +57,12 @@ export function createTrafficCollector(publish, now = Date.now) {
             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)
@@ -54,7 +82,10 @@ export function trafficMiddleware(collector, service, region) {
         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/')) {
+        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;
         }
@@ -63,11 +94,28 @@ export function trafficMiddleware(collector, service, region) {
         let finished = false;
         const inboundFlow = () => {
             // 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)
@@ -75,7 +123,14 @@ export function trafficMiddleware(collector, service, region) {
             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
@@ -93,13 +148,21 @@ export function instrumentTrafficFetch(fetcher, collector, service, region, reso
     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 (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 = {
-            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));
         if (peer)
@@ -112,23 +175,43 @@ export function instrumentTrafficFetch(fetcher, collector, service, region, reso
             collector.record({ ...flow, targetRegion: undefined });
             throw error;
         }
-        const targetRegion = peer ? normalizeInfrastructureRegion(response.headers.get('X-Oxy-Region') ?? undefined) : undefined;
+        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);
 }
 // 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 = {
-    '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) {
     const service = OXY_API_SERVICES[url.hostname];
@@ -165,7 +248,9 @@ const REGION_LOCATIONS = {
     '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) { return REGION_LOCATIONS[region]; }
+export function infrastructureLocation(region) {
+    return REGION_LOCATIONS[region];
+}
 export function normalizeInfrastructureRegion(value) {
     return typeof value === 'string' && /^[a-z]{2}(?:-[a-z]+)+-\d$/.test(value) ? value : undefined;
 }

package/dist/esm/metrics.js

@@ -0,0 +1,203 @@
+/**
+ * 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`).
+ */
+/** One HTTP request: SampleCount is the request count, percentiles the latency. */
+export const HTTP_REQUEST_LATENCY = {
+    name: 'RequestLatency',
+    unit: 'Milliseconds',
+    kind: 'distribution',
+    dimensionSets: [['StatusClass'], ['Caller']],
+};
+/** One request a rate limiter refused (429), per calling application. */
+export const HTTP_RATE_LIMITED = {
+    name: 'RateLimited',
+    unit: 'Count',
+    kind: 'sum',
+    dimensionSets: [['Caller']],
+};
+/** `2xx`, `4xx`, … — a closed set, safe as a dimension. */
+export 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`);
+}
+export 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/esm/server.js

@@ -7,7 +7,9 @@ function firstHeaderValue(value) {
     return typeof first === 'string' ? first : undefined;
 }
 export function normalizeEdgePop(value) {
-    return firstHeaderValue(value)?.match(/^[a-z]{3}$/i)?.[0]?.toLowerCase();
+    return firstHeaderValue(value)
+        ?.match(/^[a-z]{3}$/i)?.[0]
+        ?.toLowerCase();
 }
 export function normalizeActivityId(value) {
     const candidate = firstHeaderValue(value);

package/dist/esm/socket.js

@@ -1,11 +1,26 @@
 import { normalizeInfrastructureRegion } from './collector.js';
 import { metadataFromHeaders } from './server.js';
 const CATEGORIES = {
-    auth: 'identity', session: 'identity', user: 'identity', profile: 'identity',
-    chat: 'ai', agent: 'ai', inference: 'ai', completion: 'ai',
-    message: 'communication', notification: 'communication', typing: 'communication',
-    media: 'media', audio: 'media', video: 'media', stream: 'media', player: 'media',
-    track: 'media', playback: 'media', playlist: 'media', room: 'media',
+    auth: 'identity',
+    session: 'identity',
+    user: 'identity',
+    profile: 'identity',
+    chat: 'ai',
+    agent: 'ai',
+    inference: 'ai',
+    completion: 'ai',
+    message: 'communication',
+    notification: 'communication',
+    typing: 'communication',
+    media: 'media',
+    audio: 'media',
+    video: 'media',
+    stream: 'media',
+    player: 'media',
+    track: 'media',
+    playback: 'media',
+    playlist: 'media',
+    room: 'media',
 };
 /** Event names are reduced locally to five categories; payloads are never read. */
 export function socketTrafficType(event) {
@@ -27,9 +42,16 @@ export function observeTrafficSocket(socket, collector, service, region, options
         const peer = options.getPeer?.();
         const peerService = peer && /^[a-z][a-z0-9-]{0,39}$/.test(peer.service) ? peer.service : undefined;
         const edgePop = metadataFromHeaders(socket.handshake.headers).edgePop;
-        const peerRegion = peerService ? normalizeInfrastructureRegion(peer?.region) : edgePop ? `edge-${edgePop}` : undefined;
+        const peerRegion = peerService
+            ? normalizeInfrastructureRegion(peer?.region)
+            : edgePop
+                ? `edge-${edgePop}`
+                : undefined;
         collector.record({
-            region, service, scope: peerService ? 'internal' : 'external', direction,
+            region,
+            service,
+            scope: peerService ? 'internal' : 'external',
+            direction,
             activityType: socketTrafficType(event),
             sourceRegion: direction === 'inbound' ? peerRegion : region,
             targetRegion: direction === 'inbound' ? region : peerRegion,
@@ -61,9 +83,16 @@ export function observeTrafficWebSocket(socket, collector, service, region, opti
         const peer = options.getPeer?.();
         const peerService = peer && /^[a-z][a-z0-9-]{0,39}$/.test(peer.service) ? peer.service : undefined;
         const edgePop = metadataFromHeaders(options.headers ?? {}).edgePop;
-        const peerRegion = peerService ? normalizeInfrastructureRegion(peer?.region) : edgePop ? `edge-${edgePop}` : undefined;
+        const peerRegion = peerService
+            ? normalizeInfrastructureRegion(peer?.region)
+            : edgePop
+                ? `edge-${edgePop}`
+                : undefined;
         collector.record({
-            service, region, scope: peerService ? 'internal' : 'external', direction,
+            service,
+            region,
+            scope: peerService ? 'internal' : 'external',
+            direction,
             activityType: options.activityType ?? 'communication',
             sourceRegion: direction === 'inbound' ? peerRegion : region,
             targetRegion: direction === 'inbound' ? region : peerRegion,

package/dist/types/metrics.d.ts

@@ -0,0 +1,79 @@
+/**
+ * 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 declare const HTTP_REQUEST_LATENCY: MetricDefinition;
+/** One request a rate limiter refused (429), per calling application. */
+export declare const HTTP_RATE_LIMITED: MetricDefinition;
+/** `2xx`, `4xx`, … — a closed set, safe as a dimension. */
+export declare function statusClass(status: number): string;
+export declare function createEmfPublisher(options: EmfPublisherOptions): EmfPublisher;

package/dist/types/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}