@agoric/internal 0.4.0-u19.2 → 0.4.0-u20.0

package/src/metrics.d.ts

@@ -0,0 +1,183 @@
+export namespace HISTOGRAM_METRICS {
+    namespace swingset_crank_processing_time {
+        let description: "Processing time per crank (ms)";
+        let unit: "ms";
+        let boundaries: number[];
+    }
+    namespace swingset_block_processing_seconds {
+        let description_1: "Processing time per block";
+        export { description_1 as description };
+        let unit_1: "s";
+        export { unit_1 as unit };
+        export { HISTOGRAM_SECONDS_LATENCY_BOUNDARIES as boundaries };
+    }
+    namespace swingset_vat_startup {
+        let description_2: "Vat startup time (ms)";
+        export { description_2 as description };
+        let unit_2: "ms";
+        export { unit_2 as unit };
+        export { HISTOGRAM_MS_LATENCY_BOUNDARIES as boundaries };
+    }
+    namespace swingset_vat_delivery {
+        let description_3: "Vat delivery time (ms)";
+        export { description_3 as description };
+        let unit_3: "ms";
+        export { unit_3 as unit };
+        export { HISTOGRAM_MS_LATENCY_BOUNDARIES as boundaries };
+    }
+    namespace swingset_meter_usage {
+        let description_4: "Vat meter usage";
+        export { description_4 as description };
+        let unit_4: "ms";
+        export { unit_4 as unit };
+        export { HISTOGRAM_MS_LATENCY_BOUNDARIES as boundaries };
+    }
+}
+export namespace BLOCK_HISTOGRAM_METRICS {
+    namespace swingsetRunSeconds {
+        let unit_5: string;
+        export { unit_5 as unit };
+        export namespace advice {
+            let explicitBucketBoundaries: number[];
+        }
+        let description_5: "Per-block time spent executing SwingSet";
+        export { description_5 as description };
+    }
+    namespace swingsetChainSaveSeconds {
+        let unit_6: string;
+        export { unit_6 as unit };
+        export namespace advice_1 { }
+        export { advice_1 as advice };
+        let description_6: "Per-block time spent propagating SwingSet state into cosmos";
+        export { description_6 as description };
+    }
+    namespace swingsetCommitSeconds {
+        let unit_7: string;
+        export { unit_7 as unit };
+        export namespace advice_2 { }
+        export { advice_2 as advice };
+        let description_7: "Per-block time spent committing SwingSet state to host storage";
+        export { description_7 as description };
+    }
+    namespace cosmosCommitSeconds {
+        let unit_8: string;
+        export { unit_8 as unit };
+        export namespace advice_3 { }
+        export { advice_3 as advice };
+        let description_8: "Per-block time spent committing cosmos state";
+        export { description_8 as description };
+    }
+    namespace fullCommitSeconds {
+        let unit_9: string;
+        export { unit_9 as unit };
+        export namespace advice_4 { }
+        export { advice_4 as advice };
+        let description_9: "Per-block time spent committing state, inclusive of COMMIT_BLOCK processing plus time spent [outside of cosmic-swingset] before and after it";
+        export { description_9 as description };
+    }
+    namespace interBlockSeconds {
+        let unit_10: string;
+        export { unit_10 as unit };
+        export namespace advice_5 { }
+        export { advice_5 as advice };
+        let description_10: "Time spent idle between blocks";
+        export { description_10 as description };
+    }
+    namespace afterCommitHangoverSeconds {
+        let unit_11: string;
+        export { unit_11 as unit };
+        export namespace advice_6 { }
+        export { advice_6 as advice };
+        let description_11: "Per-block time spent waiting for previous-block afterCommit work";
+        export { description_11 as description };
+    }
+    namespace blockLagSeconds {
+        export namespace advice_7 {
+            let explicitBucketBoundaries_1: number[];
+            export { explicitBucketBoundaries_1 as explicitBucketBoundaries };
+        }
+        export { advice_7 as advice };
+        let unit_12: string;
+        export { unit_12 as unit };
+        let description_12: "The delay of each block from its expected begin time";
+        export { description_12 as description };
+    }
+}
+export type QueueMetricAspect = (typeof QueueMetricAspect)[keyof typeof QueueMetricAspect];
+export namespace QueueMetricAspect {
+    let Length: "length";
+    let IncrementCount: "increments";
+    let DecrementCount: "decrements";
+}
+export function makeQueueMetricsMeta(namePrefix: string, descPrefix: string): Record<QueueMetricAspect, {
+    name: string;
+    options: MetricAttributes;
+}>;
+export function makeQueueMetrics<QueueName extends string>({ otelMeter, namePrefix, descPrefix, console, }: {
+    otelMeter: OTelMeter;
+    namePrefix: string;
+    descPrefix: string;
+    console?: Pick<Console, "warn"> | undefined;
+}): QueueMetrics<QueueName>;
+/**
+ * @typedef KernelMetricMeta
+ * @property {string} key
+ * @property {string} name
+ * @property {{ dimension: string; value: string }} [sub]
+ * @property {string} description
+ * @property {boolean} [consensus]
+ * @property {MetricType} metricType
+ */
+/** @type {Omit<KernelMetricMeta, 'metricType'>[]} */
+export const KERNEL_STATS_SUM_METRICS: Omit<KernelMetricMeta, "metricType">[];
+/** @type {Omit<KernelMetricMeta, 'metricType'>[]} */
+export const KERNEL_STATS_UPDOWN_METRICS: Omit<KernelMetricMeta, "metricType">[];
+/** @type {KernelMetricMeta[]} */
+export const KERNEL_STATS_METRICS: KernelMetricMeta[];
+export type QueueMetrics<QueueName extends string> = {
+    /**
+     * must be
+     * called before any other function
+     */
+    initLengths: (lengths: Record<QueueName, number>) => void;
+    updateLengths: (lengths: Record<QueueName, number>) => void;
+    /**
+     * for a
+     * non-negative delta
+     */
+    incLength: (queue: QueueName, delta?: number) => void;
+    /**
+     * for a
+     * non-negative delta
+     */
+    decLength: (queue: QueueName, delta?: number) => void;
+};
+export type KernelMetricMeta = {
+    key: string;
+    name: string;
+    sub?: {
+        dimension: string;
+        value: string;
+    } | undefined;
+    description: string;
+    consensus?: boolean | undefined;
+    metricType: MetricType;
+};
+declare const HISTOGRAM_SECONDS_LATENCY_BOUNDARIES: number[];
+/**
+ * @import {Meter as OTelMeter, MetricAttributes} from '@opentelemetry/api';
+ * @import {TotalMap} from '@agoric/internal';
+ */
+declare const HISTOGRAM_MS_LATENCY_BOUNDARIES: number[];
+import type { MetricAttributes } from '@opentelemetry/api';
+import type { Meter as OTelMeter } from '@opentelemetry/api';
+/**
+ * MetricType
+ */
+type MetricType = (typeof MetricType)[keyof typeof MetricType];
+declare namespace MetricType {
+    let Counter: "counter";
+    let Gauge: "gauge";
+}
+export {};
+//# sourceMappingURL=metrics.d.ts.map

