@earendil-works/chord 1.4.0 → 1.5.1

package/dist/telemetry-ingest/batch.d.ts

@@ -0,0 +1,70 @@
+import type { StoredMetric, StoredSpan } from "@earendil-works/pi-telemetry";
+import { type Schema } from "../contracts/index.ts";
+/** At most this many spans in a page's batch. */
+export declare const PAGE_BATCH_SPANS = 100;
+/** At most this many spans and metric rows in a worker's batch. */
+export declare const WORKER_BATCH_ROWS = 1000;
+/** A page's batch (spans only: a page sends no metrics). */
+export declare const PageBatch: Schema<{
+    spans: StoredSpan[];
+}>;
+/** A worker's batch: its spans and its metric rows. */
+export declare const WorkerBatch: Schema<{
+    spans: StoredSpan[];
+    metrics: StoredMetric[];
+}>;
+/** The server's telemetry object for pages: any principal's page sends its batches to it, untrusted. */
+export declare const PageTelemetry: import("../contracts/contract.ts").Contract<{
+    kind: "remote";
+    name: "chord.telemetry.page";
+    params: {};
+    history: [{
+        version: "1";
+        variants: {
+            readonly main: {
+                state: Record<never, never>;
+                methods: {
+                    readonly ingest: import("../contracts/schema.ts").Method<Schema<{
+                        spans: StoredSpan[];
+                    }>, Schema<{
+                        written: number;
+                        dropped: number;
+                    }>>;
+                };
+            };
+        };
+        changes: never;
+    }];
+}>;
+/**
+ * The server's telemetry object for workers: `worker` for a worker's principal (its batches written as they are),
+ * `other` for everyone else (nothing to call).
+ */
+export declare const WorkerTelemetry: import("../contracts/contract.ts").Contract<{
+    kind: "remote";
+    name: "chord.telemetry.worker";
+    params: {};
+    history: [{
+        version: "1";
+        variants: {
+            readonly worker: {
+                state: Record<never, never>;
+                methods: {
+                    readonly ingest: import("../contracts/schema.ts").Method<Schema<{
+                        spans: StoredSpan[];
+                        metrics: StoredMetric[];
+                    }>, Schema<{
+                        written: number;
+                        dropped: number;
+                    }>>;
+                };
+            };
+            readonly other: {
+                state: Record<never, never>;
+                methods: Record<never, never>;
+            };
+        };
+        changes: never;
+    }];
+}>;
+//# sourceMappingURL=batch.d.ts.map

package/dist/telemetry-ingest/batch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"batch.d.ts","sourceRoot":"","sources":["../../src/telemetry-ingest/batch.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAkB,YAAY,EAAE,UAAU,EAAE,MAAM,8BAA8B,CAAC;AAC7F,OAAO,EAA0D,KAAK,MAAM,EAAc,MAAM,uBAAuB,CAAC;AAExH,iDAAiD;AACjD,eAAO,MAAM,gBAAgB,MAAM,CAAC;AAEpC,mEAAmE;AACnE,eAAO,MAAM,iBAAiB,OAAO,CAAC;AA8FtC,4DAA4D;AAC5D,eAAO,MAAM,SAAS;;EAA4D,CAAC;AAEnF,uDAAuD;AACvD,eAAO,MAAM,WAAW;;;EAGtB,CAAC;AAKH,wGAAwG;AACxG,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;EAKxB,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;EAK1B,CAAC"}

package/dist/telemetry-ingest/batch.js

