@earendil-works/chord 1.4.0 → 1.5.1

package/dist/telemetry-ingest/recorder.js

@@ -0,0 +1,298 @@
+// Chord's telemetry recorder (§29): an adapter keeping settled spans and metric aggregates (per series per 10 s) in a
+// bounded queue (past it dropped and counted), until its owner takes them as a batch: the SQLite store writes its
+// batches to its file, a page or a worker sends them to the server's telemetry object (`TelemetryIngest`). Its
+// carriers name a span by id and trace id; every recorder of a process reads every other's (one carrier format).
+import { NOOP_TELEMETRY_CONTEXT, telemetryNow, } from "@earendil-works/pi-telemetry";
+/** The identities of every recorder's spans and extracted parents in this process: links and carriers read them. */
+const identities = new WeakMap();
+/** The carrier's keys: a span's id and its trace's (the SQLite store's since slice 9: stored job carriers use them). */
+const SPAN_KEY = "pi-sqlite-span";
+const TRACE_KEY = "pi-sqlite-trace";
+/** The metric interval. */
+export const INTERVAL_MS = 10_000;
+/**
+ * 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 class TelemetryRecorder {
+    propagation = this;
+    metrics = {
+        counter: (name, options) => ({ add: this.#measurement("counter", name, options) }),
+        upDownCounter: (name, options) => ({ add: this.#measurement("upDownCounter", name, options) }),
+        histogram: (name, options) => ({ record: this.#measurement("histogram", name, options) }),
+    };
+    droppedSpans = 0;
+    droppedMeasurements = 0;
+    #scope;
+    #prefix;
+    #capacity;
+    #sequence = 0;
+    #spans = [];
+    #inFlight = 0;
+    #measurements = new Map();
+    #inFlightMeasurements = 0;
+    #stopped = false;
+    constructor(scope, capacity) {
+        this.#scope = scope;
+        this.#capacity = capacity;
+    }
+    /** Whether it stopped: later spans are inert, later measurements ignored. */
+    get stopped() {
+        return this.#stopped;
+    }
+    startSpan(options, callback) {
+        return this.#start(undefined, options, callback);
+    }
+    inject(context) {
+        const identity = identities.get(context);
+        return identity ? { [SPAN_KEY]: identity.id, [TRACE_KEY]: identity.traceId } : undefined;
+    }
+    extract(carrier) {
+        const id = carrier?.[SPAN_KEY];
+        const traceId = carrier?.[TRACE_KEY];
+        // Carriers come from other processes: only their two strings are read, else the root.
+        if (typeof id !== "string" || typeof traceId !== "string")
+            return this;
+        const identity = { id, traceId };
+        const parent = {
+            metrics: this.metrics,
+            propagation: this,
+            startSpan: (options, callback) => this.#start(identity, options, callback),
+        };
+        identities.set(parent, identity);
+        return parent;
+    }
+    /**
+     * 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, limit = Number.POSITIVE_INFINITY) {
+        const spans = this.#spans.length <= limit ? this.#spans : this.#spans.slice(0, limit);
+        this.#spans = spans === this.#spans ? [] : this.#spans.slice(limit);
+        this.#inFlight = spans.length;
+        const metrics = [];
+        const current = intervalOf(Date.now());
+        for (const [key, { key: _series, ...metric }] of this.#measurements) {
+            if (!partial && metric.intervalMs >= current)
+                continue;
+            metrics.push(metric);
+            this.#measurements.delete(key);
+        }
+        this.#inFlightMeasurements = metrics.length;
+        return { spans, metrics };
+    }
+    /** The batch taken last was written or given up: its capacity is free again. */
+    release() {
+        this.#inFlight = 0;
+        this.#inFlightMeasurements = 0;
+    }
+    /** How many settled spans wait to be taken. */
+    get queuedSpans() {
+        return this.#spans.length;
+    }
+    /** Whether spans, or metric intervals that are over (all of them with `partial`), wait to be taken. */
+    pending(partial) {
+        if (this.#spans.length > 0)
+            return true;
+        const current = intervalOf(Date.now());
+        for (const metric of this.#measurements.values())
+            if (partial || metric.intervalMs < current)
+                return true;
+        return false;
+    }
+    /**
+     * 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) {
+        if (this.#stopped)
+            return 0;
+        let queued = 0;
+        for (const span of batch.spans) {
+            if (this.#spans.length + this.#inFlight >= this.#capacity)
+                this.droppedSpans++;
+            else {
+                this.#spans.push(span);
+                queued++;
+            }
+        }
+        for (const metric of batch.metrics)
+            this.#merge(metric);
+        return queued;
+    }
+    /** Stops recording; with `discard`, what waits is dropped too (a failed store). */
+    stop(discard) {
+        this.#stopped = true;
+        if (discard === "discard") {
+            this.#spans = [];
+            this.#measurements.clear();
+        }
+    }
+    #inert(options, callback) {
+        return NOOP_TELEMETRY_CONTEXT.startSpan(options, (noop) => callback({
+            ...noop,
+            metrics: this.metrics,
+            propagation: this,
+            startSpan: (options, callback) => this.#inert(options, callback),
+        }));
+    }
+    async #start(parent, options, callback) {
+        if (this.#stopped)
+            return this.#inert(options, callback);
+        let attributes = copyAttributes(options.attributes);
+        const links = [];
+        for (const link of options.links ?? []) {
+            const copied = copyLink(link);
+            if (copied)
+                links.push(copied);
+        }
+        this.#prefix ??= this.#scope();
+        const id = `${this.#prefix}:${++this.#sequence}`;
+        const identity = { id, traceId: parent?.traceId ?? id };
+        // The start on the clock pi-telemetry's adapters share; the end and events by the monotonic clock from it.
+        const started = telemetryNow();
+        const clock = performance.now();
+        const events = [];
+        let status = { status: "ok" };
+        let explicit = false;
+        let settled = false;
+        const record = (action) => {
+            if (!settled && !this.#stopped)
+                action();
+        };
+        const span = {
+            metrics: this.metrics,
+            propagation: this,
+            startSpan: (options, callback) => settled ? this.#inert(options, callback) : this.#start(identity, options, callback),
+            addLink: (link) => record(() => {
+                const copied = copyLink(link);
+                if (copied)
+                    links.push(copied);
+            }),
+            addEvent: (name, attrs) => record(() => {
+                events.push({
+                    name,
+                    timeMs: microseconds(performance.now() - clock),
+                    attributes: copyAttributes(attrs),
+                });
+            }),
+            setAttributes: (attrs) => record(() => {
+                attributes = { ...attributes, ...copyAttributes(attrs) };
+            }),
+            setStatus: (value) => record(() => {
+                status =
+                    value.status === "error" && value.error
+                        ? { status: "error", error: { ...value.error } }
+                        : { status: value.status };
+                explicit = true;
+            }),
+        };
+        identities.set(span, identity);
+        try {
+            return await callback(span);
+        }
+        catch (error) {
+            if (!explicit)
+                status =
+                    error instanceof Error
+                        ? { status: "error", error: { name: error.name, message: error.message } }
+                        : { status: "error" };
+            throw error;
+        }
+        finally {
+            settled = true;
+            if (!this.#stopped) {
+                if (this.#spans.length + this.#inFlight >= this.#capacity)
+                    this.droppedSpans++;
+                else
+                    this.#spans.push({
+                        id,
+                        traceId: identity.traceId,
+                        ...(parent === undefined ? {} : { parentId: parent.id }),
+                        name: options.name,
+                        startedMs: started,
+                        endedMs: microseconds(started + performance.now() - clock),
+                        attributes,
+                        events,
+                        links,
+                        status,
+                    });
+            }
+        }
+    }
+    #measurement(kind, name, options) {
+        const unit = options?.unit;
+        return (value, attributes) => {
+            if (this.#stopped)
+                return;
+            this.#merge({
+                intervalMs: intervalOf(Date.now()),
+                name,
+                kind,
+                ...(unit === undefined ? {} : { unit }),
+                attributes: sortedAttributes(copyAttributes(attributes)),
+                count: 1,
+                sum: value,
+                min: value,
+                max: value,
+            });
+        };
+    }
+    /** Adds `metric` to its series' pending interval (a new series within the capacity, else dropped and counted). */
+    #merge(metric) {
+        if (this.#stopped)
+            return;
+        const key = seriesKey(metric);
+        const pendingKey = `${metric.intervalMs}:${key}`;
+        const previous = this.#measurements.get(pendingKey);
+        if (!previous && this.#measurements.size + this.#inFlightMeasurements >= this.#capacity) {
+            this.droppedMeasurements++;
+            return;
+        }
+        this.#measurements.set(pendingKey, {
+            ...metric,
+            key,
+            count: (previous?.count ?? 0) + metric.count,
+            sum: (previous?.sum ?? 0) + metric.sum,
+            min: Math.min(previous?.min ?? metric.min, metric.min),
+            max: Math.max(previous?.max ?? metric.max, metric.max),
+        });
+    }
+}
+/** A metric's series: its name, kind, unit and attributes (sorted by key), as JSON. */
+export function seriesKey(metric) {
+    return JSON.stringify([
+        metric.name,
+        metric.kind,
+        metric.unit ?? null,
+        JSON.stringify(sortedAttributes(metric.attributes)),
+    ]);
+}
+/** The start of the metric interval `time` falls in. */
+function intervalOf(time) {
+    return Math.floor(time / INTERVAL_MS) * INTERVAL_MS;
+}
+/** `attributes` with their keys in order (a series' attributes as stored). */
+export function sortedAttributes(attributes) {
+    return Object.fromEntries(Object.keys(attributes)
+        .sort()
+        .map((key) => [key, attributes[key]]));
+}
+/** `ms` rounded to the microsecond, as span times are. */
+function microseconds(ms) {
+    return Math.round(ms * 1000) / 1000;
+}
+function copyAttributes(attributes) {
+    return Object.fromEntries(Object.entries(attributes ?? {})
+        .filter(([, value]) => value !== undefined)
+        .map(([key, value]) => [key, Array.isArray(value) ? [...value] : value]));
+}
+function copyLink(link) {
+    const identity = identities.get(link.context);
+    return identity
+        ? { traceId: identity.traceId, spanId: identity.id, attributes: copyAttributes(link.attributes) }
+        : undefined;
+}
+//# sourceMappingURL=recorder.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"recorder.js","sourceRoot":"","sources":["../../src/telemetry-ingest/recorder.ts"],"names":[],"mappings":"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","sourcesContent":["// Chord's telemetry recorder (§29): an adapter keeping settled spans and metric aggregates (per series per 10 s) in a\n// bounded queue (past it dropped and counted), until its owner takes them as a batch: the SQLite store writes its\n// batches to its file, a page or a worker sends them to the server's telemetry object (`TelemetryIngest`). Its\n// carriers name a span by id and trace id; every recorder of a process reads every other's (one carrier format).\n\nimport {\n\ttype InstrumentOptions,\n\tNOOP_TELEMETRY_CONTEXT,\n\ttype SpanAttributes,\n\ttype SpanLink,\n\ttype SpanOptions,\n\ttype SpanStatus,\n\ttype StoredMetric,\n\ttype StoredSpan,\n\ttype TelemetryCarrier,\n\ttype TelemetryContext,\n\ttype TelemetryMetrics,\n\ttype TelemetryPropagation,\n\ttype TelemetrySpan,\n\ttelemetryNow,\n} from \"@earendil-works/pi-telemetry\";\n\n/** What a recorder hands its owner at once: settled spans and metric aggregates. */\nexport type TelemetryBatch = { readonly spans: StoredSpan[]; readonly metrics: StoredMetric[] };\n\n/** A span's identity in carriers and links: its id and its trace's. */\ntype Identity = { readonly id: string; readonly traceId: string };\n\ntype Metric = StoredMetric & { readonly key: string };\n\n/** The identities of every recorder's spans and extracted parents in this process: links and carriers read them. */\nconst identities = new WeakMap<TelemetryContext, Identity>();\n\n/** The carrier's keys: a span's id and its trace's (the SQLite store's since slice 9: stored job carriers use them). */\nconst SPAN_KEY = \"pi-sqlite-span\";\nconst TRACE_KEY = \"pi-sqlite-trace\";\n\n/** The metric interval. */\nexport const INTERVAL_MS = 10_000;\n\n/**\n * Records spans and metrics in memory for its owner, who takes them in batches (`take`, then `release` once they are\n * written or given up). Span ids are `<scope>:<n>`, `scope` read at the first span (a page's names its host's\n * incarnation, made after the recorder). `capacity` bounds the queued spans, a taken batch's included, and separately\n * the pending metric series.\n */\nexport class TelemetryRecorder implements TelemetryContext, TelemetryPropagation {\n\treadonly propagation: TelemetryPropagation = this;\n\treadonly metrics: TelemetryMetrics = {\n\t\tcounter: (name, options) => ({ add: this.#measurement(\"counter\", name, options) }),\n\t\tupDownCounter: (name, options) => ({ add: this.#measurement(\"upDownCounter\", name, options) }),\n\t\thistogram: (name, options) => ({ record: this.#measurement(\"histogram\", name, options) }),\n\t};\n\tdroppedSpans = 0;\n\tdroppedMeasurements = 0;\n\treadonly #scope: () => string;\n\t#prefix: string | undefined;\n\treadonly #capacity: number;\n\t#sequence = 0;\n\t#spans: StoredSpan[] = [];\n\t#inFlight = 0;\n\treadonly #measurements = new Map<string, Metric>();\n\t#inFlightMeasurements = 0;\n\t#stopped = false;\n\n\tconstructor(scope: () => string, capacity: number) {\n\t\tthis.#scope = scope;\n\t\tthis.#capacity = capacity;\n\t}\n\n\t/** Whether it stopped: later spans are inert, later measurements ignored. */\n\tget stopped(): boolean {\n\t\treturn this.#stopped;\n\t}\n\n\tstartSpan<T>(options: SpanOptions, callback: (span: TelemetrySpan) => T | Promise<T>): Promise<T> {\n\t\treturn this.#start(undefined, options, callback);\n\t}\n\n\tinject(context: TelemetryContext): TelemetryCarrier | undefined {\n\t\tconst identity = identities.get(context);\n\t\treturn identity ? { [SPAN_KEY]: identity.id, [TRACE_KEY]: identity.traceId } : undefined;\n\t}\n\n\textract(carrier: TelemetryCarrier | undefined): TelemetryContext {\n\t\tconst id = carrier?.[SPAN_KEY];\n\t\tconst traceId = carrier?.[TRACE_KEY];\n\t\t// Carriers come from other processes: only their two strings are read, else the root.\n\t\tif (typeof id !== \"string\" || typeof traceId !== \"string\") return this;\n\t\tconst identity = { id, traceId };\n\t\tconst parent: TelemetryContext = {\n\t\t\tmetrics: this.metrics,\n\t\t\tpropagation: this,\n\t\t\tstartSpan: (options, callback) => this.#start(identity, options, callback),\n\t\t};\n\t\tidentities.set(parent, identity);\n\t\treturn parent;\n\t}\n\n\t/**\n\t * Takes the queued spans (at most `limit`, the oldest) and the metric intervals that are over (every one with\n\t * `partial`); the spans keep counting against the capacity until `release`.\n\t */\n\ttake(partial: boolean, limit = Number.POSITIVE_INFINITY): TelemetryBatch {\n\t\tconst spans = this.#spans.length <= limit ? this.#spans : this.#spans.slice(0, limit);\n\t\tthis.#spans = spans === this.#spans ? [] : this.#spans.slice(limit);\n\t\tthis.#inFlight = spans.length;\n\t\tconst metrics: StoredMetric[] = [];\n\t\tconst current = intervalOf(Date.now());\n\t\tfor (const [key, { key: _series, ...metric }] of this.#measurements) {\n\t\t\tif (!partial && metric.intervalMs >= current) continue;\n\t\t\tmetrics.push(metric);\n\t\t\tthis.#measurements.delete(key);\n\t\t}\n\t\tthis.#inFlightMeasurements = metrics.length;\n\t\treturn { spans, metrics };\n\t}\n\n\t/** The batch taken last was written or given up: its capacity is free again. */\n\trelease(): void {\n\t\tthis.#inFlight = 0;\n\t\tthis.#inFlightMeasurements = 0;\n\t}\n\n\t/** How many settled spans wait to be taken. */\n\tget queuedSpans(): number {\n\t\treturn this.#spans.length;\n\t}\n\n\t/** Whether spans, or metric intervals that are over (all of them with `partial`), wait to be taken. */\n\tpending(partial: boolean): boolean {\n\t\tif (this.#spans.length > 0) return true;\n\t\tconst current = intervalOf(Date.now());\n\t\tfor (const metric of this.#measurements.values()) if (partial || metric.intervalMs < current) return true;\n\t\treturn false;\n\t}\n\n\t/**\n\t * Queues spans and metric rows another process recorded (an ingest), within the capacity; returns how many spans\n\t * it queued (the rest dropped and counted).\n\t */\n\tingest(batch: TelemetryBatch): number {\n\t\tif (this.#stopped) return 0;\n\t\tlet queued = 0;\n\t\tfor (const span of batch.spans) {\n\t\t\tif (this.#spans.length + this.#inFlight >= this.#capacity) this.droppedSpans++;\n\t\t\telse {\n\t\t\t\tthis.#spans.push(span);\n\t\t\t\tqueued++;\n\t\t\t}\n\t\t}\n\t\tfor (const metric of batch.metrics) this.#merge(metric);\n\t\treturn queued;\n\t}\n\n\t/** Stops recording; with `discard`, what waits is dropped too (a failed store). */\n\tstop(discard: \"keep\" | \"discard\"): void {\n\t\tthis.#stopped = true;\n\t\tif (discard === \"discard\") {\n\t\t\tthis.#spans = [];\n\t\t\tthis.#measurements.clear();\n\t\t}\n\t}\n\n\t#inert<T>(options: SpanOptions, callback: (span: TelemetrySpan) => T | Promise<T>): Promise<T> {\n\t\treturn NOOP_TELEMETRY_CONTEXT.startSpan(options, (noop) =>\n\t\t\tcallback({\n\t\t\t\t...noop,\n\t\t\t\tmetrics: this.metrics,\n\t\t\t\tpropagation: this,\n\t\t\t\tstartSpan: (options, callback) => this.#inert(options, callback),\n\t\t\t}),\n\t\t);\n\t}\n\n\tasync #start<T>(\n\t\tparent: Identity | undefined,\n\t\toptions: SpanOptions,\n\t\tcallback: (span: TelemetrySpan) => T | Promise<T>,\n\t): Promise<T> {\n\t\tif (this.#stopped) return this.#inert(options, callback);\n\t\tlet attributes = copyAttributes(options.attributes);\n\t\tconst links: { traceId: string; spanId: string; attributes: SpanAttributes }[] = [];\n\t\tfor (const link of options.links ?? []) {\n\t\t\tconst copied = copyLink(link);\n\t\t\tif (copied) links.push(copied);\n\t\t}\n\t\tthis.#prefix ??= this.#scope();\n\t\tconst id = `${this.#prefix}:${++this.#sequence}`;\n\t\tconst identity = { id, traceId: parent?.traceId ?? id };\n\t\t// The start on the clock pi-telemetry's adapters share; the end and events by the monotonic clock from it.\n\t\tconst started = telemetryNow();\n\t\tconst clock = performance.now();\n\t\tconst events: { name: string; timeMs: number; attributes: SpanAttributes }[] = [];\n\t\tlet status: SpanStatus = { status: \"ok\" };\n\t\tlet explicit = false;\n\t\tlet settled = false;\n\t\tconst record = (action: () => void): void => {\n\t\t\tif (!settled && !this.#stopped) action();\n\t\t};\n\t\tconst span: TelemetrySpan = {\n\t\t\tmetrics: this.metrics,\n\t\t\tpropagation: this,\n\t\t\tstartSpan: (options, callback) =>\n\t\t\t\tsettled ? this.#inert(options, callback) : this.#start(identity, options, callback),\n\t\t\taddLink: (link) =>\n\t\t\t\trecord(() => {\n\t\t\t\t\tconst copied = copyLink(link);\n\t\t\t\t\tif (copied) links.push(copied);\n\t\t\t\t}),\n\t\t\taddEvent: (name, attrs) =>\n\t\t\t\trecord(() => {\n\t\t\t\t\tevents.push({\n\t\t\t\t\t\tname,\n\t\t\t\t\t\ttimeMs: microseconds(performance.now() - clock),\n\t\t\t\t\t\tattributes: copyAttributes(attrs),\n\t\t\t\t\t});\n\t\t\t\t}),\n\t\t\tsetAttributes: (attrs) =>\n\t\t\t\trecord(() => {\n\t\t\t\t\tattributes = { ...attributes, ...copyAttributes(attrs) };\n\t\t\t\t}),\n\t\t\tsetStatus: (value) =>\n\t\t\t\trecord(() => {\n\t\t\t\t\tstatus =\n\t\t\t\t\t\tvalue.status === \"error\" && value.error\n\t\t\t\t\t\t\t? { status: \"error\", error: { ...value.error } }\n\t\t\t\t\t\t\t: { status: value.status };\n\t\t\t\t\texplicit = true;\n\t\t\t\t}),\n\t\t};\n\t\tidentities.set(span, identity);\n\t\ttry {\n\t\t\treturn await callback(span);\n\t\t} catch (error) {\n\t\t\tif (!explicit)\n\t\t\t\tstatus =\n\t\t\t\t\terror instanceof Error\n\t\t\t\t\t\t? { status: \"error\", error: { name: error.name, message: error.message } }\n\t\t\t\t\t\t: { status: \"error\" };\n\t\t\tthrow error;\n\t\t} finally {\n\t\t\tsettled = true;\n\t\t\tif (!this.#stopped) {\n\t\t\t\tif (this.#spans.length + this.#inFlight >= this.#capacity) this.droppedSpans++;\n\t\t\t\telse\n\t\t\t\t\tthis.#spans.push({\n\t\t\t\t\t\tid,\n\t\t\t\t\t\ttraceId: identity.traceId,\n\t\t\t\t\t\t...(parent === undefined ? {} : { parentId: parent.id }),\n\t\t\t\t\t\tname: options.name,\n\t\t\t\t\t\tstartedMs: started,\n\t\t\t\t\t\tendedMs: microseconds(started + performance.now() - clock),\n\t\t\t\t\t\tattributes,\n\t\t\t\t\t\tevents,\n\t\t\t\t\t\tlinks,\n\t\t\t\t\t\tstatus,\n\t\t\t\t\t});\n\t\t\t}\n\t\t}\n\t}\n\n\t#measurement(\n\t\tkind: StoredMetric[\"kind\"],\n\t\tname: string,\n\t\toptions?: InstrumentOptions,\n\t): (value: number, attributes?: SpanAttributes) => void {\n\t\tconst unit = options?.unit;\n\t\treturn (value, attributes) => {\n\t\t\tif (this.#stopped) return;\n\t\t\tthis.#merge({\n\t\t\t\tintervalMs: intervalOf(Date.now()),\n\t\t\t\tname,\n\t\t\t\tkind,\n\t\t\t\t...(unit === undefined ? {} : { unit }),\n\t\t\t\tattributes: sortedAttributes(copyAttributes(attributes)),\n\t\t\t\tcount: 1,\n\t\t\t\tsum: value,\n\t\t\t\tmin: value,\n\t\t\t\tmax: value,\n\t\t\t});\n\t\t};\n\t}\n\n\t/** Adds `metric` to its series' pending interval (a new series within the capacity, else dropped and counted). */\n\t#merge(metric: StoredMetric): void {\n\t\tif (this.#stopped) return;\n\t\tconst key = seriesKey(metric);\n\t\tconst pendingKey = `${metric.intervalMs}:${key}`;\n\t\tconst previous = this.#measurements.get(pendingKey);\n\t\tif (!previous && this.#measurements.size + this.#inFlightMeasurements >= this.#capacity) {\n\t\t\tthis.droppedMeasurements++;\n\t\t\treturn;\n\t\t}\n\t\tthis.#measurements.set(pendingKey, {\n\t\t\t...metric,\n\t\t\tkey,\n\t\t\tcount: (previous?.count ?? 0) + metric.count,\n\t\t\tsum: (previous?.sum ?? 0) + metric.sum,\n\t\t\tmin: Math.min(previous?.min ?? metric.min, metric.min),\n\t\t\tmax: Math.max(previous?.max ?? metric.max, metric.max),\n\t\t});\n\t}\n}\n\n/** A metric's series: its name, kind, unit and attributes (sorted by key), as JSON. */\nexport function seriesKey(metric: StoredMetric): string {\n\treturn JSON.stringify([\n\t\tmetric.name,\n\t\tmetric.kind,\n\t\tmetric.unit ?? null,\n\t\tJSON.stringify(sortedAttributes(metric.attributes)),\n\t]);\n}\n\n/** The start of the metric interval `time` falls in. */\nfunction intervalOf(time: number): number {\n\treturn Math.floor(time / INTERVAL_MS) * INTERVAL_MS;\n}\n\n/** `attributes` with their keys in order (a series' attributes as stored). */\nexport function sortedAttributes(attributes: SpanAttributes): SpanAttributes {\n\treturn Object.fromEntries(\n\t\tObject.keys(attributes)\n\t\t\t.sort()\n\t\t\t.map((key) => [key, attributes[key]]),\n\t);\n}\n\n/** `ms` rounded to the microsecond, as span times are. */\nfunction microseconds(ms: number): number {\n\treturn Math.round(ms * 1000) / 1000;\n}\n\nfunction copyAttributes(attributes?: SpanAttributes): SpanAttributes {\n\treturn Object.fromEntries(\n\t\tObject.entries(attributes ?? {})\n\t\t\t.filter(([, value]) => value !== undefined)\n\t\t\t.map(([key, value]) => [key, Array.isArray(value) ? [...value] : value]),\n\t);\n}\n\nfunction copyLink(link: SpanLink): { traceId: string; spanId: string; attributes: SpanAttributes } | undefined {\n\tconst identity = identities.get(link.context);\n\treturn identity\n\t\t? { traceId: identity.traceId, spanId: identity.id, attributes: copyAttributes(link.attributes) }\n\t\t: undefined;\n}\n"]}

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