package/src/metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.d.ts","sourceRoot":"","sources":["metrics.js"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;4CAqH2C,MAAM,EAAE;;;;;;;;;;gCAQxC,CAAC,OAAO,iBAAiB,EAAE,MAAM,OAAO,iBAAiB,CAAC;;;;;;AAiB9D,iDAPI,MAAM,cACN,MAAM,GACJ,MAAM,CACd,iBAAiB,EACrB;IAAM,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,gBAAgB,CAAA;CAAE,CAC5C,CAoBH;AA0BM,iCARe,SAAS,SAAlB,MAAQ,mDAElB;IAA0B,SAAS,EAA3B,SAAS;IACM,UAAU,EAAzB,MAAM;IACS,UAAU,EAAzB,MAAM;IACyB,OAAO;CAC9C,GAAU,YAAY,CAAC,SAAS,CAAC,CA8GnC;AAQD;;;;;;;;GAQG;AACH,qDAAqD;AACrD,uCADW,IAAI,CAAC,gBAAgB,EAAE,YAAY,CAAC,EAAE,CAkF/C;AAEF,qDAAqD;AACrD,0CADW,IAAI,CAAC,gBAAgB,EAAE,YAAY,CAAC,EAAE,CA4D/C;AAGF,iCAAiC;AACjC,mCADW,gBAAgB,EAAE,CAI1B;yBA3SmB,SAAS,SAAlB,MAAQ;;;;;iBAEP,CAAC,OAAO,EAAE,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,KAAK,IAAI;mBAE5C,CAAC,OAAO,EAAE,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,KAAK,IAAI;;;;;eAC5C,CAAC,KAAK,EAAE,SAAS,EAAE,KAAK,CAAC,EAAE,MAAM,KAAK,IAAI;;;;;eAE1C,CAAC,KAAK,EAAE,SAAS,EAAE,KAAK,CAAC,EAAE,MAAM,KAAK,IAAI;;;SAsI1C,MAAM;UACN,MAAM;;mBACO,MAAM;eAAS,MAAM;;iBAClC,MAAM;;gBAEN,UAAU;;AAnRxB,6DACuD;AApBvD;;;GAGG;AAEH,wDAaE;sCAjBqD,oBAAoB;wCAApB,oBAAoB;;;;kBAyRhE,CAAC,OAAO,UAAU,EAAE,MAAM,OAAO,UAAU,CAAC"}