@@ -0,0 +1,110 @@
+// What pages and workers send the server's telemetry objects (decisions "Telemetry from browser pages", "The server is
+// the one place telemetry is stored"): a batch of finished spans (a worker's with its metric aggregates), its schemas
+// (a page's strict: every field bounded, ids printable ASCII, no control characters; a worker's, the server's own
+// child, generous), and the two remote objects on the server that take them, `PageTelemetry` and `WorkerTelemetry`.
+import { arr, hostKind, int, lit, method, num, obj, opt, remote, str, union } from "../contracts/index.js";
+/** At most this many spans in a page's batch. */
+export const PAGE_BATCH_SPANS = 100;
+/** At most this many spans and metric rows in a worker's batch. */
+export const WORKER_BATCH_ROWS = 1000;
+/** An id: printable ASCII, no spaces (a page's are `browser:<incarnation>:<n>`). */
+function id(max) {
+    return str({ min: 1, max, pattern: "^[\\x21-\\x7e]+$" });
+}
+/** Text: no control characters (C0, DEL, C1), at most `max` characters. */
+function text(max, min = 0) {
+    return str({ min, max, pattern: "^[^\\u0000-\\u001f\\u007f-\\u009f]*$" });
+}
+/** A record of attributes: at most `count` keys of 1 to 64 characters of text (other keys refused), values of `value`. */
+function attributes(count, value) {
+    return {
+        type: "object",
+        maxProperties: count,
+        patternProperties: { "^[^\\u0000-\\u001f\\u007f-\\u009f]{1,64}$": value },
+        additionalProperties: false,
+    };
+}
+/** A finished span as `span`'s fields allow: ids, a name, times, attributes, events, links and a status. */
+function spanSchema(limits) {
+    const record = attributes(limits.attributes, limits.value);
+    const span = obj({
+        id: id(limits.id),
+        traceId: id(limits.id),
+        parentId: opt(id(limits.id)),
+        name: text(limits.name, 1),
+        startedMs: num({ min: 0 }),
+        endedMs: num({ min: 0 }),
+        attributes: record,
+        events: arr(obj({ name: text(limits.name, 1), timeMs: num({ min: 0 }), attributes: record }), {
+            max: limits.events,
+        }),
+        links: arr(obj({ traceId: id(limits.id), spanId: id(limits.id), attributes: opt(record) }), {
+            max: limits.links,
+        }),
+        status: union([
+            obj({ status: lit("ok") }),
+            obj({ status: lit("error"), error: opt(obj({ name: text(64), message: text(500) })) }),
+        ]),
+    });
+    // The object schema's static type is StoredSpan's shape: the same fields, optional ones `opt`.
+    return span;
+}
+/** A page's spans: what a recorded click needs, little more (decision "Telemetry from browser pages"). */
+const PAGE_SPAN = spanSchema({
+    id: 128,
+    name: 128,
+    attributes: 32,
+    value: union([text(256), num(), { type: "boolean" }]),
+    events: 16,
+    links: 8,
+});
+/** A worker's spans: bounded generously (its spans are Chord's and its plugins'). */
+const WORKER_SPAN = spanSchema({
+    id: 256,
+    name: 1024,
+    attributes: 256,
+    value: union([str({ max: 65_536 }), num(), { type: "boolean" }, arr(union([str(), num()]))]),
+    events: 1024,
+    links: 256,
+});
+/** A worker's metric row: one series' aggregate of one 10 s interval. */
+const METRIC = obj({
+    intervalMs: int({ min: 0 }),
+    name: text(256, 1),
+    kind: union([lit("counter"), lit("upDownCounter"), lit("histogram")]),
+    unit: opt(text(64)),
+    attributes: attributes(64, union([str({ max: 4096 }), num(), { type: "boolean" }])),
+    count: int({ min: 0 }),
+    sum: num(),
+    min: num(),
+    max: num(),
+});
+/** What `ingest` answers: the spans the store queued and the ones it dropped (refused, over the rate, over its bound). */
+const RECEIPT = obj({ written: int(), dropped: int() });
+/** A page's batch (spans only: a page sends no metrics). */
+export const PageBatch = obj({ spans: arr(PAGE_SPAN, { max: PAGE_BATCH_SPANS }) });
+/** A worker's batch: its spans and its metric rows. */
+export const WorkerBatch = obj({
+    spans: arr(WORKER_SPAN, { max: WORKER_BATCH_ROWS }),
+    metrics: arr(METRIC, { max: WORKER_BATCH_ROWS }),
+});
+/** The server's host kind as the app kit names it. */
+const Server = hostKind("server");
+/** The server's telemetry object for pages: any principal's page sends its batches to it, untrusted. */
+export const PageTelemetry = remote("chord.telemetry.page", {
+    version: 1,
+    params: {},
+    hostAddress: () => Server(),
+    variants: { main: { methods: { ingest: method(PageBatch, RECEIPT) } } },
+});
+/**
+ * The server's telemetry object for workers: `worker` for a worker's principal (its batches written as they are),
+ * `other` for everyone else (nothing to call).
+ */
+export const WorkerTelemetry = remote("chord.telemetry.worker", {
+    version: 1,
+    params: {},
+    hostAddress: () => Server(),
+    variants: { worker: { methods: { ingest: method(WorkerBatch, RECEIPT) } }, other: {} },
+});
+//# sourceMappingURL=batch.js.map

