@earendil-works/chord 1.4.0 → 1.5.1

package/dist/telemetry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.d.ts","sourceRoot":"","sources":["../src/telemetry.ts"],"names":[],"mappings":"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"}

package/dist/telemetry.js

@@ -0,0 +1,470 @@
+// Chord's telemetry (§29, slice 9): its typed schema (every span, event and metric Chord records, with their
+// attributes), and how its sites record through it: no span and no attribute object under the NOOP context, spans kept
+// open until an event ends them, failures with a fixed category, carriers for links, and the instruments of an
+// adapter's metrics made once.
+import { createTypedMetrics, createTypedSpanStarter, defineTelemetrySchema, NOOP_TELEMETRY_CONTEXT, NOOP_TELEMETRY_METRICS, } from "@earendil-works/pi-telemetry";
+import { isChordError } from "./data/index.js";
+const type = { type: "string", required: true, description: "The object type's name." };
+const host = {
+    type: "string",
+    required: true,
+    description: "The host that recorded the span: its address key (`list|groceries`), `client` without an address.",
+    cardinality: "high",
+};
+const principal = {
+    type: "string",
+    required: false,
+    description: "Whom the call was for: its principal key, unless the host's `principalAttributes` hook records other attributes.",
+    cardinality: "high",
+};
+const object = {
+    type: "string",
+    required: true,
+    description: "The object: its type, and its params key when it has params.",
+    cardinality: "high",
+};
+const member = { type: "string", required: true, description: "The method's name." };
+const outcome = (values) => ({ type: "string", values, description: "How it ended; a cancel is no error (status ok)." });
+const commit = {
+    description: "A commit of the span's object (documents and tables) inside the span's work.",
+    attributes: {
+        documents: { type: "number", required: true, description: "Documents the commit adopted." },
+        ops: { type: "number", required: true, description: "Ops of the documents' prepared changes." },
+        rows: {
+            type: "number",
+            required: true,
+            description: "Table rows its writes changed: a `put` one, an update or delete the rows its statement changed.",
+        },
+        duration: {
+            type: "number",
+            required: true,
+            description: "Milliseconds from the commit's start to its adoption.",
+        },
+    },
+};
+const retry = {
+    description: "A transient failure: the next attempt waits for its backoff.",
+    attributes: { backoff: { type: "number", required: true, description: "Milliseconds until the next attempt." } },
+};
+const park = {
+    description: "The attempt parked on a dependency that is not live.",
+    attributes: { cause: { type: "string", required: true, description: "`loading`, or the waiting cause's message." } },
+};
+const fate = {
+    description: "One object's fate in a reload.",
+    attributes: {
+        object,
+        fate: {
+            type: "string",
+            required: true,
+            values: ["restarted", "ended", "parked", "retried"],
+            description: "What the object did.",
+        },
+    },
+};
+/** Failed spans: `status: "error"` with one of these categories and the error's message (at most 500 characters). */
+const ERRORS = "The error's category (`call_failed`, `method_failed`, `relay_failed`, `hold_failed`, `activation_failed`, " +
+    "`open_failed`, `close_failed`, `load_failed`, `reload_failed`, `resolve_failed`, `routine_failed`, `job_failed`, " +
+    "`http_failed`, `trace_failed` for `ctx.trace`) and its message, " +
+    "at most 500 characters; a cancel keeps status ok.";
+/** Chord's span, event and metric vocabulary (§29). Ids (objects, holds, calls, address keys) are span attributes only. */
+export const CHORD_TELEMETRY_SCHEMA = defineTelemetrySchema({
+    version: 1,
+    spans: {
+        "chord.call": {
+            description: "A consumer's call of a remote object's method, from the call until its reply.",
+            parents: { kind: "any" },
+            startAttributes: {
+                "chord.host": host,
+                type,
+                member,
+                object,
+                "address.kind": { type: "string", required: true, description: "The kind of the provider's host." },
+                "chord.principal": principal,
+            },
+            endAttributes: { outcome: outcome(["ok", "error", "aborted"]) },
+            status: { default: "ok", errorWhen: ERRORS },
+        },
+        "chord.method": {
+            description: "A provider running a method: under the call's carrier (over a link) or the caller's span (same host).",
+            parents: { kind: "any" },
+            startAttributes: {
+                "chord.host": host,
+                type,
+                member,
+                object,
+                "principal.kind": { type: "string", required: true, description: "The ctx's principal kind, or `none`." },
+                "chord.principal": principal,
+            },
+            endAttributes: { outcome: outcome(["ok", "error", "aborted"]) },
+            events: { "chord.commit": commit },
+            status: { default: "ok", errorWhen: ERRORS },
+        },
+        "chord.relay": {
+            description: "A relay forwarding a hold (until it is held upstream) or a call (until its reply came back), under the arriving carrier.",
+            parents: { kind: "root_or_external" },
+            startAttributes: {
+                "chord.host": host,
+                type,
+                member: {
+                    type: "string",
+                    required: true,
+                    description: "`hold`, or a call's method as `#<index>` (a relay never knows names).",
+                },
+                "upstream.kind": { type: "string", required: true, description: "The kind of the upstream host." },
+            },
+            endAttributes: { outcome: outcome(["ok", "error", "aborted"]) },
+            status: { default: "ok", errorWhen: ERRORS },
+        },
+        "chord.hold": {
+            description: "A consumer's hold of a remote object, until its first `bound` or failure.",
+            parents: { kind: "any" },
+            startAttributes: {
+                "chord.host": host,
+                type,
+                object,
+                "address.kind": { type: "string", required: true, description: "The kind of the provider's host." },
+            },
+            endAttributes: { outcome: outcome(["bound", "failed", "ended"]) },
+            status: { default: "ok", errorWhen: ERRORS },
+        },
+        "chord.activate": {
+            description: "One activation attempt until it is live, failed, parked or ended (a parked one resumes in a new span); linked to its object's first trigger.",
+            parents: { kind: "root_or_external" },
+            startAttributes: {
+                "chord.host": host,
+                type,
+                object,
+                attempt: { type: "number", required: true, description: "The object's attempt, from 1." },
+            },
+            endAttributes: { outcome: outcome(["live", "failed", "parked", "ended"]) },
+            events: { "chord.park": park, "chord.retry": retry },
+            status: { default: "ok", errorWhen: ERRORS },
+        },
+        "chord.open": {
+            description: "One native's open, under its attempt's span.",
+            parents: { kind: "spans", spans: ["chord.activate"] },
+            startAttributes: {
+                "chord.host": host,
+                type,
+                native: { type: "number", required: true, description: "The native's position, from 1." },
+            },
+            endAttributes: {},
+            status: { default: "ok", errorWhen: ERRORS },
+        },
+        "chord.close": {
+            description: "One native's close (a root: it runs at its attempt's teardown).",
+            parents: { kind: "root_or_external" },
+            startAttributes: {
+                "chord.host": host,
+                type,
+                native: { type: "number", required: true, description: "The native's position, from 1." },
+                reason: { type: "string", required: true, values: ["end", "close", "reload"], description: "Why." },
+            },
+            endAttributes: {},
+            status: { default: "ok", errorWhen: ERRORS },
+        },
+        "chord.load": {
+            description: "A host's `load`: the setups, the publication and the start barrier.",
+            parents: { kind: "any" },
+            startAttributes: {
+                "chord.host": host,
+                plugins: { type: "number", required: true, description: "Plugins given." },
+            },
+            endAttributes: { failed: { type: "number", description: "Plugins left out." } },
+            status: { default: "ok", errorWhen: ERRORS },
+        },
+        "chord.reload": {
+            description: "A host's `reload`: staging, the commit and every object's fate.",
+            parents: { kind: "any" },
+            startAttributes: {
+                "chord.host": host,
+                plugins: { type: "number", required: true, description: "Plugins given." },
+            },
+            endAttributes: {
+                added: { type: "number", description: "Plugins added." },
+                changed: { type: "number", description: "Plugins changed." },
+                removed: { type: "number", description: "Plugins removed." },
+                failed: { type: "number", description: "Plugins whose new code failed." },
+                fates: { type: "number", description: "Objects that took a fate." },
+            },
+            events: { "chord.reload.fate": fate },
+            status: { default: "ok", errorWhen: ERRORS },
+        },
+        "chord.resolve": {
+            description: "A route resolving an address (a worker start included), linked to its first trigger.",
+            parents: { kind: "root_or_external" },
+            startAttributes: {
+                "chord.host": host,
+                kind: { type: "string", required: true, description: "The host kind." },
+                address: { type: "string", required: true, description: "The address key.", cardinality: "high" },
+            },
+            endAttributes: { outcome: outcome(["linked", "failed"]) },
+            status: { default: "ok", errorWhen: ERRORS },
+        },
+        "chord.revoke": {
+            description: "A revocation on this host.",
+            parents: { kind: "any" },
+            startAttributes: { "chord.host": host },
+            endAttributes: { count: { type: "number", description: "Objects it ended and child links it closed." } },
+            status: { default: "ok", errorWhen: ERRORS },
+        },
+        "chord.routine": {
+            description: "One routine call (`self.on`, `self.onLive`), a root linked to the span of the commit that changed its source (when known); a throw's backoff a `chord.retry` event.",
+            parents: { kind: "root_or_external" },
+            startAttributes: {
+                "chord.host": host,
+                type,
+                object,
+                routine: { type: "string", required: true, values: ["on", "onLive"], description: "Its kind." },
+                position: { type: "number", required: true, description: "Its position among its kind, from 1." },
+            },
+            endAttributes: { outcome: outcome(["ok", "error", "aborted"]) },
+            events: { "chord.commit": commit, "chord.retry": retry },
+            status: { default: "ok", errorWhen: ERRORS },
+        },
+        "chord.job": {
+            description: "One phase of a job run: the intent (the start's transaction), the run, the finish; under the stored carrier (persisted) or the starter's span.",
+            parents: { kind: "any" },
+            startAttributes: {
+                "chord.host": host,
+                job: { type: "string", required: true, description: "The job's name." },
+                phase: { type: "string", required: true, values: ["intent", "run", "finish"], description: "The phase." },
+                object,
+                "job.id": { type: "string", required: false, description: "The run's id.", cardinality: "high" },
+            },
+            endAttributes: {
+                outcome: outcome(["ok", "error", "aborted"]),
+                "job.id": { type: "string", description: "The run's id, once the intent made it.", cardinality: "high" },
+            },
+            events: { "chord.commit": commit, "chord.retry": retry },
+            status: { default: "ok", errorWhen: ERRORS },
+        },
+        "chord.http": {
+            description: "An HTTP request routed to a contributed route (`chord/http`); its path is never recorded.",
+            parents: { kind: "root_or_external" },
+            startAttributes: {
+                "chord.host": host,
+                method: { type: "string", required: true, description: "The request's method." },
+                route: { type: "string", required: true, description: "The route's pattern." },
+            },
+            endAttributes: { status: { type: "number", description: "The response's status." } },
+            events: { "chord.commit": commit },
+            status: { default: "ok", errorWhen: ERRORS },
+        },
+    },
+    metrics: {
+        "chord.data.compilations": { kind: "counter", description: "Schemas compiled.", attributes: {} },
+        "chord.data.validations": { kind: "counter", description: "Values validated against a schema.", attributes: {} },
+        "chord.data.walks": { kind: "counter", description: "Full-value walks.", attributes: {} },
+        "chord.link.checks": {
+            kind: "counter",
+            description: "Messages checked against the message schema.",
+            attributes: {},
+        },
+        "chord.link.deflates": { kind: "counter", description: "Parts deflated.", attributes: {} },
+        "chord.link.inflates": { kind: "counter", description: "Parts inflated.", attributes: {} },
+        "chord.link.encodes": {
+            kind: "counter",
+            description: "Member values and ops encoded for a hold.",
+            attributes: {},
+        },
+        "chord.store.loads": { kind: "counter", description: "Persisted documents loaded.", attributes: {} },
+        "chord.store.commits": { kind: "counter", description: "Store commits.", attributes: {} },
+        "chord.store.statements": { kind: "counter", description: "SQL statements of store commits.", attributes: {} },
+        "chord.query.runs": { kind: "counter", description: "Live query runs.", attributes: {} },
+        "chord.cycle.visits": { kind: "counter", description: "Objects a cycle check visited.", attributes: {} },
+        "chord.derive.computes": { kind: "counter", description: "Derive computations.", attributes: {} },
+        "chord.derive.diffs": { kind: "counter", description: "Derive diffs.", attributes: {} },
+        "chord.registry.composes": { kind: "counter", description: "Registry compositions.", attributes: {} },
+        "chord.registry.adapts": {
+            kind: "counter",
+            description: "Registry values mapped for an older reader.",
+            attributes: {},
+        },
+        "chord.contract.adapts": { kind: "counter", description: "State mapped for an older consumer.", attributes: {} },
+        "chord.link.state_messages": {
+            kind: "counter",
+            description: "`state` messages this host sent of its own.",
+            attributes: {},
+        },
+        "chord.link.bytes": {
+            kind: "counter",
+            unit: "By",
+            description: "Bytes of encoded messages on this host's links (WebSocket frames, IPC messages).",
+            attributes: {
+                direction: { type: "string", required: true, values: ["sent", "received"], description: "Which way." },
+            },
+        },
+        "chord.commit.duration": {
+            kind: "histogram",
+            unit: "ms",
+            description: "Commits of an object's documents and tables, from their start to their adoption.",
+            attributes: {},
+        },
+        "chord.calls.in_flight": {
+            kind: "upDownCounter",
+            description: "Method calls running on this host.",
+            attributes: {},
+        },
+        "chord.holds.active": {
+            kind: "upDownCounter",
+            description: "Holds arriving over links and placed on this host.",
+            attributes: {},
+        },
+        "chord.links.open": { kind: "upDownCounter", description: "Open links of this host.", attributes: {} },
+        "chord.park.duration": {
+            kind: "histogram",
+            unit: "ms",
+            description: "How long an activation attempt stayed parked on its dependencies.",
+            attributes: {},
+        },
+        "chord.backpressure.wait": {
+            kind: "histogram",
+            unit: "ms",
+            description: "How long a link origin's state waited for a slot of its window.",
+            attributes: {},
+        },
+    },
+});
+/**
+ * Whether nothing under `parent` can be recorded: it starts spans as the NOOP context does (a host without an adapter, a
+ * context without a span, `countingOnly`'s). Span sites then start no span, build no attributes and inject no carrier
+ * (§30's cost: one call).
+ */
+export function untraced(parent) {
+    return parent.startSpan === NOOP_TELEMETRY_CONTEXT.startSpan;
+}
+/**
+ * A span recording nothing but carrying `metrics` (a host's adapter's): the telemetry of work a host does under a context
+ * without a span (its links' accepted by an app with `BACKGROUND_CONTEXT`), so the cost counters counted through that
+ * work's context reach the host's adapter (review L6). It starts no span: span sites treat it as untraced.
+ */
+export function countingOnly(metrics) {
+    return { ...NOOP_TELEMETRY_CONTEXT, metrics };
+}
+/** Chord's typed span starter under `parent` (for a recorded parent: it allocates). */
+export function chordSpans(parent) {
+    return createTypedSpanStarter(parent, [CHORD_TELEMETRY_SCHEMA]);
+}
+/**
+ * A span of work whose end is an event, not a return (a hold until bound, an attempt until its outcome, a call until
+ * its handler settled): open until `end`. Its `span` is the NOOP span until the adapter started it (Chord's adapters
+ * call back at once).
+ */
+export class OpenSpan {
+    #span = NOOP_TELEMETRY_CONTEXT;
+    #done = Promise.withResolvers();
+    #ended = false;
+    constructor(parent, name, attributes) {
+        void parent.startSpan({ name, attributes }, (span) => {
+            this.#span = span;
+            return this.#done.promise;
+        });
+    }
+    /** The span, typed by its schema entry. */
+    get span() {
+        // The adapter's span, recorded under `N`.
+        return this.#span;
+    }
+    /** Whether `end` ran. */
+    get ended() {
+        return this.#ended;
+    }
+    /** Ends the span (once; later calls do nothing). */
+    end() {
+        if (this.#ended)
+            return;
+        this.#ended = true;
+        this.#done.resolve();
+    }
+    /**
+     * Ends the span when `work` settles, its `outcome` set: `ok`, `aborted` (a cancel, `signal`'s or `aborted`: status
+     * ok) or `error` with `category`.
+     */
+    endWhen(work, category, signal) {
+        work.then(() => this.#close("ok"), (error) => this.#close(ended(this.#span, category, error, signal)));
+    }
+    #close(outcome) {
+        this.#span.setAttributes({ outcome });
+        this.end();
+    }
+}
+/**
+ * The longest string attribute Chord records that a peer chose (an object's label with its params key, an address key, a
+ * principal's kind): stores keep it for days (slice 9 review M1).
+ */
+const ATTRIBUTE_LENGTH = 256;
+/** `text` as a span attribute: its first 256 characters. */
+export function capped(text) {
+    return text.length > ATTRIBUTE_LENGTH ? text.slice(0, ATTRIBUTE_LENGTH) : text;
+}
+/** The `chord.host` attribute of the spans of a host at `address`: its key, `client` without one; capped. */
+export function hostAttribute(address) {
+    return capped(address?.key ?? "client");
+}
+/** The longest message a span's error or event carries (decision "Errors in telemetry"). */
+export const MAX_MESSAGE = 500;
+/** Marks `span` failed with `category` and `error`'s message (at most `MAX_MESSAGE` characters). */
+export function spanFailed(span, category, error) {
+    const message = error instanceof Error ? error.message : String(error);
+    span.setStatus({ status: "error", error: { name: category, message: message.slice(0, MAX_MESSAGE) } });
+}
+/**
+ * How work under `span` that threw `error` ended: `aborted` for a cancel (`signal` aborted, or Chord's `aborted`), its
+ * status set ok explicitly (an adapter marks a span failed when its callback throws); else `error`, the span failed
+ * with `category`. The outcome attribute is the caller's to set.
+ */
+export function ended(span, category, error, signal) {
+    if (signal?.aborted === true || isChordError(error, "aborted")) {
+        span.setStatus({ status: "ok" });
+        return "aborted";
+    }
+    spanFailed(span, category, error);
+    return "error";
+}
+/** The carrier of `span` for a link, when its adapter propagates; none under the NOOP context. */
+export function carrierOf(span) {
+    return untraced(span) ? undefined : span.propagation?.inject(span);
+}
+/** The parent `carrier` names on `adapter` (a host's), its root when absent or malformed; never throws. */
+export function parentOf(carrier, adapter) {
+    if (untraced(adapter))
+        return adapter;
+    return adapter.propagation?.extract(carrier) ?? adapter;
+}
+/** Chord's instruments on the NOOP metrics, shared: no adapter, nothing made per use. */
+const NOOP_METRICS = createTypedMetrics(NOOP_TELEMETRY_METRICS, [CHORD_TELEMETRY_SCHEMA]);
+/** Chord's instruments by the metrics object they record to (an adapter's), each made by its first use. */
+const instruments = new WeakMap();
+/** Chord's instruments on `metrics` (an adapter's, or none: NOOP), made once per metrics object and name. */
+export function chordMetrics(metrics) {
+    if (metrics === undefined || metrics === NOOP_TELEMETRY_METRICS)
+        return NOOP_METRICS;
+    let made = instruments.get(metrics);
+    if (made === undefined) {
+        made = cachedMetrics(createTypedMetrics(metrics, [CHORD_TELEMETRY_SCHEMA]));
+        instruments.set(metrics, made);
+    }
+    return made;
+}
+/** `typed` with each instrument made once per name. */
+function cachedMetrics(typed) {
+    const made = new Map();
+    const once = (name, make) => {
+        // Each name has one kind in the schema, so one instrument per name.
+        let instrument = made.get(name);
+        if (instrument === undefined) {
+            instrument = make();
+            made.set(name, instrument);
+        }
+        return instrument;
+    };
+    // The instruments `typed` makes, typed by its own signatures.
+    return {
+        counter: ((name) => once(name, () => typed.counter(name))),
+        upDownCounter: ((name) => once(name, () => typed.upDownCounter(name))),
+        histogram: ((name) => once(name, () => typed.histogram(name))),
+    };
+}
+//# sourceMappingURL=telemetry.js.map

package/dist/telemetry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.js","sourceRoot":"","sources":["../src/telemetry.ts"],"names":[],"mappings":"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","sourcesContent":["// Chord's telemetry (§29, slice 9): its typed schema (every span, event and metric Chord records, with their\n// attributes), and how its sites record through it: no span and no attribute object under the NOOP context, spans kept\n// open until an event ends them, failures with a fixed category, carriers for links, and the instruments of an\n// adapter's metrics made once.\n\nimport {\n\tcreateTypedMetrics,\n\tcreateTypedSpanStarter,\n\tdefineTelemetrySchema,\n\tNOOP_TELEMETRY_CONTEXT,\n\tNOOP_TELEMETRY_METRICS,\n\ttype SchemaTelemetryCounter,\n\ttype SchemaTelemetrySpan,\n\ttype TelemetryCarrier,\n\ttype TelemetryContext,\n\ttype TelemetryMetrics,\n\ttype TelemetrySchemaSpanName,\n\ttype TelemetrySchemaSpanStartAttributes,\n\ttype TelemetrySpan,\n\ttype TypedSpanStarter,\n\ttype TypedTelemetryMetrics,\n} from \"@earendil-works/pi-telemetry\";\nimport type { Address } from \"./contracts/index.ts\";\nimport { isChordError } from \"./data/index.ts\";\n\n/** A span of Chord's schema, its end attributes and events typed. */\nexport type ChordSpan<N extends ChordSpanName> = SchemaTelemetrySpan<typeof CHORD_TELEMETRY_SCHEMA, N>;\n\n/** The names of Chord's spans. */\nexport type ChordSpanName = TelemetrySchemaSpanName<typeof CHORD_TELEMETRY_SCHEMA>;\n\n/** Chord's instruments on one adapter's metrics, typed by its schema. */\nexport type ChordMetrics = TypedTelemetryMetrics<readonly [typeof CHORD_TELEMETRY_SCHEMA]>;\n\n/** One of Chord's counters (or up/down counters), its attributes typed. */\nexport type ChordCounter<N extends keyof (typeof CHORD_TELEMETRY_SCHEMA)[\"metrics\"]> = SchemaTelemetryCounter<\n\t(typeof CHORD_TELEMETRY_SCHEMA)[\"metrics\"][N]\n>;\n\nconst type = { type: \"string\", required: true, description: \"The object type's name.\" } as const;\n\nconst host = {\n\ttype: \"string\",\n\trequired: true,\n\tdescription: \"The host that recorded the span: its address key (`list|groceries`), `client` without an address.\",\n\tcardinality: \"high\",\n} as const;\n\nconst principal = {\n\ttype: \"string\",\n\trequired: false,\n\tdescription:\n\t\t\"Whom the call was for: its principal key, unless the host's `principalAttributes` hook records other attributes.\",\n\tcardinality: \"high\",\n} as const;\n\nconst object = {\n\ttype: \"string\",\n\trequired: true,\n\tdescription: \"The object: its type, and its params key when it has params.\",\n\tcardinality: \"high\",\n} as const;\n\nconst member = { type: \"string\", required: true, description: \"The method's name.\" } as const;\n\nconst outcome = (values: readonly string[]) =>\n\t({ type: \"string\", values, description: \"How it ended; a cancel is no error (status ok).\" }) as const;\n\nconst commit = {\n\tdescription: \"A commit of the span's object (documents and tables) inside the span's work.\",\n\tattributes: {\n\t\tdocuments: { type: \"number\", required: true, description: \"Documents the commit adopted.\" },\n\t\tops: { type: \"number\", required: true, description: \"Ops of the documents' prepared changes.\" },\n\t\trows: {\n\t\t\ttype: \"number\",\n\t\t\trequired: true,\n\t\t\tdescription: \"Table rows its writes changed: a `put` one, an update or delete the rows its statement changed.\",\n\t\t},\n\t\tduration: {\n\t\t\ttype: \"number\",\n\t\t\trequired: true,\n\t\t\tdescription: \"Milliseconds from the commit's start to its adoption.\",\n\t\t},\n\t},\n} as const;\n\nconst retry = {\n\tdescription: \"A transient failure: the next attempt waits for its backoff.\",\n\tattributes: { backoff: { type: \"number\", required: true, description: \"Milliseconds until the next attempt.\" } },\n} as const;\n\nconst park = {\n\tdescription: \"The attempt parked on a dependency that is not live.\",\n\tattributes: { cause: { type: \"string\", required: true, description: \"`loading`, or the waiting cause's message.\" } },\n} as const;\n\nconst fate = {\n\tdescription: \"One object's fate in a reload.\",\n\tattributes: {\n\t\tobject,\n\t\tfate: {\n\t\t\ttype: \"string\",\n\t\t\trequired: true,\n\t\t\tvalues: [\"restarted\", \"ended\", \"parked\", \"retried\"],\n\t\t\tdescription: \"What the object did.\",\n\t\t},\n\t},\n} as const;\n\n/** Failed spans: `status: \"error\"` with one of these categories and the error's message (at most 500 characters). */\nconst ERRORS =\n\t\"The error's category (`call_failed`, `method_failed`, `relay_failed`, `hold_failed`, `activation_failed`, \" +\n\t\"`open_failed`, `close_failed`, `load_failed`, `reload_failed`, `resolve_failed`, `routine_failed`, `job_failed`, \" +\n\t\"`http_failed`, `trace_failed` for `ctx.trace`) and its message, \" +\n\t\"at most 500 characters; a cancel keeps status ok.\";\n\n/** Chord's span, event and metric vocabulary (§29). Ids (objects, holds, calls, address keys) are span attributes only. */\nexport const CHORD_TELEMETRY_SCHEMA = defineTelemetrySchema({\n\tversion: 1,\n\tspans: {\n\t\t\"chord.call\": {\n\t\t\tdescription: \"A consumer's call of a remote object's method, from the call until its reply.\",\n\t\t\tparents: { kind: \"any\" },\n\t\t\tstartAttributes: {\n\t\t\t\t\"chord.host\": host,\n\t\t\t\ttype,\n\t\t\t\tmember,\n\t\t\t\tobject,\n\t\t\t\t\"address.kind\": { type: \"string\", required: true, description: \"The kind of the provider's host.\" },\n\t\t\t\t\"chord.principal\": principal,\n\t\t\t},\n\t\t\tendAttributes: { outcome: outcome([\"ok\", \"error\", \"aborted\"]) },\n\t\t\tstatus: { default: \"ok\", errorWhen: ERRORS },\n\t\t},\n\t\t\"chord.method\": {\n\t\t\tdescription:\n\t\t\t\t\"A provider running a method: under the call's carrier (over a link) or the caller's span (same host).\",\n\t\t\tparents: { kind: \"any\" },\n\t\t\tstartAttributes: {\n\t\t\t\t\"chord.host\": host,\n\t\t\t\ttype,\n\t\t\t\tmember,\n\t\t\t\tobject,\n\t\t\t\t\"principal.kind\": { type: \"string\", required: true, description: \"The ctx's principal kind, or `none`.\" },\n\t\t\t\t\"chord.principal\": principal,\n\t\t\t},\n\t\t\tendAttributes: { outcome: outcome([\"ok\", \"error\", \"aborted\"]) },\n\t\t\tevents: { \"chord.commit\": commit },\n\t\t\tstatus: { default: \"ok\", errorWhen: ERRORS },\n\t\t},\n\t\t\"chord.relay\": {\n\t\t\tdescription:\n\t\t\t\t\"A relay forwarding a hold (until it is held upstream) or a call (until its reply came back), under the arriving carrier.\",\n\t\t\tparents: { kind: \"root_or_external\" },\n\t\t\tstartAttributes: {\n\t\t\t\t\"chord.host\": host,\n\t\t\t\ttype,\n\t\t\t\tmember: {\n\t\t\t\t\ttype: \"string\",\n\t\t\t\t\trequired: true,\n\t\t\t\t\tdescription: \"`hold`, or a call's method as `#<index>` (a relay never knows names).\",\n\t\t\t\t},\n\t\t\t\t\"upstream.kind\": { type: \"string\", required: true, description: \"The kind of the upstream host.\" },\n\t\t\t},\n\t\t\tendAttributes: { outcome: outcome([\"ok\", \"error\", \"aborted\"]) },\n\t\t\tstatus: { default: \"ok\", errorWhen: ERRORS },\n\t\t},\n\t\t\"chord.hold\": {\n\t\t\tdescription: \"A consumer's hold of a remote object, until its first `bound` or failure.\",\n\t\t\tparents: { kind: \"any\" },\n\t\t\tstartAttributes: {\n\t\t\t\t\"chord.host\": host,\n\t\t\t\ttype,\n\t\t\t\tobject,\n\t\t\t\t\"address.kind\": { type: \"string\", required: true, description: \"The kind of the provider's host.\" },\n\t\t\t},\n\t\t\tendAttributes: { outcome: outcome([\"bound\", \"failed\", \"ended\"]) },\n\t\t\tstatus: { default: \"ok\", errorWhen: ERRORS },\n\t\t},\n\t\t\"chord.activate\": {\n\t\t\tdescription:\n\t\t\t\t\"One activation attempt until it is live, failed, parked or ended (a parked one resumes in a new span); linked to its object's first trigger.\",\n\t\t\tparents: { kind: \"root_or_external\" },\n\t\t\tstartAttributes: {\n\t\t\t\t\"chord.host\": host,\n\t\t\t\ttype,\n\t\t\t\tobject,\n\t\t\t\tattempt: { type: \"number\", required: true, description: \"The object's attempt, from 1.\" },\n\t\t\t},\n\t\t\tendAttributes: { outcome: outcome([\"live\", \"failed\", \"parked\", \"ended\"]) },\n\t\t\tevents: { \"chord.park\": park, \"chord.retry\": retry },\n\t\t\tstatus: { default: \"ok\", errorWhen: ERRORS },\n\t\t},\n\t\t\"chord.open\": {\n\t\t\tdescription: \"One native's open, under its attempt's span.\",\n\t\t\tparents: { kind: \"spans\", spans: [\"chord.activate\"] },\n\t\t\tstartAttributes: {\n\t\t\t\t\"chord.host\": host,\n\t\t\t\ttype,\n\t\t\t\tnative: { type: \"number\", required: true, description: \"The native's position, from 1.\" },\n\t\t\t},\n\t\t\tendAttributes: {},\n\t\t\tstatus: { default: \"ok\", errorWhen: ERRORS },\n\t\t},\n\t\t\"chord.close\": {\n\t\t\tdescription: \"One native's close (a root: it runs at its attempt's teardown).\",\n\t\t\tparents: { kind: \"root_or_external\" },\n\t\t\tstartAttributes: {\n\t\t\t\t\"chord.host\": host,\n\t\t\t\ttype,\n\t\t\t\tnative: { type: \"number\", required: true, description: \"The native's position, from 1.\" },\n\t\t\t\treason: { type: \"string\", required: true, values: [\"end\", \"close\", \"reload\"], description: \"Why.\" },\n\t\t\t},\n\t\t\tendAttributes: {},\n\t\t\tstatus: { default: \"ok\", errorWhen: ERRORS },\n\t\t},\n\t\t\"chord.load\": {\n\t\t\tdescription: \"A host's `load`: the setups, the publication and the start barrier.\",\n\t\t\tparents: { kind: \"any\" },\n\t\t\tstartAttributes: {\n\t\t\t\t\"chord.host\": host,\n\t\t\t\tplugins: { type: \"number\", required: true, description: \"Plugins given.\" },\n\t\t\t},\n\t\t\tendAttributes: { failed: { type: \"number\", description: \"Plugins left out.\" } },\n\t\t\tstatus: { default: \"ok\", errorWhen: ERRORS },\n\t\t},\n\t\t\"chord.reload\": {\n\t\t\tdescription: \"A host's `reload`: staging, the commit and every object's fate.\",\n\t\t\tparents: { kind: \"any\" },\n\t\t\tstartAttributes: {\n\t\t\t\t\"chord.host\": host,\n\t\t\t\tplugins: { type: \"number\", required: true, description: \"Plugins given.\" },\n\t\t\t},\n\t\t\tendAttributes: {\n\t\t\t\tadded: { type: \"number\", description: \"Plugins added.\" },\n\t\t\t\tchanged: { type: \"number\", description: \"Plugins changed.\" },\n\t\t\t\tremoved: { type: \"number\", description: \"Plugins removed.\" },\n\t\t\t\tfailed: { type: \"number\", description: \"Plugins whose new code failed.\" },\n\t\t\t\tfates: { type: \"number\", description: \"Objects that took a fate.\" },\n\t\t\t},\n\t\t\tevents: { \"chord.reload.fate\": fate },\n\t\t\tstatus: { default: \"ok\", errorWhen: ERRORS },\n\t\t},\n\t\t\"chord.resolve\": {\n\t\t\tdescription: \"A route resolving an address (a worker start included), linked to its first trigger.\",\n\t\t\tparents: { kind: \"root_or_external\" },\n\t\t\tstartAttributes: {\n\t\t\t\t\"chord.host\": host,\n\t\t\t\tkind: { type: \"string\", required: true, description: \"The host kind.\" },\n\t\t\t\taddress: { type: \"string\", required: true, description: \"The address key.\", cardinality: \"high\" },\n\t\t\t},\n\t\t\tendAttributes: { outcome: outcome([\"linked\", \"failed\"]) },\n\t\t\tstatus: { default: \"ok\", errorWhen: ERRORS },\n\t\t},\n\t\t\"chord.revoke\": {\n\t\t\tdescription: \"A revocation on this host.\",\n\t\t\tparents: { kind: \"any\" },\n\t\t\tstartAttributes: { \"chord.host\": host },\n\t\t\tendAttributes: { count: { type: \"number\", description: \"Objects it ended and child links it closed.\" } },\n\t\t\tstatus: { default: \"ok\", errorWhen: ERRORS },\n\t\t},\n\t\t\"chord.routine\": {\n\t\t\tdescription:\n\t\t\t\t\"One routine call (`self.on`, `self.onLive`), a root linked to the span of the commit that changed its source (when known); a throw's backoff a `chord.retry` event.\",\n\t\t\tparents: { kind: \"root_or_external\" },\n\t\t\tstartAttributes: {\n\t\t\t\t\"chord.host\": host,\n\t\t\t\ttype,\n\t\t\t\tobject,\n\t\t\t\troutine: { type: \"string\", required: true, values: [\"on\", \"onLive\"], description: \"Its kind.\" },\n\t\t\t\tposition: { type: \"number\", required: true, description: \"Its position among its kind, from 1.\" },\n\t\t\t},\n\t\t\tendAttributes: { outcome: outcome([\"ok\", \"error\", \"aborted\"]) },\n\t\t\tevents: { \"chord.commit\": commit, \"chord.retry\": retry },\n\t\t\tstatus: { default: \"ok\", errorWhen: ERRORS },\n\t\t},\n\t\t\"chord.job\": {\n\t\t\tdescription:\n\t\t\t\t\"One phase of a job run: the intent (the start's transaction), the run, the finish; under the stored carrier (persisted) or the starter's span.\",\n\t\t\tparents: { kind: \"any\" },\n\t\t\tstartAttributes: {\n\t\t\t\t\"chord.host\": host,\n\t\t\t\tjob: { type: \"string\", required: true, description: \"The job's name.\" },\n\t\t\t\tphase: { type: \"string\", required: true, values: [\"intent\", \"run\", \"finish\"], description: \"The phase.\" },\n\t\t\t\tobject,\n\t\t\t\t\"job.id\": { type: \"string\", required: false, description: \"The run's id.\", cardinality: \"high\" },\n\t\t\t},\n\t\t\tendAttributes: {\n\t\t\t\toutcome: outcome([\"ok\", \"error\", \"aborted\"]),\n\t\t\t\t\"job.id\": { type: \"string\", description: \"The run's id, once the intent made it.\", cardinality: \"high\" },\n\t\t\t},\n\t\t\tevents: { \"chord.commit\": commit, \"chord.retry\": retry },\n\t\t\tstatus: { default: \"ok\", errorWhen: ERRORS },\n\t\t},\n\t\t\"chord.http\": {\n\t\t\tdescription: \"An HTTP request routed to a contributed route (`chord/http`); its path is never recorded.\",\n\t\t\tparents: { kind: \"root_or_external\" },\n\t\t\tstartAttributes: {\n\t\t\t\t\"chord.host\": host,\n\t\t\t\tmethod: { type: \"string\", required: true, description: \"The request's method.\" },\n\t\t\t\troute: { type: \"string\", required: true, description: \"The route's pattern.\" },\n\t\t\t},\n\t\t\tendAttributes: { status: { type: \"number\", description: \"The response's status.\" } },\n\t\t\tevents: { \"chord.commit\": commit },\n\t\t\tstatus: { default: \"ok\", errorWhen: ERRORS },\n\t\t},\n\t},\n\tmetrics: {\n\t\t\"chord.data.compilations\": { kind: \"counter\", description: \"Schemas compiled.\", attributes: {} },\n\t\t\"chord.data.validations\": { kind: \"counter\", description: \"Values validated against a schema.\", attributes: {} },\n\t\t\"chord.data.walks\": { kind: \"counter\", description: \"Full-value walks.\", attributes: {} },\n\t\t\"chord.link.checks\": {\n\t\t\tkind: \"counter\",\n\t\t\tdescription: \"Messages checked against the message schema.\",\n\t\t\tattributes: {},\n\t\t},\n\t\t\"chord.link.deflates\": { kind: \"counter\", description: \"Parts deflated.\", attributes: {} },\n\t\t\"chord.link.inflates\": { kind: \"counter\", description: \"Parts inflated.\", attributes: {} },\n\t\t\"chord.link.encodes\": {\n\t\t\tkind: \"counter\",\n\t\t\tdescription: \"Member values and ops encoded for a hold.\",\n\t\t\tattributes: {},\n\t\t},\n\t\t\"chord.store.loads\": { kind: \"counter\", description: \"Persisted documents loaded.\", attributes: {} },\n\t\t\"chord.store.commits\": { kind: \"counter\", description: \"Store commits.\", attributes: {} },\n\t\t\"chord.store.statements\": { kind: \"counter\", description: \"SQL statements of store commits.\", attributes: {} },\n\t\t\"chord.query.runs\": { kind: \"counter\", description: \"Live query runs.\", attributes: {} },\n\t\t\"chord.cycle.visits\": { kind: \"counter\", description: \"Objects a cycle check visited.\", attributes: {} },\n\t\t\"chord.derive.computes\": { kind: \"counter\", description: \"Derive computations.\", attributes: {} },\n\t\t\"chord.derive.diffs\": { kind: \"counter\", description: \"Derive diffs.\", attributes: {} },\n\t\t\"chord.registry.composes\": { kind: \"counter\", description: \"Registry compositions.\", attributes: {} },\n\t\t\"chord.registry.adapts\": {\n\t\t\tkind: \"counter\",\n\t\t\tdescription: \"Registry values mapped for an older reader.\",\n\t\t\tattributes: {},\n\t\t},\n\t\t\"chord.contract.adapts\": { kind: \"counter\", description: \"State mapped for an older consumer.\", attributes: {} },\n\t\t\"chord.link.state_messages\": {\n\t\t\tkind: \"counter\",\n\t\t\tdescription: \"`state` messages this host sent of its own.\",\n\t\t\tattributes: {},\n\t\t},\n\t\t\"chord.link.bytes\": {\n\t\t\tkind: \"counter\",\n\t\t\tunit: \"By\",\n\t\t\tdescription: \"Bytes of encoded messages on this host's links (WebSocket frames, IPC messages).\",\n\t\t\tattributes: {\n\t\t\t\tdirection: { type: \"string\", required: true, values: [\"sent\", \"received\"], description: \"Which way.\" },\n\t\t\t},\n\t\t},\n\t\t\"chord.commit.duration\": {\n\t\t\tkind: \"histogram\",\n\t\t\tunit: \"ms\",\n\t\t\tdescription: \"Commits of an object's documents and tables, from their start to their adoption.\",\n\t\t\tattributes: {},\n\t\t},\n\t\t\"chord.calls.in_flight\": {\n\t\t\tkind: \"upDownCounter\",\n\t\t\tdescription: \"Method calls running on this host.\",\n\t\t\tattributes: {},\n\t\t},\n\t\t\"chord.holds.active\": {\n\t\t\tkind: \"upDownCounter\",\n\t\t\tdescription: \"Holds arriving over links and placed on this host.\",\n\t\t\tattributes: {},\n\t\t},\n\t\t\"chord.links.open\": { kind: \"upDownCounter\", description: \"Open links of this host.\", attributes: {} },\n\t\t\"chord.park.duration\": {\n\t\t\tkind: \"histogram\",\n\t\t\tunit: \"ms\",\n\t\t\tdescription: \"How long an activation attempt stayed parked on its dependencies.\",\n\t\t\tattributes: {},\n\t\t},\n\t\t\"chord.backpressure.wait\": {\n\t\t\tkind: \"histogram\",\n\t\t\tunit: \"ms\",\n\t\t\tdescription: \"How long a link origin's state waited for a slot of its window.\",\n\t\t\tattributes: {},\n\t\t},\n\t},\n});\n\n/**\n * Whether nothing under `parent` can be recorded: it starts spans as the NOOP context does (a host without an adapter, a\n * context without a span, `countingOnly`'s). Span sites then start no span, build no attributes and inject no carrier\n * (§30's cost: one call).\n */\nexport function untraced(parent: TelemetryContext): boolean {\n\treturn parent.startSpan === NOOP_TELEMETRY_CONTEXT.startSpan;\n}\n\n/**\n * A span recording nothing but carrying `metrics` (a host's adapter's): the telemetry of work a host does under a context\n * without a span (its links' accepted by an app with `BACKGROUND_CONTEXT`), so the cost counters counted through that\n * work's context reach the host's adapter (review L6). It starts no span: span sites treat it as untraced.\n */\nexport function countingOnly(metrics: TelemetryMetrics): TelemetrySpan {\n\treturn { ...NOOP_TELEMETRY_CONTEXT, metrics };\n}\n\n/** Chord's typed span starter under `parent` (for a recorded parent: it allocates). */\nexport function chordSpans(parent: TelemetryContext): TypedSpanStarter<readonly [typeof CHORD_TELEMETRY_SCHEMA]> {\n\treturn createTypedSpanStarter(parent, [CHORD_TELEMETRY_SCHEMA]);\n}\n\n/**\n * A span of work whose end is an event, not a return (a hold until bound, an attempt until its outcome, a call until\n * its handler settled): open until `end`. Its `span` is the NOOP span until the adapter started it (Chord's adapters\n * call back at once).\n */\nexport class OpenSpan<N extends ChordSpanName> {\n\t#span: TelemetrySpan = NOOP_TELEMETRY_CONTEXT;\n\treadonly #done = Promise.withResolvers<void>();\n\t#ended = false;\n\n\tconstructor(\n\t\tparent: TelemetryContext,\n\t\tname: N,\n\t\tattributes: TelemetrySchemaSpanStartAttributes<typeof CHORD_TELEMETRY_SCHEMA, N>,\n\t) {\n\t\tvoid parent.startSpan({ name, attributes }, (span) => {\n\t\t\tthis.#span = span;\n\t\t\treturn this.#done.promise;\n\t\t});\n\t}\n\n\t/** The span, typed by its schema entry. */\n\tget span(): ChordSpan<N> {\n\t\t// The adapter's span, recorded under `N`.\n\t\treturn this.#span as unknown as ChordSpan<N>;\n\t}\n\n\t/** Whether `end` ran. */\n\tget ended(): boolean {\n\t\treturn this.#ended;\n\t}\n\n\t/** Ends the span (once; later calls do nothing). */\n\tend(): void {\n\t\tif (this.#ended) return;\n\t\tthis.#ended = true;\n\t\tthis.#done.resolve();\n\t}\n\n\t/**\n\t * Ends the span when `work` settles, its `outcome` set: `ok`, `aborted` (a cancel, `signal`'s or `aborted`: status\n\t * ok) or `error` with `category`.\n\t */\n\tendWhen(work: Promise<unknown>, category: string, signal: AbortSignal | undefined): void {\n\t\twork.then(\n\t\t\t() => this.#close(\"ok\"),\n\t\t\t(error: unknown) => this.#close(ended(this.#span, category, error, signal)),\n\t\t);\n\t}\n\n\t#close(outcome: \"ok\" | \"aborted\" | \"error\"): void {\n\t\tthis.#span.setAttributes({ outcome });\n\t\tthis.end();\n\t}\n}\n\n/**\n * The longest string attribute Chord records that a peer chose (an object's label with its params key, an address key, a\n * principal's kind): stores keep it for days (slice 9 review M1).\n */\nconst ATTRIBUTE_LENGTH = 256;\n\n/** `text` as a span attribute: its first 256 characters. */\nexport function capped(text: string): string {\n\treturn text.length > ATTRIBUTE_LENGTH ? text.slice(0, ATTRIBUTE_LENGTH) : text;\n}\n\n/** The `chord.host` attribute of the spans of a host at `address`: its key, `client` without one; capped. */\nexport function hostAttribute(address: Address | undefined): string {\n\treturn capped(address?.key ?? \"client\");\n}\n\n/** The longest message a span's error or event carries (decision \"Errors in telemetry\"). */\nexport const MAX_MESSAGE = 500;\n\n/** Marks `span` failed with `category` and `error`'s message (at most `MAX_MESSAGE` characters). */\nexport function spanFailed(span: TelemetrySpan, category: string, error: unknown): void {\n\tconst message = error instanceof Error ? error.message : String(error);\n\tspan.setStatus({ status: \"error\", error: { name: category, message: message.slice(0, MAX_MESSAGE) } });\n}\n\n/**\n * How work under `span` that threw `error` ended: `aborted` for a cancel (`signal` aborted, or Chord's `aborted`), its\n * status set ok explicitly (an adapter marks a span failed when its callback throws); else `error`, the span failed\n * with `category`. The outcome attribute is the caller's to set.\n */\nexport function ended(\n\tspan: TelemetrySpan,\n\tcategory: string,\n\terror: unknown,\n\tsignal: AbortSignal | undefined,\n): \"aborted\" | \"error\" {\n\tif (signal?.aborted === true || isChordError(error, \"aborted\")) {\n\t\tspan.setStatus({ status: \"ok\" });\n\t\treturn \"aborted\";\n\t}\n\tspanFailed(span, category, error);\n\treturn \"error\";\n}\n\n/** The carrier of `span` for a link, when its adapter propagates; none under the NOOP context. */\nexport function carrierOf(span: TelemetryContext): TelemetryCarrier | undefined {\n\treturn untraced(span) ? undefined : span.propagation?.inject(span);\n}\n\n/** The parent `carrier` names on `adapter` (a host's), its root when absent or malformed; never throws. */\nexport function parentOf(carrier: TelemetryCarrier | undefined, adapter: TelemetryContext): TelemetryContext {\n\tif (untraced(adapter)) return adapter;\n\treturn adapter.propagation?.extract(carrier) ?? adapter;\n}\n\n/** Chord's instruments on the NOOP metrics, shared: no adapter, nothing made per use. */\nconst NOOP_METRICS = createTypedMetrics(NOOP_TELEMETRY_METRICS, [CHORD_TELEMETRY_SCHEMA]);\n\n/** Chord's instruments by the metrics object they record to (an adapter's), each made by its first use. */\nconst instruments = new WeakMap<TelemetryMetrics, ChordMetrics>();\n\n/** Chord's instruments on `metrics` (an adapter's, or none: NOOP), made once per metrics object and name. */\nexport function chordMetrics(metrics: TelemetryMetrics | undefined): ChordMetrics {\n\tif (metrics === undefined || metrics === NOOP_TELEMETRY_METRICS) return NOOP_METRICS;\n\tlet made = instruments.get(metrics);\n\tif (made === undefined) {\n\t\tmade = cachedMetrics(createTypedMetrics(metrics, [CHORD_TELEMETRY_SCHEMA]));\n\t\tinstruments.set(metrics, made);\n\t}\n\treturn made;\n}\n\n/** `typed` with each instrument made once per name. */\nfunction cachedMetrics(typed: ChordMetrics): ChordMetrics {\n\tconst made = new Map<string, unknown>();\n\tconst once = <T>(name: string, make: () => T): T => {\n\t\t// Each name has one kind in the schema, so one instrument per name.\n\t\tlet instrument = made.get(name) as T | undefined;\n\t\tif (instrument === undefined) {\n\t\t\tinstrument = make();\n\t\t\tmade.set(name, instrument);\n\t\t}\n\t\treturn instrument;\n\t};\n\t// The instruments `typed` makes, typed by its own signatures.\n\treturn {\n\t\tcounter: ((name: Parameters<ChordMetrics[\"counter\"]>[0]) =>\n\t\t\tonce(name, () => typed.counter(name))) as ChordMetrics[\"counter\"],\n\t\tupDownCounter: ((name: Parameters<ChordMetrics[\"upDownCounter\"]>[0]) =>\n\t\t\tonce(name, () => typed.upDownCounter(name))) as ChordMetrics[\"upDownCounter\"],\n\t\thistogram: ((name: Parameters<ChordMetrics[\"histogram\"]>[0]) =>\n\t\t\tonce(name, () => typed.histogram(name))) as ChordMetrics[\"histogram\"],\n\t};\n}\n"]}