package/src/metrics.js

@@ -0,0 +1,476 @@
+/**
+ * @file Metadata about exported metrics. Note that any embedded unit
+ *   information should be provided as case-sensitive UCUM (e.g., `s` for
+ *   seconds, `ms` for milliseconds, `KiBy` for binary kilobytes [each being
+ *   1024 bytes]).
+ *
+ *   - https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/metrics.md#instrument-units
+ *   - https://ucum.org/ucum
+ *   - https://ucum.nlm.nih.gov/ucum-lhc/demo.html
+ *   - https://en.wikipedia.org/wiki/Unified_Code_for_Units_of_Measure
+ */
+
+import { q } from '@endo/errors';
+import { isNat } from '@endo/nat';
+
+/**
+ * @import {Meter as OTelMeter, MetricAttributes} from '@opentelemetry/api';
+ * @import {TotalMap} from '@agoric/internal';
+ */
+
+const HISTOGRAM_MS_LATENCY_BOUNDARIES = [
+  5,
+  10,
+  25,
+  50,
+  100,
+  250,
+  500,
+  1000,
+  2500,
+  5000,
+  10000,
+  Infinity,
+];
+const HISTOGRAM_SECONDS_LATENCY_BOUNDARIES =
+  HISTOGRAM_MS_LATENCY_BOUNDARIES.map(ms => ms / 1000);
+
+// TODO: Validate these boundaries. We're not going to have 5ms blocks, but
+// we probably care about the difference between 10 vs. 30 seconds.
+export const HISTOGRAM_METRICS = /** @type {const} */ ({
+  swingset_crank_processing_time: {
+    description: 'Processing time per crank (ms)',
+    unit: 'ms',
+    boundaries: Array.of(1, 11, 21, 31, 41, 51, 61, 71, 81, 91, Infinity),
+  },
+  swingset_block_processing_seconds: {
+    description: 'Processing time per block',
+    unit: 's',
+    boundaries: HISTOGRAM_SECONDS_LATENCY_BOUNDARIES,
+  },
+  swingset_vat_startup: {
+    description: 'Vat startup time (ms)',
+    unit: 'ms',
+    boundaries: HISTOGRAM_MS_LATENCY_BOUNDARIES,
+  },
+  swingset_vat_delivery: {
+    description: 'Vat delivery time (ms)',
+    unit: 'ms',
+    boundaries: HISTOGRAM_MS_LATENCY_BOUNDARIES,
+  },
+  swingset_meter_usage: {
+    description: 'Vat meter usage',
+    unit: 'ms',
+    boundaries: HISTOGRAM_MS_LATENCY_BOUNDARIES,
+  },
+});
+
+const blockHistogramMetricDesc = {
+  // Disabled because importing from @opentelemetry/api breaks kernel bundling.
+  // Thankfully, it's the default anyway:
+  // https://github.com/open-telemetry/opentelemetry-js/blob/f4dd2a1062f980cd344cfb172a515d00115df570/api/src/metrics/Metric.ts#L53-L57
+  // valueType: ValueType.DOUBLE,
+  unit: 's',
+  advice: {
+    explicitBucketBoundaries: [
+      0.1, 0.2, 0.3, 0.4, 0.5, 1, 2, 3, 4, 5, 6, 7, 10, 15, 30,
+    ],
+  },
+};
+export const BLOCK_HISTOGRAM_METRICS = /** @type {const} */ ({
+  swingsetRunSeconds: {
+    description: 'Per-block time spent executing SwingSet',
+    ...blockHistogramMetricDesc,
+  },
+  swingsetChainSaveSeconds: {
+    description: 'Per-block time spent propagating SwingSet state into cosmos',
+    ...blockHistogramMetricDesc,
+  },
+  swingsetCommitSeconds: {
+    description:
+      'Per-block time spent committing SwingSet state to host storage',
+    ...blockHistogramMetricDesc,
+  },
+  cosmosCommitSeconds: {
+    description: 'Per-block time spent committing cosmos state',
+    ...blockHistogramMetricDesc,
+  },
+  fullCommitSeconds: {
+    description:
+      'Per-block time spent committing state, inclusive of COMMIT_BLOCK processing plus time spent [outside of cosmic-swingset] before and after it',
+    ...blockHistogramMetricDesc,
+  },
+  interBlockSeconds: {
+    description: 'Time spent idle between blocks',
+    ...blockHistogramMetricDesc,
+  },
+  afterCommitHangoverSeconds: {
+    description:
+      'Per-block time spent waiting for previous-block afterCommit work',
+    ...blockHistogramMetricDesc,
+  },
+  blockLagSeconds: {
+    description: 'The delay of each block from its expected begin time',
+    ...blockHistogramMetricDesc,
+    // Add buckets for excessively long delays.
+    advice: {
+      ...blockHistogramMetricDesc.advice,
+      explicitBucketBoundaries: /** @type {number[]} */ ([
+        ...blockHistogramMetricDesc.advice.explicitBucketBoundaries,
+        ...[60, 120, 180, 240, 300, 600, 3600],
+      ]),
+    },
+  },
+});
+
+/** @enum {(typeof QueueMetricAspect)[keyof typeof QueueMetricAspect]} */
+export const QueueMetricAspect = /** @type {const} */ ({
+  Length: 'length',
+  IncrementCount: 'increments',
+  DecrementCount: 'decrements',
+});
+
+/**
+ * Queue metrics come in {length,add,remove} triples sharing a common prefix.
+ *
+ * @param {string} namePrefix
+ * @param {string} descPrefix
+ * @returns {Record<
+ *   QueueMetricAspect,
+ *   { name: string; options: MetricAttributes }
+ * >}
+ */
+export const makeQueueMetricsMeta = (namePrefix, descPrefix) => {
+  /** @type {[QueueMetricAspect, string, string][]} */
+  const metricsMeta = [
+    [QueueMetricAspect.Length, 'length', 'length'],
+    [QueueMetricAspect.IncrementCount, 'add', 'increments'],
+    [QueueMetricAspect.DecrementCount, 'remove', 'decrements'],
+  ];
+  const entries = metricsMeta.map(([aspect, nameSuffix, descSuffix]) => {
+    const name = `${namePrefix}_${nameSuffix}`;
+    const description = `${descPrefix} ${descSuffix}`;
+    // Future OpenTelemetry SDKs should also support creating Instruments with
+    // attribute keys (such as the "queue" attribute for
+    // "cosmic_swingset_inbound_queue_{length,add,remove}" measurements):
+    // https://opentelemetry.io/docs/specs/otel/metrics/api/#instrument-advisory-parameter-attributes
+    // At that time, a new field will be added to this record.
+    return [aspect, { name, options: { description } }];
+  });
+  return Object.fromEntries(entries);
+};
+
+/**
+ * @template {string} QueueName
+ * @typedef QueueMetrics
+ * @property {(lengths: Record<QueueName, number>) => void} initLengths must be
+ *   called before any other function
+ * @property {(lengths: Record<QueueName, number>) => void} updateLengths
+ * @property {(queue: QueueName, delta?: number) => void} incLength for a
+ *   non-negative delta
+ * @property {(queue: QueueName, delta?: number) => void} decLength for a
+ *   non-negative delta
+ */
+
+/**
+ * Create {length,add,remove} Instruments for a queue and return functions for
+ * consistently initializing and updating them.
+ *
+ * @template {string} QueueName
+ * @param {object} config
+ * @param {OTelMeter} config.otelMeter
+ * @param {string} config.namePrefix
+ * @param {string} config.descPrefix
+ * @param {Pick<Console, 'warn'>} [config.console]
+ * @returns {QueueMetrics<QueueName>}
+ */
+export const makeQueueMetrics = ({
+  otelMeter,
+  namePrefix,
+  descPrefix,
+  console,
+}) => {
+  const {
+    [QueueMetricAspect.Length]: lengthMeta,
+    [QueueMetricAspect.IncrementCount]: upMeta,
+    [QueueMetricAspect.DecrementCount]: downMeta,
+  } = makeQueueMetricsMeta(namePrefix, descPrefix);
+  // TODO: When it's deemed safe to change reported metrics, make upCounter and
+  // downCounter synchronous (and drop `increments` and `decrements` maps).
+  // We can't do so until then because it will add a "_total" suffix to the
+  // Prometheus export metric name, diverging from `makeInboundQueueMetrics` in
+  // packages/cosmic-swingset/src/kernel-stats.js.
+  // https://github.com/open-telemetry/opentelemetry-js/blob/main/doc/upgrade-to-2.x.md#-other-changes
+  const lengthCounter = otelMeter.createUpDownCounter(
+    lengthMeta.name,
+    lengthMeta.options,
+  );
+  // const upCounter = otelMeter.createCounter(upMeta.name, upMeta.options);
+  // const downCounter = otelMeter.createCounter(downMeta.name, downMeta.options);
+  const upCounter = otelMeter.createObservableCounter(
+    upMeta.name,
+    upMeta.options,
+  );
+  const downCounter = otelMeter.createObservableCounter(
+    downMeta.name,
+    downMeta.options,
+  );
+  const increments = /** @type {TotalMap<string, number>} */ (new Map());
+  const decrements = /** @type {TotalMap<string, number>} */ (new Map());
+  upCounter.addCallback(observer => {
+    for (const [queueName, value] of increments.entries()) {
+      observer.observe(value, { queue: queueName });
+    }
+  });
+  downCounter.addCallback(observer => {
+    for (const [queueName, value] of decrements.entries()) {
+      observer.observe(value, { queue: queueName });
+    }
+  });
+
+  let ready = false;
+  const lengths = /** @type {TotalMap<string, number>} */ (new Map());
+  const nudge = (queueName, delta, init = false) => {
+    if (!lengths.has(queueName)) {
+      if (!init) console?.warn('Unknown queue', queueName);
+      lengths.set(queueName, 0);
+      increments.set(queueName, 0);
+      decrements.set(queueName, 0);
+    }
+    const oldLength = lengths.get(queueName);
+    lengths.set(queueName, oldLength + delta);
+    const dimensions = { queue: queueName };
+    lengthCounter.add(delta, dimensions);
+    if (init) {
+      return;
+    } else if (delta > 0) {
+      // TODO per above: upCounter.add(delta, dimensions);
+      increments.set(queueName, (increments.get(queueName) || 0) + delta);
+    } else if (delta < 0) {
+      // TODO per above: downCounter.add(-delta, dimensions);
+      decrements.set(queueName, (decrements.get(queueName) || 0) - delta);
+    }
+    ready = true;
+  };
+
+  return harden({
+    initLengths: initialLengths => {
+      !ready ||
+        console?.warn(
+          `Unexpected repeat queue length initialization from ${q(lengths)} to ${q(initialLengths)}`,
+        );
+      for (const [queueName, newLength] of Object.entries(initialLengths)) {
+        if (!isNat(newLength)) {
+          console?.warn(`Invalid length for queue ${q(queueName)}:`, newLength);
+          continue;
+        }
+        nudge(queueName, newLength, true);
+      }
+    },
+    updateLengths: newLengths => {
+      ready || console?.warn('Missing initial queue lengths');
+      for (const [queueName, newLength] of Object.entries(newLengths)) {
+        if (!isNat(newLength)) {
+          console?.warn(`Invalid length for queue ${q(queueName)}:`, newLength);
+          continue;
+        }
+        nudge(queueName, newLength - (lengths.get(queueName) || 0));
+      }
+    },
+    incLength: (queueName, delta = 1) => {
+      if (!isNat(delta)) {
+        console?.warn(`Invalid increment for queue ${q(queueName)}:`, delta);
+        return;
+      }
+      nudge(queueName, delta);
+    },
+    decLength: (queueName, delta = 1) => {
+      if (!isNat(delta)) {
+        console?.warn(`Invalid decrement for queue ${q(queueName)}:`, delta);
+        return;
+      }
+      nudge(queueName, -delta);
+    },
+  });
+};
+
+// All the kernel metrics we are prepared for.
+/** @enum {(typeof MetricType)[keyof typeof MetricType]} MetricType */
+const MetricType = /** @type {const} */ ({
+  Counter: 'counter',
+  Gauge: 'gauge',
+});
+/**
+ * @typedef KernelMetricMeta
+ * @property {string} key
+ * @property {string} name
+ * @property {{ dimension: string; value: string }} [sub]
+ * @property {string} description
+ * @property {boolean} [consensus]
+ * @property {MetricType} metricType
+ */
+/** @type {Omit<KernelMetricMeta, 'metricType'>[]} */
+export const KERNEL_STATS_SUM_METRICS = [
+  {
+    key: 'syscalls',
+    name: 'swingset_all_syscall_total',
+    description: 'Total number of SwingSet kernel calls',
+  },
+  {
+    key: 'syscallSend',
+    name: 'swingset_syscall_total',
+    sub: { dimension: 'syscall', value: 'send' },
+    description: 'Total number of SwingSet message send kernel calls',
+  },
+  {
+    key: 'syscallCallNow',
+    name: 'swingset_syscall_total',
+    sub: { dimension: 'syscall', value: 'callNow' },
+    description: 'Total number of SwingSet synchronous device kernel calls',
+  },
+  {
+    key: 'syscallSubscribe',
+    name: 'swingset_syscall_total',
+    sub: { dimension: 'syscall', value: 'subscribe' },
+    description: 'Total number of SwingSet promise subscription kernel calls',
+  },
+  {
+    key: 'syscallResolve',
+    name: 'swingset_syscall_total',
+    sub: { dimension: 'syscall', value: 'resolve' },
+    description: 'Total number of SwingSet promise resolution kernel calls',
+  },
+  {
+    key: 'syscallExit',
+    name: 'swingset_syscall_total',
+    sub: { dimension: 'syscall', value: 'exit' },
+    description: 'Total number of SwingSet vat exit kernel calls',
+  },
+  {
+    key: 'syscallVatstoreGet',
+    name: 'swingset_syscall_total',
+    sub: { dimension: 'syscall', value: 'vatstoreGet' },
+    description: 'Total number of SwingSet vatstore get kernel calls',
+  },
+  {
+    key: 'syscallVatstoreSet',
+    name: 'swingset_syscall_total',
+    sub: { dimension: 'syscall', value: 'vatstoreSet' },
+    description: 'Total number of SwingSet vatstore set kernel calls',
+  },
+  {
+    key: 'syscallVatstoreGetNextKey',
+    name: 'swingset_syscall_total',
+    sub: { dimension: 'syscall', value: 'vatstoreGetNext' },
+    description: 'Total number of SwingSet vatstore getNextKey kernel calls',
+  },
+  {
+    key: 'syscallVatstoreDelete',
+    name: 'swingset_syscall_total',
+    sub: { dimension: 'syscall', value: 'vatstoreDelete' },
+    description: 'Total number of SwingSet vatstore delete kernel calls',
+  },
+  {
+    key: 'syscallDropImports',
+    name: 'swingset_syscall_total',
+    sub: { dimension: 'syscall', value: 'dropImports' },
+    description: 'Total number of SwingSet drop imports kernel calls',
+  },
+  {
+    key: 'dispatches',
+    name: 'swingset_dispatch_total',
+    description: 'Total number of SwingSet vat calls',
+  },
+  {
+    key: 'dispatchDeliver',
+    name: 'swingset_dispatch_deliver_total',
+    description: 'Total number of SwingSet vat message deliveries',
+  },
+  {
+    key: 'dispatchNotify',
+    name: 'swingset_dispatch_notify_total',
+    description: 'Total number of SwingSet vat promise notifications',
+  },
+];
+
+/** @type {Omit<KernelMetricMeta, 'metricType'>[]} */
+export const KERNEL_STATS_UPDOWN_METRICS = [
+  {
+    key: 'kernelObjects',
+    name: 'swingset_kernel_objects',
+    description: 'Active kernel objects',
+  },
+  {
+    key: 'kernelDevices',
+    name: 'swingset_kernel_devices',
+    description: 'Active kernel devices',
+  },
+  {
+    key: 'kernelPromises',
+    name: 'swingset_kernel_promises',
+    description: 'Active kernel promises',
+  },
+  {
+    key: 'kpUnresolved',
+    name: 'swingset_unresolved_kernel_promises',
+    description: 'Unresolved kernel promises',
+  },
+  {
+    key: 'kpFulfilled',
+    name: 'swingset_fulfilled_kernel_promises',
+    description: 'Fulfilled kernel promises',
+  },
+  {
+    key: 'kpRejected',
+    name: 'swingset_rejected_kernel_promises',
+    description: 'Rejected kernel promises',
+  },
+  {
+    key: 'runQueueLength',
+    name: 'swingset_run_queue_length',
+    consensus: true,
+    description: 'Length of the kernel run queue',
+  },
+  {
+    key: 'acceptanceQueueLength',
+    name: 'swingset_acceptance_queue_length',
+    consensus: true,
+    description: 'Length of the kernel acceptance queue',
+  },
+  {
+    key: 'promiseQueuesLength',
+    name: 'swingset_promise_queues_length',
+    consensus: true,
+    description: 'Combined length of all kernel promise queues',
+  },
+  {
+    key: 'clistEntries',
+    name: 'swingset_clist_entries',
+    description: 'Number of entries in the kernel c-list',
+  },
+  {
+    key: 'vats',
+    name: 'swingset_vats',
+    description: 'Number of active vats',
+  },
+];
+
+const { Counter, Gauge } = MetricType;
+/** @type {KernelMetricMeta[]} */
+export const KERNEL_STATS_METRICS = harden([
+  ...KERNEL_STATS_SUM_METRICS.map(m => ({ ...m, metricType: Counter })),
+  ...KERNEL_STATS_UPDOWN_METRICS.map(m => ({ ...m, metricType: Gauge })),
+]);
+
+// Ensure kernel stats key uniqueness.
+const kernelStatsKeys = new Map();
+for (const { key } of KERNEL_STATS_METRICS) {
+  kernelStatsKeys.set(key, (kernelStatsKeys.get(key) || 0) + 1);
+}
+const duplicateKernelStatsKeys = [...kernelStatsKeys.entries()].flatMap(
+  ([key, value]) => (value > 1 ? [key] : []),
+);
+if (duplicateKernelStatsKeys.length > 0) {
+  const msg = `Duplicate kernel stats keys ${JSON.stringify(duplicateKernelStatsKeys)}`;
+  throw Error(msg);
+}