package/dist/telemetry-ingest/batch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"batch.js","sourceRoot":"","sources":["../../src/telemetry-ingest/batch.ts"],"names":[],"mappings":"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","sourcesContent":["// What pages and workers send the server's telemetry objects (decisions \"Telemetry from browser pages\", \"The server is\n// the one place telemetry is stored\"): a batch of finished spans (a worker's with its metric aggregates), its schemas\n// (a page's strict: every field bounded, ids printable ASCII, no control characters; a worker's, the server's own\n// child, generous), and the two remote objects on the server that take them, `PageTelemetry` and `WorkerTelemetry`.\n\nimport type { AttributeValue, StoredMetric, StoredSpan } from \"@earendil-works/pi-telemetry\";\nimport { arr, hostKind, int, lit, method, num, obj, opt, remote, type Schema, str, union } from \"../contracts/index.ts\";\n\n/** At most this many spans in a page's batch. */\nexport const PAGE_BATCH_SPANS = 100;\n\n/** At most this many spans and metric rows in a worker's batch. */\nexport const WORKER_BATCH_ROWS = 1000;\n\n/** An id: printable ASCII, no spaces (a page's are `browser:<incarnation>:<n>`). */\nfunction id(max: number): Schema<string> {\n\treturn str({ min: 1, max, pattern: \"^[\\\\x21-\\\\x7e]+$\" });\n}\n\n/** Text: no control characters (C0, DEL, C1), at most `max` characters. */\nfunction text(max: number, min = 0): Schema<string> {\n\treturn str({ min, max, pattern: \"^[^\\\\u0000-\\\\u001f\\\\u007f-\\\\u009f]*$\" });\n}\n\n/** A record of attributes: at most `count` keys of 1 to 64 characters of text (other keys refused), values of `value`. */\nfunction attributes(count: number, value: Schema): Schema<Record<string, AttributeValue>> {\n\treturn {\n\t\ttype: \"object\",\n\t\tmaxProperties: count,\n\t\tpatternProperties: { \"^[^\\\\u0000-\\\\u001f\\\\u007f-\\\\u009f]{1,64}$\": value },\n\t\tadditionalProperties: false,\n\t};\n}\n\n/** A finished span as `span`'s fields allow: ids, a name, times, attributes, events, links and a status. */\nfunction spanSchema(limits: SpanLimits): Schema<StoredSpan> {\n\tconst record = attributes(limits.attributes, limits.value);\n\tconst span = obj({\n\t\tid: id(limits.id),\n\t\ttraceId: id(limits.id),\n\t\tparentId: opt(id(limits.id)),\n\t\tname: text(limits.name, 1),\n\t\tstartedMs: num({ min: 0 }),\n\t\tendedMs: num({ min: 0 }),\n\t\tattributes: record,\n\t\tevents: arr(obj({ name: text(limits.name, 1), timeMs: num({ min: 0 }), attributes: record }), {\n\t\t\tmax: limits.events,\n\t\t}),\n\t\tlinks: arr(obj({ traceId: id(limits.id), spanId: id(limits.id), attributes: opt(record) }), {\n\t\t\tmax: limits.links,\n\t\t}),\n\t\tstatus: union([\n\t\t\tobj({ status: lit(\"ok\") }),\n\t\t\tobj({ status: lit(\"error\"), error: opt(obj({ name: text(64), message: text(500) })) }),\n\t\t]),\n\t});\n\t// The object schema's static type is StoredSpan's shape: the same fields, optional ones `opt`.\n\treturn span as unknown as Schema<StoredSpan>;\n}\n\n/** The bounds of one span's fields. */\ntype SpanLimits = {\n\treadonly id: number;\n\treadonly name: number;\n\treadonly attributes: number;\n\treadonly value: Schema;\n\treadonly events: number;\n\treadonly links: number;\n};\n\n/** A page's spans: what a recorded click needs, little more (decision \"Telemetry from browser pages\"). */\nconst PAGE_SPAN = spanSchema({\n\tid: 128,\n\tname: 128,\n\tattributes: 32,\n\tvalue: union([text(256), num(), { type: \"boolean\" } as Schema<boolean>]),\n\tevents: 16,\n\tlinks: 8,\n});\n\n/** A worker's spans: bounded generously (its spans are Chord's and its plugins'). */\nconst WORKER_SPAN = spanSchema({\n\tid: 256,\n\tname: 1024,\n\tattributes: 256,\n\tvalue: union([str({ max: 65_536 }), num(), { type: \"boolean\" } as Schema<boolean>, arr(union([str(), num()]))]),\n\tevents: 1024,\n\tlinks: 256,\n});\n\n/** A worker's metric row: one series' aggregate of one 10 s interval. */\nconst METRIC = obj({\n\tintervalMs: int({ min: 0 }),\n\tname: text(256, 1),\n\tkind: union([lit(\"counter\"), lit(\"upDownCounter\"), lit(\"histogram\")]),\n\tunit: opt(text(64)),\n\tattributes: attributes(64, union([str({ max: 4096 }), num(), { type: \"boolean\" } as Schema<boolean>])),\n\tcount: int({ min: 0 }),\n\tsum: num(),\n\tmin: num(),\n\tmax: num(),\n}) as unknown as Schema<StoredMetric>;\n\n/** What `ingest` answers: the spans the store queued and the ones it dropped (refused, over the rate, over its bound). */\nconst RECEIPT = obj({ written: int(), dropped: int() });\n\n/** A page's batch (spans only: a page sends no metrics). */\nexport const PageBatch = obj({ spans: arr(PAGE_SPAN, { max: PAGE_BATCH_SPANS }) });\n\n/** A worker's batch: its spans and its metric rows. */\nexport const WorkerBatch = obj({\n\tspans: arr(WORKER_SPAN, { max: WORKER_BATCH_ROWS }),\n\tmetrics: arr(METRIC, { max: WORKER_BATCH_ROWS }),\n});\n\n/** The server's host kind as the app kit names it. */\nconst Server = hostKind(\"server\");\n\n/** The server's telemetry object for pages: any principal's page sends its batches to it, untrusted. */\nexport const PageTelemetry = remote(\"chord.telemetry.page\", {\n\tversion: 1,\n\tparams: {},\n\thostAddress: () => Server(),\n\tvariants: { main: { methods: { ingest: method(PageBatch, RECEIPT) } } },\n});\n\n/**\n * The server's telemetry object for workers: `worker` for a worker's principal (its batches written as they are),\n * `other` for everyone else (nothing to call).\n */\nexport const WorkerTelemetry = remote(\"chord.telemetry.worker\", {\n\tversion: 1,\n\tparams: {},\n\thostAddress: () => Server(),\n\tvariants: { worker: { methods: { ingest: method(WorkerBatch, RECEIPT) } }, other: {} },\n});\n"]}