@@ -0,0 +1,14 @@
+import { type Context } from "../context/index.ts";
+import type { Principal } from "../data/index.ts";
+import type { Host } from "../host/index.ts";
+import type { TelemetryRecorder } from "./recorder.ts";
+/** A running sender: `send` sends one batch now (with `partial`, the metric intervals not over too), `stop` stops. */
+export type TelemetrySender = {
+    send(partial: boolean): Promise<void>;
+    stop(): void;
+};
+/** Sends a page's spans (never its metrics) to the server's `PageTelemetry`, at most `PAGE_BATCH_SPANS` a batch. */
+export declare function sendPageTelemetry<P extends Principal>(host: Host<P>, recorder: TelemetryRecorder, context: Context): TelemetrySender;
+/** Sends a worker's spans and metrics to the server's `WorkerTelemetry`, at most `WORKER_BATCH_ROWS` spans a batch. */
+export declare function sendWorkerTelemetry<P extends Principal>(host: Host<P>, recorder: TelemetryRecorder, context: Context): TelemetrySender;
+//# sourceMappingURL=sender.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sender.d.ts","sourceRoot":"","sources":["../../src/telemetry-ingest/sender.ts"],"names":[],"mappings":"AAKA,OAAO,EAAsB,KAAK,OAAO,EAAE,MAAM,qBAAqB,CAAC;AACvE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAE7C,OAAO,KAAK,EAAkB,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAEvE,sHAAsH;AACtH,MAAM,MAAM,eAAe,GAAG;IAC7B,IAAI,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC,IAAI,IAAI,IAAI,CAAC;CACb,CAAC;AAEF,oHAAoH;AACpH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,SAAS,EACpD,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,EACb,QAAQ,EAAE,iBAAiB,EAC3B,OAAO,EAAE,OAAO,GACd,eAAe,CAcjB;AAED,uHAAuH;AACvH,wBAAgB,mBAAmB,CAAC,CAAC,SAAS,SAAS,EACtD,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,EACb,QAAQ,EAAE,iBAAiB,EAC3B,OAAO,EAAE,OAAO,GACd,eAAe,CAgBjB"}