package/src/module-utils.d.ts

@@ -0,0 +1,2 @@
+export function getSpecifier(fileUrl: string): Promise<string>;
+//# sourceMappingURL=module-utils.d.ts.map

package/src/module-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"module-utils.d.ts","sourceRoot":"","sources":["module-utils.js"],"names":[],"mappings":"AAaO,sCAHI,MAAM,GACJ,OAAO,CAAC,MAAM,CAAC,CAc3B"}

package/src/module-utils.js

@@ -0,0 +1,27 @@
+import { readFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import { search } from '@endo/compartment-mapper';
+import { Fail } from '@endo/errors';
+
+/**
+ * Given a file URL, return a deep import specifier that starts with the
+ * specifier for its containing module (e.g., the deep import specifier for this
+ * file is expected to be "@agoric/internal/src/module-utils.js").
+ *
+ * @param {string} fileUrl
+ * @returns {Promise<string>}
+ */
+export const getSpecifier = async fileUrl => {
+  // eslint-disable-next-line no-new
+  new URL(fileUrl); // validates fileUrl
+  const read = async location => {
+    const path = fileURLToPath(new URL(location, fileUrl));
+    return readFile(path);
+  };
+  const searchResult = await search(read, fileUrl);
+  const { packageDescriptorText, moduleSpecifier } = searchResult;
+  const { name } = JSON.parse(packageDescriptorText);
+  name || Fail`containing package must have a name`;
+  return `${name}/${moduleSpecifier.replace(/^\.\//, '')}`;
+};
+harden(getSpecifier);