package/dist/telemetry-ingest/facet.d.ts

@@ -0,0 +1,21 @@
+import type { SpanAttributes } from "@earendil-works/pi-telemetry";
+import type { Principal } from "../data/index.ts";
+import { type Facet } from "../host/index.ts";
+import type { TelemetryBatch } from "./recorder.ts";
+/** Where ingested batches go: the server's store (`SqliteTelemetry`), which queues them; how many spans it queued. */
+export type TelemetryIngestTarget = {
+    ingest(batch: TelemetryBatch): number;
+};
+/** What the ingest facet takes. */
+export type TelemetryIngestOptions<P extends Principal> = {
+    readonly target: TelemetryIngestTarget;
+    /** The address key of the worker whose link stamps `principal`; `undefined` for any other principal. */
+    readonly workerHost: (principal: P) => string | undefined;
+    /** The attributes a page's spans record for the principal of their link (the server host's `principalAttributes`). */
+    readonly principalAttributes: (principal: P) => Readonly<SpanAttributes>;
+};
+/** How many spans one page may send per minute; past it they are dropped (and counted in its receipts). */
+export declare const PAGE_SPANS_PER_MINUTE = 1200;
+/** The ingest facet: `PageTelemetry` and `WorkerTelemetry` on the server, writing to `options.target`. */
+export declare function telemetryIngestFacet<P extends Principal>(options: TelemetryIngestOptions<P>): Facet<P>;
+//# sourceMappingURL=facet.d.ts.map

package/dist/telemetry-ingest/facet.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"facet.d.ts","sourceRoot":"","sources":["../../src/telemetry-ingest/facet.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,cAAc,EAAc,MAAM,8BAA8B,CAAC;AAE/E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAe,KAAK,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAE3D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAEpD,sHAAsH;AACtH,MAAM,MAAM,qBAAqB,GAAG;IAAE,MAAM,CAAC,KAAK,EAAE,cAAc,GAAG,MAAM,CAAA;CAAE,CAAC;AAE9E,mCAAmC;AACnC,MAAM,MAAM,sBAAsB,CAAC,CAAC,SAAS,SAAS,IAAI;IACzD,QAAQ,CAAC,MAAM,EAAE,qBAAqB,CAAC;IACvC,wGAAwG;IACxG,QAAQ,CAAC,UAAU,EAAE,CAAC,SAAS,EAAE,CAAC,KAAK,MAAM,GAAG,SAAS,CAAC;IAC1D,sHAAsH;IACtH,QAAQ,CAAC,mBAAmB,EAAE,CAAC,SAAS,EAAE,CAAC,KAAK,QAAQ,CAAC,cAAc,CAAC,CAAC;CACzE,CAAC;AAEF,2GAA2G;AAC3G,eAAO,MAAM,qBAAqB,OAAO,CAAC;AAO1C,0GAA0G;AAC1G,wBAAgB,oBAAoB,CAAC,CAAC,SAAS,SAAS,EAAE,OAAO,EAAE,sBAAsB,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CA6CtG"}

package/dist/telemetry-ingest/facet.js