package/dist/telemetry-ingest/sender.js

@@ -0,0 +1,64 @@
+// How a page and a worker send what their recorder kept (decisions "Telemetry from browser pages", "The server is the
+// one place telemetry is stored"): their host holds the server's telemetry object over the link it has, and each send
+// takes one batch from the recorder and calls `ingest` with it; a batch that cannot be sent (no link, a refusal) is
+// given up, best effort. One send at a time; nothing is sent while the object is not bound.
+import { BACKGROUND_CONTEXT } from "../context/index.js";
+import { PAGE_BATCH_SPANS, PageTelemetry, WORKER_BATCH_ROWS, WorkerTelemetry } from "./batch.js";
+/** Sends a page's spans (never its metrics) to the server's `PageTelemetry`, at most `PAGE_BATCH_SPANS` a batch. */
+export function sendPageTelemetry(host, recorder, context) {
+    const held = host.hold(PageTelemetry, {}, context);
+    // Spans only: its metrics are taken with them and dropped.
+    const waiting = (_partial) => recorder.queuedSpans > 0;
+    return sender(recorder, PAGE_BATCH_SPANS, waiting, () => held.release(), (batch) => {
+        if (held.state.value.kind !== "live")
+            return undefined;
+        return held.ingest({ spans: batch.spans }, BACKGROUND_CONTEXT);
+    });
+}
+/** Sends a worker's spans and metrics to the server's `WorkerTelemetry`, at most `WORKER_BATCH_ROWS` spans a batch. */
+export function sendWorkerTelemetry(host, recorder, context) {
+    const held = host.hold(WorkerTelemetry, {}, context);
+    return sender(recorder, WORKER_BATCH_ROWS, (partial) => recorder.pending(partial), () => held.release(), (batch) => {
+        if (held.state.value.kind !== "live" || held.variant !== "worker")
+            return undefined;
+        // A batch takes at most `WORKER_BATCH_ROWS` metric rows; more series in one interval are dropped.
+        return held.ingest({ spans: batch.spans, metrics: batch.metrics.slice(0, WORKER_BATCH_ROWS) }, BACKGROUND_CONTEXT);
+    });
+}
+/**
+ * The send loop over `call`, which sends a batch, or answers `undefined` when it cannot now (the batch then waits); a
+ * send does nothing while `waiting` says nothing waits.
+ */
+function sender(recorder, limit, waiting, release, call) {
+    let sending;
+    let stopped = false;
+    const once = async (partial) => {
+        if (!waiting(partial))
+            return;
+        const batch = recorder.take(partial, limit);
+        const sent = call(batch);
+        if (sent === undefined) {
+            // Not bound now: the batch is queued again (at the back), within the recorder's bound.
+            recorder.release();
+            recorder.ingest(batch);
+            return;
+        }
+        // Best effort: a refused or lost batch is given up.
+        await sent.catch(() => { });
+        recorder.release();
+    };
+    return {
+        send: (partial) => {
+            if (stopped)
+                return Promise.resolve();
+            const next = (sending ?? Promise.resolve()).then(() => once(partial));
+            sending = next;
+            return next;
+        },
+        stop: () => {
+            stopped = true;
+            release();
+        },
+    };
+}
+//# sourceMappingURL=sender.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sender.js","sourceRoot":"","sources":["../../src/telemetry-ingest/sender.ts"],"names":[],"mappings":"AAAA,sHAAsH;AACtH,sHAAsH;AACtH,oHAAoH;AACpH,4FAA4F;AAE5F,OAAO,EAAE,kBAAkB,EAAgB,MAAM,qBAAqB,CAAC;AAGvE,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AASjG,oHAAoH;AACpH,MAAM,UAAU,iBAAiB,CAChC,IAAa,EACb,QAA2B,EAC3B,OAAgB;IAEhB,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,EAAE,EAAE,OAAO,CAAC,CAAC;IACnD,2DAA2D;IAC3D,MAAM,OAAO,GAAG,CAAC,QAAiB,EAAE,EAAE,CAAC,QAAQ,CAAC,WAAW,GAAG,CAAC,CAAC;IAChE,OAAO,MAAM,CACZ,QAAQ,EACR,gBAAgB,EAChB,OAAO,EACP,GAAG,EAAE,CAAC,IAAI,CAAC,OAAO,EAAE,EACpB,CAAC,KAAK,EAAE,EAAE;QACT,IAAI,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,KAAK,MAAM;YAAE,OAAO,SAAS,CAAC;QACvD,OAAO,IAAI,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,EAAE,kBAAkB,CAAC,CAAC;IAChE,CAAC,CACD,CAAC;AACH,CAAC;AAED,uHAAuH;AACvH,MAAM,UAAU,mBAAmB,CAClC,IAAa,EACb,QAA2B,EAC3B,OAAgB;IAEhB,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,eAAe,EAAE,EAAE,EAAE,OAAO,CAAC,CAAC;IACrD,OAAO,MAAM,CACZ,QAAQ,EACR,iBAAiB,EACjB,CAAC,OAAO,EAAE,EAAE,CAAC,QAAQ,CAAC,OAAO,CAAC,OAAO,CAAC,EACtC,GAAG,EAAE,CAAC,IAAI,CAAC,OAAO,EAAE,EACpB,CAAC,KAAK,EAAE,EAAE;QACT,IAAI,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,KAAK,MAAM,IAAI,IAAI,CAAC,OAAO,KAAK,QAAQ;YAAE,OAAO,SAAS,CAAC;QACpF,kGAAkG;QAClG,OAAO,IAAI,CAAC,MAAM,CACjB,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,iBAAiB,CAAC,EAAE,EAC1E,kBAAkB,CAClB,CAAC;IACH,CAAC,CACD,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,SAAS,MAAM,CACd,QAA2B,EAC3B,KAAa,EACb,OAAsC,EACtC,OAAmB,EACnB,IAA6D;IAE7D,IAAI,OAAkC,CAAC;IACvC,IAAI,OAAO,GAAG,KAAK,CAAC;IACpB,MAAM,IAAI,GAAG,KAAK,EAAE,OAAgB,EAAiB,EAAE;QACtD,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC;YAAE,OAAO;QAC9B,MAAM,KAAK,GAAG,QAAQ,CAAC,IAAI,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QAC5C,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC;QACzB,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACxB,uFAAuF;YACvF,QAAQ,CAAC,OAAO,EAAE,CAAC;YACnB,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YACvB,OAAO;QACR,CAAC;QACD,oDAAoD;QACpD,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;QAC3B,QAAQ,CAAC,OAAO,EAAE,CAAC;IACpB,CAAC,CAAC;IACF,OAAO;QACN,IAAI,EAAE,CAAC,OAAO,EAAE,EAAE;YACjB,IAAI,OAAO;gBAAE,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;YACtC,MAAM,IAAI,GAAG,CAAC,OAAO,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;YACtE,OAAO,GAAG,IAAI,CAAC;YACf,OAAO,IAAI,CAAC;QACb,CAAC;QACD,IAAI,EAAE,GAAG,EAAE;YACV,OAAO,GAAG,IAAI,CAAC;YACf,OAAO,EAAE,CAAC;QACX,CAAC;KACD,CAAC;AACH,CAAC","sourcesContent":["// How a page and a worker send what their recorder kept (decisions \"Telemetry from browser pages\", \"The server is the\n// one place telemetry is stored\"): their host holds the server's telemetry object over the link it has, and each send\n// takes one batch from the recorder and calls `ingest` with it; a batch that cannot be sent (no link, a refusal) is\n// given up, best effort. One send at a time; nothing is sent while the object is not bound.\n\nimport { BACKGROUND_CONTEXT, type Context } from \"../context/index.ts\";\nimport type { Principal } from \"../data/index.ts\";\nimport type { Host } from \"../host/index.ts\";\nimport { PAGE_BATCH_SPANS, PageTelemetry, WORKER_BATCH_ROWS, WorkerTelemetry } from \"./batch.ts\";\nimport type { TelemetryBatch, TelemetryRecorder } from \"./recorder.ts\";\n\n/** A running sender: `send` sends one batch now (with `partial`, the metric intervals not over too), `stop` stops. */\nexport type TelemetrySender = {\n\tsend(partial: boolean): Promise<void>;\n\tstop(): void;\n};\n\n/** Sends a page's spans (never its metrics) to the server's `PageTelemetry`, at most `PAGE_BATCH_SPANS` a batch. */\nexport function sendPageTelemetry<P extends Principal>(\n\thost: Host<P>,\n\trecorder: TelemetryRecorder,\n\tcontext: Context,\n): TelemetrySender {\n\tconst held = host.hold(PageTelemetry, {}, context);\n\t// Spans only: its metrics are taken with them and dropped.\n\tconst waiting = (_partial: boolean) => recorder.queuedSpans > 0;\n\treturn sender(\n\t\trecorder,\n\t\tPAGE_BATCH_SPANS,\n\t\twaiting,\n\t\t() => held.release(),\n\t\t(batch) => {\n\t\t\tif (held.state.value.kind !== \"live\") return undefined;\n\t\t\treturn held.ingest({ spans: batch.spans }, BACKGROUND_CONTEXT);\n\t\t},\n\t);\n}\n\n/** Sends a worker's spans and metrics to the server's `WorkerTelemetry`, at most `WORKER_BATCH_ROWS` spans a batch. */\nexport function sendWorkerTelemetry<P extends Principal>(\n\thost: Host<P>,\n\trecorder: TelemetryRecorder,\n\tcontext: Context,\n): TelemetrySender {\n\tconst held = host.hold(WorkerTelemetry, {}, context);\n\treturn sender(\n\t\trecorder,\n\t\tWORKER_BATCH_ROWS,\n\t\t(partial) => recorder.pending(partial),\n\t\t() => held.release(),\n\t\t(batch) => {\n\t\t\tif (held.state.value.kind !== \"live\" || held.variant !== \"worker\") return undefined;\n\t\t\t// A batch takes at most `WORKER_BATCH_ROWS` metric rows; more series in one interval are dropped.\n\t\t\treturn held.ingest(\n\t\t\t\t{ spans: batch.spans, metrics: batch.metrics.slice(0, WORKER_BATCH_ROWS) },\n\t\t\t\tBACKGROUND_CONTEXT,\n\t\t\t);\n\t\t},\n\t);\n}\n\n/**\n * The send loop over `call`, which sends a batch, or answers `undefined` when it cannot now (the batch then waits); a\n * send does nothing while `waiting` says nothing waits.\n */\nfunction sender(\n\trecorder: TelemetryRecorder,\n\tlimit: number,\n\twaiting: (partial: boolean) => boolean,\n\trelease: () => void,\n\tcall: (batch: TelemetryBatch) => Promise<unknown> | undefined,\n): TelemetrySender {\n\tlet sending: Promise<void> | undefined;\n\tlet stopped = false;\n\tconst once = async (partial: boolean): Promise<void> => {\n\t\tif (!waiting(partial)) return;\n\t\tconst batch = recorder.take(partial, limit);\n\t\tconst sent = call(batch);\n\t\tif (sent === undefined) {\n\t\t\t// Not bound now: the batch is queued again (at the back), within the recorder's bound.\n\t\t\trecorder.release();\n\t\t\trecorder.ingest(batch);\n\t\t\treturn;\n\t\t}\n\t\t// Best effort: a refused or lost batch is given up.\n\t\tawait sent.catch(() => {});\n\t\trecorder.release();\n\t};\n\treturn {\n\t\tsend: (partial) => {\n\t\t\tif (stopped) return Promise.resolve();\n\t\t\tconst next = (sending ?? Promise.resolve()).then(() => once(partial));\n\t\t\tsending = next;\n\t\t\treturn next;\n\t\t},\n\t\tstop: () => {\n\t\t\tstopped = true;\n\t\t\trelease();\n\t\t},\n\t};\n}\n"]}

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