@@ -0,0 +1,96 @@
+// The server's telemetry ingest (decisions "Telemetry from browser pages", "The server is the one place telemetry is
+// stored", "Who a span was for"): a facet serving `PageTelemetry` and `WorkerTelemetry`, whose `ingest(batch)` writes
+// what pages and workers recorded to the server's store. A page is untrusted: its spans must carry its own ids
+// (`browser:<its incarnation>:...`), are capped per page and minute, marked `chord.host: browser` and stamped with the
+// principal of the link they came over; a worker's are written as they are, stamped with its host.
+import { defineFacet } from "../host/index.js";
+import { PageTelemetry, WorkerTelemetry } from "./batch.js";
+/** How many spans one page may send per minute; past it they are dropped (and counted in its receipts). */
+export const PAGE_SPANS_PER_MINUTE = 1200;
+/** How many pages' minute counts one principal's object keeps (the earliest goes first). */
+const PAGES = 1000;
+const MINUTE_MS = 60_000;
+/** The ingest facet: `PageTelemetry` and `WorkerTelemetry` on the server, writing to `options.target`. */
+export function telemetryIngestFacet(options) {
+    return defineFacet((host) => {
+        host.serve(PageTelemetry, (_params, principal) => {
+            // Per span, as for every span Chord records with a principal: caching is the hook's own.
+            const who = () => options.principalAttributes(principal);
+            const budgets = new PageBudgets();
+            return {
+                variant: "main",
+                members: {
+                    ingest: async (batch, ctx) => {
+                        const budget = budgets.of(ctx.incarnation, Date.now());
+                        const accepted = pageSpans(batch, `browser:${ctx.incarnation}:`, who, budget);
+                        const written = options.target.ingest({ spans: accepted, metrics: [] });
+                        return { written, dropped: batch.spans.length - written };
+                    },
+                },
+            };
+        }, 
+        // A span per batch would be telemetry about telemetry, written back with the next batch.
+        { untraced: true });
+        host.serve(WorkerTelemetry, (_params, principal) => {
+            const worker = options.workerHost(principal);
+            if (worker === undefined)
+                return { variant: "other", members: {} };
+            return {
+                variant: "worker",
+                members: {
+                    ingest: async ({ spans, metrics }, _ctx) => {
+                        const stamped = spans.map((span) => ({
+                            ...span,
+                            attributes: { ...span.attributes, "chord.host": worker },
+                        }));
+                        const written = options.target.ingest({ spans: stamped, metrics });
+                        return { written, dropped: spans.length - written };
+                    },
+                },
+            };
+        }, { untraced: true });
+    });
+}
+/** The minute budgets of one principal's pages, by incarnation, bounded (the earliest page goes first). */
+class PageBudgets {
+    #budgets = new Map();
+    /** The budget of the page `incarnation` at `now`: a new minute starts a new one. */
+    of(incarnation, now) {
+        let budget = this.#budgets.get(incarnation);
+        if (budget === undefined || now - budget.start >= MINUTE_MS) {
+            this.#budgets.delete(incarnation);
+            if (this.#budgets.size >= PAGES)
+                this.#budgets.delete(this.#budgets.keys().next().value);
+            budget = { start: now, spans: 0 };
+            this.#budgets.set(incarnation, budget);
+        }
+        return budget;
+    }
+}
+/**
+ * The spans of a page's `batch` the store takes: its own (ids, trace and parent under `prefix`, so it never writes
+ * into another sender's trace or poses as a server span), ending after they start, within its minute's `budget`; each
+ * marked `chord.host: browser` and stamped with `who()` (the link's principal's attributes), which no attribute of the
+ * page's may override: the page's own `chord.*` attributes are dropped (a claimed `chord.principal` too, when the hook
+ * records none).
+ */
+function pageSpans(batch, prefix, who, budget) {
+    const accepted = [];
+    for (const span of batch.spans) {
+        if (budget.spans >= PAGE_SPANS_PER_MINUTE)
+            break;
+        const own = span.id.startsWith(prefix) &&
+            span.traceId.startsWith(prefix) &&
+            (span.parentId === undefined || span.parentId.startsWith(prefix));
+        if (!own || span.endedMs < span.startedMs)
+            continue;
+        budget.spans++;
+        accepted.push({ ...span, attributes: { "chord.host": "browser", ...ownAttributes(span.attributes), ...who() } });
+    }
+    return accepted;
+}
+/** A page's attributes without Chord's (`chord.*`): what Chord records about a span, the server stamps itself. */
+function ownAttributes(attributes) {
+    return Object.fromEntries(Object.entries(attributes).filter(([key]) => !key.startsWith("chord.")));
+}
+//# sourceMappingURL=facet.js.map

package/dist/telemetry-ingest/facet.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"facet.js","sourceRoot":"","sources":["../../src/telemetry-ingest/facet.ts"],"names":[],"mappings":"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","sourcesContent":["// The server's telemetry ingest (decisions \"Telemetry from browser pages\", \"The server is the one place telemetry is\n// stored\", \"Who a span was for\"): a facet serving `PageTelemetry` and `WorkerTelemetry`, whose `ingest(batch)` writes\n// what pages and workers recorded to the server's store. A page is untrusted: its spans must carry its own ids\n// (`browser:<its incarnation>:...`), are capped per page and minute, marked `chord.host: browser` and stamped with the\n// principal of the link they came over; a worker's are written as they are, stamped with its host.\n\nimport type { SpanAttributes, StoredSpan } from \"@earendil-works/pi-telemetry\";\nimport type { Static } from \"../contracts/index.ts\";\nimport type { Principal } from \"../data/index.ts\";\nimport { defineFacet, type Facet } from \"../host/index.ts\";\nimport { type PageBatch, PageTelemetry, WorkerTelemetry } from \"./batch.ts\";\nimport type { TelemetryBatch } from \"./recorder.ts\";\n\n/** Where ingested batches go: the server's store (`SqliteTelemetry`), which queues them; how many spans it queued. */\nexport type TelemetryIngestTarget = { ingest(batch: TelemetryBatch): number };\n\n/** What the ingest facet takes. */\nexport type TelemetryIngestOptions<P extends Principal> = {\n\treadonly target: TelemetryIngestTarget;\n\t/** The address key of the worker whose link stamps `principal`; `undefined` for any other principal. */\n\treadonly workerHost: (principal: P) => string | undefined;\n\t/** The attributes a page's spans record for the principal of their link (the server host's `principalAttributes`). */\n\treadonly principalAttributes: (principal: P) => Readonly<SpanAttributes>;\n};\n\n/** How many spans one page may send per minute; past it they are dropped (and counted in its receipts). */\nexport const PAGE_SPANS_PER_MINUTE = 1200;\n\n/** How many pages' minute counts one principal's object keeps (the earliest goes first). */\nconst PAGES = 1000;\n\nconst MINUTE_MS = 60_000;\n\n/** The ingest facet: `PageTelemetry` and `WorkerTelemetry` on the server, writing to `options.target`. */\nexport function telemetryIngestFacet<P extends Principal>(options: TelemetryIngestOptions<P>): Facet<P> {\n\treturn defineFacet<P>((host) => {\n\t\thost.serve(\n\t\t\tPageTelemetry,\n\t\t\t(_params, principal) => {\n\t\t\t\t// Per span, as for every span Chord records with a principal: caching is the hook's own.\n\t\t\t\tconst who = () => options.principalAttributes(principal);\n\t\t\t\tconst budgets = new PageBudgets();\n\t\t\t\treturn {\n\t\t\t\t\tvariant: \"main\",\n\t\t\t\t\tmembers: {\n\t\t\t\t\t\tingest: async (batch, ctx) => {\n\t\t\t\t\t\t\tconst budget = budgets.of(ctx.incarnation, Date.now());\n\t\t\t\t\t\t\tconst accepted = pageSpans(batch, `browser:${ctx.incarnation}:`, who, budget);\n\t\t\t\t\t\t\tconst written = options.target.ingest({ spans: accepted, metrics: [] });\n\t\t\t\t\t\t\treturn { written, dropped: batch.spans.length - written };\n\t\t\t\t\t\t},\n\t\t\t\t\t},\n\t\t\t\t};\n\t\t\t},\n\t\t\t// A span per batch would be telemetry about telemetry, written back with the next batch.\n\t\t\t{ untraced: true },\n\t\t);\n\t\thost.serve(\n\t\t\tWorkerTelemetry,\n\t\t\t(_params, principal) => {\n\t\t\t\tconst worker = options.workerHost(principal);\n\t\t\t\tif (worker === undefined) return { variant: \"other\", members: {} };\n\t\t\t\treturn {\n\t\t\t\t\tvariant: \"worker\",\n\t\t\t\t\tmembers: {\n\t\t\t\t\t\tingest: async ({ spans, metrics }, _ctx) => {\n\t\t\t\t\t\t\tconst stamped = spans.map((span) => ({\n\t\t\t\t\t\t\t\t...span,\n\t\t\t\t\t\t\t\tattributes: { ...span.attributes, \"chord.host\": worker },\n\t\t\t\t\t\t\t}));\n\t\t\t\t\t\t\tconst written = options.target.ingest({ spans: stamped, metrics });\n\t\t\t\t\t\t\treturn { written, dropped: spans.length - written };\n\t\t\t\t\t\t},\n\t\t\t\t\t},\n\t\t\t\t};\n\t\t\t},\n\t\t\t{ untraced: true },\n\t\t);\n\t});\n}\n\n/** One page's spans of the current minute. */\ntype Budget = { readonly start: number; spans: number };\n\n/** The minute budgets of one principal's pages, by incarnation, bounded (the earliest page goes first). */\nclass PageBudgets {\n\treadonly #budgets = new Map<string, Budget>();\n\n\t/** The budget of the page `incarnation` at `now`: a new minute starts a new one. */\n\tof(incarnation: string, now: number): Budget {\n\t\tlet budget = this.#budgets.get(incarnation);\n\t\tif (budget === undefined || now - budget.start >= MINUTE_MS) {\n\t\t\tthis.#budgets.delete(incarnation);\n\t\t\tif (this.#budgets.size >= PAGES) this.#budgets.delete(this.#budgets.keys().next().value!);\n\t\t\tbudget = { start: now, spans: 0 };\n\t\t\tthis.#budgets.set(incarnation, budget);\n\t\t}\n\t\treturn budget;\n\t}\n}\n\n/**\n * The spans of a page's `batch` the store takes: its own (ids, trace and parent under `prefix`, so it never writes\n * into another sender's trace or poses as a server span), ending after they start, within its minute's `budget`; each\n * marked `chord.host: browser` and stamped with `who()` (the link's principal's attributes), which no attribute of the\n * page's may override: the page's own `chord.*` attributes are dropped (a claimed `chord.principal` too, when the hook\n * records none).\n */\nfunction pageSpans(\n\tbatch: Static<typeof PageBatch>,\n\tprefix: string,\n\twho: () => Readonly<SpanAttributes>,\n\tbudget: Budget,\n): StoredSpan[] {\n\tconst accepted: StoredSpan[] = [];\n\tfor (const span of batch.spans) {\n\t\tif (budget.spans >= PAGE_SPANS_PER_MINUTE) break;\n\t\tconst own =\n\t\t\tspan.id.startsWith(prefix) &&\n\t\t\tspan.traceId.startsWith(prefix) &&\n\t\t\t(span.parentId === undefined || span.parentId.startsWith(prefix));\n\t\tif (!own || span.endedMs < span.startedMs) continue;\n\t\tbudget.spans++;\n\t\taccepted.push({ ...span, attributes: { \"chord.host\": \"browser\", ...ownAttributes(span.attributes), ...who() } });\n\t}\n\treturn accepted;\n}\n\n/** A page's attributes without Chord's (`chord.*`): what Chord records about a span, the server stamps itself. */\nfunction ownAttributes(attributes: SpanAttributes): SpanAttributes {\n\treturn Object.fromEntries(Object.entries(attributes).filter(([key]) => !key.startsWith(\"chord.\")));\n}\n"]}

package/dist/telemetry-ingest/index.d.ts

@@ -0,0 +1,5 @@
+export { PAGE_BATCH_SPANS, PageBatch, PageTelemetry, WORKER_BATCH_ROWS, WorkerBatch, WorkerTelemetry, } from "./batch.ts";
+export { PAGE_SPANS_PER_MINUTE, type TelemetryIngestOptions, type TelemetryIngestTarget, telemetryIngestFacet, } from "./facet.ts";
+export { type TelemetryBatch, TelemetryRecorder } from "./recorder.ts";
+export { sendPageTelemetry, sendWorkerTelemetry, type TelemetrySender } from "./sender.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/telemetry-ingest/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/telemetry-ingest/index.ts"],"names":[],"mappings":"AAIA,OAAO,EACN,gBAAgB,EAChB,SAAS,EACT,aAAa,EACb,iBAAiB,EACjB,WAAW,EACX,eAAe,GACf,MAAM,YAAY,CAAC;AACpB,OAAO,EACN,qBAAqB,EACrB,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,EAC1B,oBAAoB,GACpB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,KAAK,cAAc,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AACvE,OAAO,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,KAAK,eAAe,EAAE,MAAM,aAAa,CAAC"}

package/dist/telemetry-ingest/index.js

@@ -0,0 +1,8 @@
+// Telemetry from pages and workers to the server's store (decisions "Telemetry from browser pages", "The server is
+// the one place telemetry is stored"): the recorder pages and workers keep their spans in, the batches and the
+// server's objects that take them, the facet serving those, and the senders.
+export { PAGE_BATCH_SPANS, PageBatch, PageTelemetry, WORKER_BATCH_ROWS, WorkerBatch, WorkerTelemetry, } from "./batch.js";
+export { PAGE_SPANS_PER_MINUTE, telemetryIngestFacet, } from "./facet.js";
+export { TelemetryRecorder } from "./recorder.js";
+export { sendPageTelemetry, sendWorkerTelemetry } from "./sender.js";
+//# sourceMappingURL=index.js.map