@@ -1,5 +1,7 @@
-import { type TelemetryContext, type TelemetryMetrics, type TelemetryPropagation, type TelemetryStore } from "@earendil-works/pi-telemetry";
-import { type SqliteDatabase } from "../sqlite/index.ts";
+import type { TelemetryContext, TelemetryMetrics, TelemetryPropagation, TelemetryStore } from "@earendil-works/pi-telemetry";
+import type { SqliteDatabase } from "../sqlite/index.ts";
+import { type TelemetryBatch } from "../telemetry-ingest/recorder.ts";
+export type { TelemetryBatch } from "../telemetry-ingest/recorder.ts";
 export interface SqliteTelemetryOptions {
     /** Retain seven days by default. Cleanup runs in the flush transaction. */
     readonly retentionMs?: number;
@@ -12,13 +14,20 @@ export interface SqliteTelemetry extends TelemetryContext, TelemetryStore {
     readonly propagation: TelemetryPropagation;
     readonly droppedSpans: number;
     readonly droppedMeasurements: number;
+    /**
+     * Queues finished spans and metric rows another process recorded, written with the next flush (a span whose id is
+     * stored already is kept as it was); within the queue's bound, the rest dropped and counted. Returns how many
+     * spans it queued. Callers check what they pass: the store writes it as it is.
+     */
+    ingest(batch: TelemetryBatch): number;
     /** Persist settled spans and completed ten-second metric intervals. */
     flush(): Promise<void>;
     /** Stop recording and drain, including partial metric intervals. Does not close the database. */
     close(): Promise<void>;
 }
 /** Portable, buffered SQLite recorder. Recording never performs SQL; flush runs every second.
- * Only settled spans are stored. Metrics aggregate count/sum/min/max per ten-second interval.
- * A write failure permanently stops recording and is reported by flush and close. */
+ * Only settled spans are stored, their times in microseconds (`telemetryNow`). Metrics aggregate count/sum/min/max per
+ * ten-second interval. A store of an older version in `db` is migrated (version 2: span times from milliseconds to
+ * microseconds, rows kept). A write failure permanently stops recording and is reported by flush and close. */
 export declare function createSqliteTelemetry(db: SqliteDatabase, options?: SqliteTelemetryOptions): Promise<SqliteTelemetry>;
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/telemetry-sqlite/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAQN,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,EAEzB,KAAK,cAAc,EACnB,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAyB,KAAK,cAAc,EAAoB,MAAM,oBAAoB,CAAC;AAGlG,MAAM,WAAW,sBAAsB;IACtC,2EAA2E;IAC3E,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B;yEACqE;IACrE,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CACjC;AAED,MAAM,WAAW,eAAgB,SAAQ,gBAAgB,EAAE,cAAc;IACxE,QAAQ,CAAC,OAAO,EAAE,gBAAgB,CAAC;IACnC,QAAQ,CAAC,WAAW,EAAE,oBAAoB,CAAC;IAC3C,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,uEAAuE;IACvE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,iGAAiG;IACjG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB;AA4SD;;qFAEqF;AACrF,wBAAsB,qBAAqB,CAC1C,EAAE,EAAE,cAAc,EAClB,OAAO,GAAE,sBAA2B,GAClC,OAAO,CAAC,eAAe,CAAC,CAsB1B"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/telemetry-sqlite/index.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAGX,gBAAgB,EAChB,gBAAgB,EAChB,oBAAoB,EACpB,cAAc,EACd,MAAM,8BAA8B,CAAC;AACtC,OAAO,KAAK,EAAE,cAAc,EAAkB,MAAM,oBAAoB,CAAC;AACzE,OAAO,EAA+B,KAAK,cAAc,EAAqB,MAAM,iCAAiC,CAAC;AAItH,YAAY,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AAEtE,MAAM,WAAW,sBAAsB;IACtC,2EAA2E;IAC3E,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B;yEACqE;IACrE,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CACjC;AAED,MAAM,WAAW,eAAgB,SAAQ,gBAAgB,EAAE,cAAc;IACxE,QAAQ,CAAC,OAAO,EAAE,gBAAgB,CAAC;IACnC,QAAQ,CAAC,WAAW,EAAE,oBAAoB,CAAC;IAC3C,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC;;;;OAIG;IACH,MAAM,CAAC,KAAK,EAAE,cAAc,GAAG,MAAM,CAAC;IACtC,uEAAuE;IACvE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,iGAAiG;IACjG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB;AAwID;;;+GAG+G;AAC/G,wBAAsB,qBAAqB,CAC1C,EAAE,EAAE,cAAc,EAClB,OAAO,GAAE,sBAA2B,GAClC,OAAO,CAAC,eAAe,CAAC,CAK1B"}