package/dist/telemetry-ingest/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/telemetry-ingest/index.ts"],"names":[],"mappings":"AAAA,mHAAmH;AACnH,+GAA+G;AAC/G,6EAA6E;AAE7E,OAAO,EACN,gBAAgB,EAChB,SAAS,EACT,aAAa,EACb,iBAAiB,EACjB,WAAW,EACX,eAAe,GACf,MAAM,YAAY,CAAC;AACpB,OAAO,EACN,qBAAqB,EAGrB,oBAAoB,GACpB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAuB,iBAAiB,EAAE,MAAM,eAAe,CAAC;AACvE,OAAO,EAAE,iBAAiB,EAAE,mBAAmB,EAAwB,MAAM,aAAa,CAAC","sourcesContent":["// Telemetry from pages and workers to the server's store (decisions \"Telemetry from browser pages\", \"The server is\n// the one place telemetry is stored\"): the recorder pages and workers keep their spans in, the batches and the\n// server's objects that take them, the facet serving those, and the senders.\n\nexport {\n\tPAGE_BATCH_SPANS,\n\tPageBatch,\n\tPageTelemetry,\n\tWORKER_BATCH_ROWS,\n\tWorkerBatch,\n\tWorkerTelemetry,\n} from \"./batch.ts\";\nexport {\n\tPAGE_SPANS_PER_MINUTE,\n\ttype TelemetryIngestOptions,\n\ttype TelemetryIngestTarget,\n\ttelemetryIngestFacet,\n} from \"./facet.ts\";\nexport { type TelemetryBatch, TelemetryRecorder } from \"./recorder.ts\";\nexport { sendPageTelemetry, sendWorkerTelemetry, type TelemetrySender } from \"./sender.ts\";\n"]}

package/dist/telemetry-ingest/recorder.d.ts

@@ -0,0 +1,50 @@
+import { type SpanAttributes, type SpanOptions, type StoredMetric, type StoredSpan, type TelemetryCarrier, type TelemetryContext, type TelemetryMetrics, type TelemetryPropagation, type TelemetrySpan } from "@earendil-works/pi-telemetry";
+/** What a recorder hands its owner at once: settled spans and metric aggregates. */
+export type TelemetryBatch = {
+    readonly spans: StoredSpan[];
+    readonly metrics: StoredMetric[];
+};
+/** The metric interval. */
+export declare const INTERVAL_MS = 10000;
+/**
+ * Records spans and metrics in memory for its owner, who takes them in batches (`take`, then `release` once they are
+ * written or given up). Span ids are `<scope>:<n>`, `scope` read at the first span (a page's names its host's
+ * incarnation, made after the recorder). `capacity` bounds the queued spans, a taken batch's included, and separately
+ * the pending metric series.
+ */
+export declare class TelemetryRecorder implements TelemetryContext, TelemetryPropagation {
+    #private;
+    readonly propagation: TelemetryPropagation;
+    readonly metrics: TelemetryMetrics;
+    droppedSpans: number;
+    droppedMeasurements: number;
+    constructor(scope: () => string, capacity: number);
+    /** Whether it stopped: later spans are inert, later measurements ignored. */
+    get stopped(): boolean;
+    startSpan<T>(options: SpanOptions, callback: (span: TelemetrySpan) => T | Promise<T>): Promise<T>;
+    inject(context: TelemetryContext): TelemetryCarrier | undefined;
+    extract(carrier: TelemetryCarrier | undefined): TelemetryContext;
+    /**
+     * Takes the queued spans (at most `limit`, the oldest) and the metric intervals that are over (every one with
+     * `partial`); the spans keep counting against the capacity until `release`.
+     */
+    take(partial: boolean, limit?: number): TelemetryBatch;
+    /** The batch taken last was written or given up: its capacity is free again. */
+    release(): void;
+    /** How many settled spans wait to be taken. */
+    get queuedSpans(): number;
+    /** Whether spans, or metric intervals that are over (all of them with `partial`), wait to be taken. */
+    pending(partial: boolean): boolean;
+    /**
+     * Queues spans and metric rows another process recorded (an ingest), within the capacity; returns how many spans
+     * it queued (the rest dropped and counted).
+     */
+    ingest(batch: TelemetryBatch): number;
+    /** Stops recording; with `discard`, what waits is dropped too (a failed store). */
+    stop(discard: "keep" | "discard"): void;
+}
+/** A metric's series: its name, kind, unit and attributes (sorted by key), as JSON. */
+export declare function seriesKey(metric: StoredMetric): string;
+/** `attributes` with their keys in order (a series' attributes as stored). */
+export declare function sortedAttributes(attributes: SpanAttributes): SpanAttributes;
+//# sourceMappingURL=recorder.d.ts.map

package/dist/telemetry-ingest/recorder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recorder.d.ts","sourceRoot":"","sources":["../../src/telemetry-ingest/recorder.ts"],"names":[],"mappings":"AAKA,OAAO,EAGN,KAAK,cAAc,EAEnB,KAAK,WAAW,EAEhB,KAAK,YAAY,EACjB,KAAK,UAAU,EACf,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,EACzB,KAAK,aAAa,EAElB,MAAM,8BAA8B,CAAC;AAEtC,oFAAoF;AACpF,MAAM,MAAM,cAAc,GAAG;IAAE,QAAQ,CAAC,KAAK,EAAE,UAAU,EAAE,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,YAAY,EAAE,CAAA;CAAE,CAAC;AAchG,2BAA2B;AAC3B,eAAO,MAAM,WAAW,QAAS,CAAC;AAElC;;;;;GAKG;AACH,qBAAa,iBAAkB,YAAW,gBAAgB,EAAE,oBAAoB;;IAC/E,QAAQ,CAAC,WAAW,EAAE,oBAAoB,CAAQ;IAClD,QAAQ,CAAC,OAAO,EAAE,gBAAgB,CAIhC;IACF,YAAY,SAAK;IACjB,mBAAmB,SAAK;IAWxB,YAAY,KAAK,EAAE,MAAM,MAAM,EAAE,QAAQ,EAAE,MAAM,EAGhD;IAED,6EAA6E;IAC7E,IAAI,OAAO,IAAI,OAAO,CAErB;IAED,SAAS,CAAC,CAAC,EAAE,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,CAAC,IAAI,EAAE,aAAa,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAEhG;IAED,MAAM,CAAC,OAAO,EAAE,gBAAgB,GAAG,gBAAgB,GAAG,SAAS,CAG9D;IAED,OAAO,CAAC,OAAO,EAAE,gBAAgB,GAAG,SAAS,GAAG,gBAAgB,CAa/D;IAED;;;OAGG;IACH,IAAI,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,SAA2B,GAAG,cAAc,CAavE;IAED,gFAAgF;IAChF,OAAO,IAAI,IAAI,CAGd;IAED,+CAA+C;IAC/C,IAAI,WAAW,IAAI,MAAM,CAExB;IAED,uGAAuG;IACvG,OAAO,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAKjC;IAED;;;OAGG;IACH,MAAM,CAAC,KAAK,EAAE,cAAc,GAAG,MAAM,CAYpC;IAED,mFAAmF;IACnF,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAMtC;CA6ID;AAED,uFAAuF;AACvF,wBAAgB,SAAS,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CAOtD;AAOD,8EAA8E;AAC9E,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,cAAc,GAAG,cAAc,CAM3E"}