@agoric/telemetry 0.6.3-dev-98f94b3.0 → 0.6.3-dev-7332d8b.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agoric/telemetry",
-  "version": "0.6.3-dev-98f94b3.0+98f94b3",
+  "version": "0.6.3-dev-7332d8b.0+7332d8b",
   "description": "Agoric's telemetry implementation",
   "type": "module",
   "repository": "https://github.com/Agoric/agoric-sdk",
@@ -22,8 +22,8 @@
   "author": "Agoric",
   "license": "Apache-2.0",
   "dependencies": {
-    "@agoric/internal": "0.3.3-dev-98f94b3.0+98f94b3",
-    "@agoric/store": "0.9.3-dev-98f94b3.0+98f94b3",
+    "@agoric/internal": "0.3.3-dev-7332d8b.0+7332d8b",
+    "@agoric/store": "0.9.3-dev-7332d8b.0+7332d8b",
     "@endo/errors": "^1.2.9",
     "@endo/init": "^1.1.8",
     "@endo/marshal": "^1.6.3",
@@ -68,5 +68,5 @@
   "typeCoverage": {
     "atLeast": 88.87
   },
-  "gitHead": "98f94b345cd8ddbcd5e80d77ed2703691635e3fc"
+  "gitHead": "7332d8bc8525e0b8d7723d9af9af6c1d97b98820"
 }

package/src/index.js

@@ -84,44 +84,37 @@ export const getResourceAttributes = ({
 
 /**
  * @typedef {object} Powers
- * @property {{ warn: Console['warn'] }} console
+ * @property {Pick<Console, 'warn'>} console
  * @property {NodeJS.ProcessEnv} env
  * @property {import('@opentelemetry/sdk-metrics').View[]} views
  * @property {string} [serviceName]
  */
 
 /**
- * @param {Partial<Powers>} param0
+ * @param {Partial<Powers>} powers
  */
-const getPrometheusMeterProvider = ({
+export const getPrometheusMeterProvider = ({
   console = globalThis.console,
   env = process.env,
   views,
   ...rest
 } = {}) => {
-  const { OTEL_EXPORTER_PROMETHEUS_PORT } = env;
-  if (!OTEL_EXPORTER_PROMETHEUS_PORT) {
-    // No Prometheus config, so don't install.
-    return undefined;
-  }
+  const { OTEL_EXPORTER_PROMETHEUS_HOST, OTEL_EXPORTER_PROMETHEUS_PORT } = env;
+
+  // The opt-in signal is a non-empty OTEL_EXPORTER_PROMETHEUS_PORT.
+  if (!OTEL_EXPORTER_PROMETHEUS_PORT) return;
 
   const resource = new Resource(getResourceAttributes({ env, ...rest }));
 
-  const port =
-    parseInt(OTEL_EXPORTER_PROMETHEUS_PORT || '', 10) ||
-    PrometheusExporter.DEFAULT_OPTIONS.port;
+  const { DEFAULT_OPTIONS } = PrometheusExporter;
+  const host = OTEL_EXPORTER_PROMETHEUS_HOST || DEFAULT_OPTIONS.host;
+  const port = +OTEL_EXPORTER_PROMETHEUS_PORT || DEFAULT_OPTIONS.port;
+  const url = `http://${host || '0.0.0.0'}:${port}${DEFAULT_OPTIONS.endpoint}`;
 
-  const exporter = new PrometheusExporter(
-    {
-      port,
-      appendTimestamp: true,
-    },
-    () => {
-      console.warn(
-        `Prometheus scrape endpoint: http://0.0.0.0:${port}${PrometheusExporter.DEFAULT_OPTIONS.endpoint}`,
-      );
-    },
-  );
+  const options = { host, port, appendTimestamp: true };
+  const exporter = new PrometheusExporter(options, () => {
+    console.warn(`Prometheus scrape endpoint: ${url}`);
+  });
 
   const provider = new MeterProvider({ resource, views });
   provider.addMetricReader(exporter);

package/src/make-slog-sender.js

@@ -1,13 +1,13 @@
 import path from 'path';
 import tmp from 'tmp';
-import { PromiseAllOrErrors } from '@agoric/internal';
+import { PromiseAllOrErrors, unprefixedProperties } from '@agoric/internal';
 import { serializeSlogObj } from './serialize-slog-obj.js';
 
+export const DEFAULT_SLOGSENDER_AGENT = 'self';
 export const DEFAULT_SLOGSENDER_MODULE =
   '@agoric/telemetry/src/flight-recorder.js';
 export const SLOGFILE_SENDER_MODULE = '@agoric/telemetry/src/slog-file.js';
-
-export const DEFAULT_SLOGSENDER_AGENT = 'self';
+export const PROMETHEUS_SENDER_MODULE = '@agoric/telemetry/src/prometheus.js';
 
 /** @import {SlogSender} from './index.js' */
 
@@ -19,6 +19,23 @@ export const DEFAULT_SLOGSENDER_AGENT = 'self';
 const filterTruthy = arr => /** @type {any[]} */ (arr.filter(Boolean));
 
 /**
+ * Create an aggregate slog sender that fans out inbound slog entries to modules
+ * as indicated by variables in the supplied `env` option. The SLOGSENDER value
+ * (or a default DEFAULT_SLOGSENDER_MODULE defined above) is split on commas
+ * into a list of module identifiers and adjusted by automatic insertions (a
+ * non-empty SLOGFILE value inserts DEFAULT_SLOGSENDER_AGENT defined above), and
+ * then each identifier is dynamically `import`ed for its own `makeSlogSender`
+ * export, which is invoked with a non-empty `stateDir` option and a modified
+ * `env` in which SLOGSENDER_AGENT_* variables have overridden their unprefixed
+ * equivalents to produce a subordinate slog sender.
+ * Subordinate slog senders remain isolated from each other, and any errors from
+ * them are caught and held until the next `forceFlush()` without disrupting
+ * any remaining slog entry fanout.
+ * If SLOGSENDER_AGENT is 'process', 'slog-sender-pipe.js' is used to load the
+ * subordinates in a child process rather than the main process.
+ * When there are no subordinates, the return value will be `undefined` rather
+ * than a slog sender function.
+ *
  * @type {import('./index.js').MakeSlogSender}
  */
 export const makeSlogSender = async (opts = {}) => {
@@ -26,95 +43,95 @@ export const makeSlogSender = async (opts = {}) => {
   const {
     SLOGSENDER = DEFAULT_SLOGSENDER_MODULE,
     SLOGSENDER_AGENT = DEFAULT_SLOGSENDER_AGENT,
+    // While cosmic-swingset/kernel code includes its own Prometheus metrics
+    // export, that trumps a slog sender module doing so.
+    // This extraction can be removed when that changes, but in the meantime,
+    // opt-in is only by SLOGSENDER_AGENT_OTEL_EXPORTER_PROMETHEUS_PORT.
+    OTEL_EXPORTER_PROMETHEUS_PORT: _prometheusExportPort,
     ...otherEnv
   } = env;
 
   const agentEnv = {
     ...otherEnv,
-    ...Object.fromEntries(
-      Object.entries(otherEnv)
-        .filter(([k]) => k.match(/^(?:SLOGSENDER_AGENT_)+/)) // narrow to SLOGSENDER_AGENT_ prefixes.
-        .map(([k, v]) => [k.replace(/^(?:SLOGSENDER_AGENT_)+/, ''), v]), // Rewrite SLOGSENDER_AGENT_ to un-prefixed version.
-    ),
+    ...unprefixedProperties(otherEnv, 'SLOGSENDER_AGENT_'),
   };
 
-  const slogSenderModules = [
-    ...new Set([
-      ...(agentEnv.SLOGFILE ? [SLOGFILE_SENDER_MODULE] : []),
-      ...SLOGSENDER.split(',')
-        .filter(Boolean)
-        .map(modulePath =>
-          modulePath.startsWith('.')
-            ? // Resolve relative to the current working directory.
-              path.resolve(modulePath)
-            : modulePath,
-        ),
-    ]),
-  ];
-
-  if (!slogSenderModules.length) {
+  const slogSenderModules = new Set();
+  if (agentEnv.OTEL_EXPORTER_PROMETHEUS_PORT) {
+    slogSenderModules.add(PROMETHEUS_SENDER_MODULE);
+  }
+  if (agentEnv.SLOGFILE) {
+    slogSenderModules.add(SLOGFILE_SENDER_MODULE);
+  }
+  for (const moduleIdentifier of filterTruthy(SLOGSENDER.split(','))) {
+    if (moduleIdentifier.startsWith('-')) {
+      // Opt out of an automatically-included sender.
+      slogSenderModules.delete(moduleIdentifier.slice(1));
+    } else if (moduleIdentifier.startsWith('.')) {
+      // Resolve relative to the current working directory.
+      slogSenderModules.add(path.resolve(moduleIdentifier));
+    } else {
+      slogSenderModules.add(moduleIdentifier);
+    }
+  }
+
+  if (!slogSenderModules.size) {
     return undefined;
   }
 
-  switch (SLOGSENDER_AGENT) {
-    case '':
-    case 'self':
-      break;
-    case 'process': {
-      console.warn('Loading slog sender in subprocess');
-      return import('./slog-sender-pipe.js').then(
-        async ({ makeSlogSender: makeSogSenderPipe }) =>
-          makeSogSenderPipe({
-            env: {
-              ...agentEnv,
-              SLOGSENDER,
-              SLOGSENDER_AGENT: 'self',
-            },
-            stateDir: stateDirOption,
-            ...otherOpts,
-          }),
-      );
-    }
-    case 'worker':
-    default:
-      console.warn(`Unknown SLOGSENDER_AGENT=${SLOGSENDER_AGENT}`);
+  if (SLOGSENDER_AGENT === 'process') {
+    console.warn('Loading slog sender in subprocess');
+    return import('./slog-sender-pipe.js').then(async module =>
+      module.makeSlogSender({
+        env: {
+          ...agentEnv,
+          SLOGSENDER,
+          SLOGSENDER_AGENT: 'self',
+        },
+        stateDir: stateDirOption,
+        ...otherOpts,
+      }),
+    );
+  } else if (SLOGSENDER_AGENT && SLOGSENDER_AGENT !== 'self') {
+    console.warn(
+      `Unknown SLOGSENDER_AGENT=${SLOGSENDER_AGENT}; defaulting to 'self'`,
+    );
   }
 
   if (SLOGSENDER) {
     console.warn('Loading slog sender modules:', ...slogSenderModules);
   }
 
-  const makersInfo = await Promise.all(
-    slogSenderModules.map(async moduleIdentifier =>
-      import(moduleIdentifier)
-        .then(
-          /** @param {{makeSlogSender: import('./index.js').MakeSlogSender}} module */ ({
-            makeSlogSender: maker,
-          }) => {
-            if (typeof maker !== 'function') {
-              return Promise.reject(
-                Error(`No 'makeSlogSender' function exported by module`),
-              );
-            } else if (maker === makeSlogSender) {
-              return Promise.reject(
-                Error(`Cannot recursively load 'makeSlogSender' aggregator`),
-              );
-            }
-
-            return /** @type {const} */ ([maker, moduleIdentifier]);
-          },
-        )
-        .catch(err => {
+  /** @type {Map<import('./index.js').MakeSlogSender, string>} */
+  const makerMap = new Map();
+  await Promise.all(
+    [...slogSenderModules].map(async moduleIdentifier => {
+      await null;
+      try {
+        const module = await import(moduleIdentifier);
+        const { makeSlogSender: maker } = module;
+        if (typeof maker !== 'function') {
+          throw Error(`No 'makeSlogSender' function exported by module`);
+        } else if (maker === makeSlogSender) {
+          throw Error(`Cannot recursively load 'makeSlogSender' aggregator`);
+        }
+        const isReplacing = makerMap.get(maker);
+        if (isReplacing) {
           console.warn(
-            `Failed to load slog sender from ${moduleIdentifier}.`,
-            err,
+            `The slog sender from ${moduleIdentifier} matches the one from ${isReplacing}.`,
           );
-          return undefined;
-        }),
-    ),
-  ).then(makerEntries => [...new Map(filterTruthy(makerEntries)).entries()]);
+        }
+        makerMap.set(maker, moduleIdentifier);
+      } catch (err) {
+        console.warn(
+          `Failed to load slog sender from ${moduleIdentifier}.`,
+          err,
+        );
+      }
+    }),
+  );
 
-  if (!makersInfo.length) {
+  if (!makerMap.size) {
     return undefined;
   }
 
@@ -122,11 +139,11 @@ export const makeSlogSender = async (opts = {}) => {
 
   if (stateDir === undefined) {
     stateDir = tmp.dirSync().name;
-    console.warn(`Using ${stateDir} for stateDir`);
+    console.warn(`Using ${stateDir} for slog sender stateDir`);
   }
 
   const senders = await Promise.all(
-    makersInfo.map(async ([maker, moduleIdentifier]) =>
+    [...makerMap.entries()].map(async ([maker, moduleIdentifier]) =>
       maker({
         ...otherOpts,
         stateDir,
@@ -137,37 +154,37 @@ export const makeSlogSender = async (opts = {}) => {
 
   if (!senders.length) {
     return undefined;
-  } else {
-    // Optimize creating a JSON serialization only if needed
-    // by any of the sender modules
-    const hasSenderUsingJsonObj = senders.some(
-      ({ usesJsonObject = true }) => usesJsonObject,
-    );
-    const getJsonObj = hasSenderUsingJsonObj
-      ? serializeSlogObj
-      : () => undefined;
-    const sendErrors = [];
-    /** @type {SlogSender} */
-    const slogSender = (slogObj, jsonObj = getJsonObj(slogObj)) => {
-      for (const sender of senders) {
-        try {
-          sender(slogObj, jsonObj);
-        } catch (err) {
-          sendErrors.push(err);
-        }
-      }
-    };
-    return Object.assign(slogSender, {
-      forceFlush: async () => {
-        await PromiseAllOrErrors([
-          ...senders.map(sender => sender.forceFlush?.()),
-          ...sendErrors.splice(0).map(err => Promise.reject(err)),
-        ]);
-      },
-      shutdown: async () => {
-        await PromiseAllOrErrors(senders.map(sender => sender.shutdown?.()));
-      },
-      usesJsonObject: hasSenderUsingJsonObj,
-    });
   }
+
+  // Optimize creating a JSON serialization only if needed
+  // by at least one of the senders.
+  const hasSenderUsingJsonObj = senders.some(
+    ({ usesJsonObject = true }) => usesJsonObject,
+  );
+  const getJsonObj = hasSenderUsingJsonObj ? serializeSlogObj : () => undefined;
+
+  const sendErrors = [];
+
+  /** @type {SlogSender} */
+  const slogSender = (slogObj, jsonObj = getJsonObj(slogObj)) => {
+    for (const sender of senders) {
+      try {
+        sender(slogObj, jsonObj);
+      } catch (err) {
+        sendErrors.push(err);
+      }
+    }
+  };
+  return Object.assign(slogSender, {
+    forceFlush: async () => {
+      await PromiseAllOrErrors([
+        ...senders.map(sender => sender.forceFlush?.()),
+        ...sendErrors.splice(0).map(err => Promise.reject(err)),
+      ]);
+    },
+    shutdown: async () => {
+      await PromiseAllOrErrors(senders.map(sender => sender.shutdown?.()));
+    },
+    usesJsonObject: hasSenderUsingJsonObj,
+  });
 };

package/src/otel-metrics.js

@@ -0,0 +1,223 @@
+import { q, Fail } from '@endo/errors';
+
+import * as ActionType from '@agoric/internal/src/action-types.js';
+import { objectMapMutable } from '@agoric/internal/src/js-utils.js';
+import {
+  HISTOGRAM_METRICS,
+  BLOCK_HISTOGRAM_METRICS,
+  KERNEL_STATS_METRICS,
+  makeQueueMetrics,
+} from '@agoric/internal/src/metrics.js';
+
+/**
+ * @import {MeterProvider, MetricOptions, ObservableCounter, ObservableUpDownCounter} from '@opentelemetry/api';
+ * @import {TotalMap} from '@agoric/internal';
+ */
+
+const knownActionTypes = new Set(Object.values(ActionType.QueuedActionType));
+
+/** @param {import('./index.js').MakeSlogSenderOptions & {otelMeterName: string, otelMeterProvider?: MeterProvider}} opts */
+export const makeSlogSender = async (opts = /** @type {any} */ ({})) => {
+  const { otelMeterName, otelMeterProvider } = opts;
+  if (!otelMeterName) throw Fail`OTel meter name is required`;
+  if (!otelMeterProvider) return;
+
+  const otelMeter = otelMeterProvider.getMeter(otelMeterName);
+
+  const processedInboundActionCounter = otelMeter.createCounter(
+    'cosmic_swingset_inbound_actions',
+    { description: 'Processed inbound action counts by type' },
+  );
+  const histograms = {
+    ...objectMapMutable(HISTOGRAM_METRICS, (desc, name) => {
+      const { boundaries, ...options } = desc;
+      const advice = boundaries && { explicitBucketBoundaries: boundaries };
+      return otelMeter.createHistogram(name, { ...options, advice });
+    }),
+    ...objectMapMutable(BLOCK_HISTOGRAM_METRICS, (desc, name) =>
+      otelMeter.createHistogram(name, desc),
+    ),
+  };
+
+  const inboundQueueMetrics = makeQueueMetrics({
+    otelMeter,
+    namePrefix: 'cosmic_swingset_inbound_queue',
+    descPrefix: 'inbound queue',
+    console,
+  });
+
+  // Values for KERNEL_STATS_METRICS could be built up locally by observing slog
+  // entries, but they are all collectively reported in "kernel-stats"
+  // (@see {@link ../../cosmic-swingset/src/kernel-stats.js exportKernelStats})
+  // and for now we just reflect that, which requires implementation as async
+  // ("observable") instruments rather than synchronous ones.
+  /** @typedef {string} KernelStatsKey */
+  /** @typedef {string} KernelMetricName */
+  /** @type {TotalMap<KernelStatsKey, number>} */
+  const kernelStats = new Map();
+  /** @type {Map<KernelMetricName, ObservableCounter | ObservableUpDownCounter>} */
+  const kernelStatsCounters = new Map();
+  for (const meta of KERNEL_STATS_METRICS) {
+    const { key, name, sub, metricType, ...options } = meta;
+    kernelStats.set(key, 0);
+    if (metricType === 'gauge') {
+      kernelStats.set(`${key}Up`, 0);
+      kernelStats.set(`${key}Down`, 0);
+      kernelStats.set(`${key}Max`, 0);
+    } else if (metricType !== 'counter') {
+      Fail`Unknown metric type ${q(metricType)} for key ${q(key)} name ${q(name)}`;
+    }
+    let counter = kernelStatsCounters.get(name);
+    if (!counter) {
+      counter =
+        metricType === 'counter'
+          ? otelMeter.createObservableCounter(name, options)
+          : otelMeter.createObservableUpDownCounter(name, options);
+      kernelStatsCounters.set(name, counter);
+    }
+    const attributes = sub ? { [sub.dimension]: sub.value } : {};
+    counter.addCallback(observer => {
+      observer.observe(kernelStats.get(key), attributes);
+    });
+  }
+  const expectedKernelStats = new Set(kernelStats.keys());
+
+  /**
+   * @typedef {object} LazyStats
+   * @property {string} namePrefix
+   * @property {MetricOptions} options
+   * @property {Set<string>} keys
+   * @property {Record<string, number>} data
+   */
+  /** @type {(namePrefix: string, description: string) => LazyStats} */
+  const makeLazyStats = (namePrefix, description) => {
+    return { namePrefix, options: { description }, keys: new Set(), data: {} };
+  };
+  const dynamicAfterCommitStatsCounters = {
+    memoryUsage: makeLazyStats(
+      'memoryUsage_',
+      'kernel process memory statistic',
+    ),
+    heapStats: makeLazyStats('heapStats_', 'v8 kernel heap statistic'),
+  };
+
+  const slogSender = ({ type: slogType, ...slogObj }) => {
+    switch (slogType) {
+      // Consume cosmic-swingset block lifecycle slog entries.
+      case 'cosmic-swingset-init': {
+        const { inboundQueueInitialLengths: lengths } = slogObj;
+        inboundQueueMetrics.initLengths(lengths);
+        break;
+      }
+      case 'cosmic-swingset-begin-block': {
+        const {
+          interBlockSeconds,
+          afterCommitHangoverSeconds,
+          blockLagSeconds,
+        } = slogObj;
+
+        Number.isFinite(interBlockSeconds) &&
+          histograms.interBlockSeconds.record(interBlockSeconds);
+        histograms.afterCommitHangoverSeconds.record(
+          afterCommitHangoverSeconds,
+        );
+        Number.isFinite(blockLagSeconds) &&
+          histograms.blockLagSeconds.record(blockLagSeconds);
+        break;
+      }
+      case 'cosmic-swingset-run-finish': {
+        histograms.swingset_block_processing_seconds.record(slogObj.seconds);
+        break;
+      }
+      case 'cosmic-swingset-end-block-finish': {
+        const { inboundQueueStartLengths, processedActionCounts } = slogObj;
+        inboundQueueMetrics.updateLengths(inboundQueueStartLengths);
+        for (const processedActionRecord of processedActionCounts) {
+          const { count, phase, type: actionType } = processedActionRecord;
+          if (!knownActionTypes.has(actionType)) {
+            console.warn('Unknown inbound action type', actionType);
+          }
+          processedInboundActionCounter.add(count, { actionType });
+          inboundQueueMetrics.decLength(phase);
+        }
+        break;
+      }
+      case 'cosmic-swingset-commit-block-finish': {
+        const {
+          runSeconds,
+          chainTime,
+          saveTime,
+          cosmosCommitSeconds,
+          fullSaveTime,
+        } = slogObj;
+        histograms.swingsetRunSeconds.record(runSeconds);
+        histograms.swingsetChainSaveSeconds.record(chainTime);
+        histograms.swingsetCommitSeconds.record(saveTime);
+        histograms.cosmosCommitSeconds.record(cosmosCommitSeconds);
+        histograms.fullCommitSeconds.record(fullSaveTime);
+        break;
+      }
+
+      // Consume Swingset kernel slog entries.
+      case 'vat-startup-finish': {
+        histograms.swingset_vat_startup.record(slogObj.seconds * 1000);
+        break;
+      }
+      case 'crank-finish': {
+        const { crankType, messageType, seconds } = slogObj;
+        // TODO: Reflect crankType/messageType as proper dimensional attributes.
+        // For now, we're going for parity with direct metrics.
+        if (crankType !== 'routing' && messageType !== 'create-vat') {
+          histograms.swingset_crank_processing_time.record(seconds * 1000);
+        }
+        break;
+      }
+
+      // Consume miscellaneous slog entries.
+      case 'kernel-stats': {
+        const { stats } = slogObj;
+        const notYetFoundKernelStats = new Set(expectedKernelStats);
+        for (const [key, value] of Object.entries(stats)) {
+          notYetFoundKernelStats.delete(key);
+          if (!kernelStats.has(key)) {
+            console.warn('Unexpected SwingSet kernel statistic', key);
+          }
+          kernelStats.set(key, value);
+        }
+        if (notYetFoundKernelStats.size) {
+          console.warn('Expected SwingSet kernel statistics not found', [
+            ...notYetFoundKernelStats,
+          ]);
+        }
+        break;
+      }
+      case 'cosmic-swingset-after-commit-stats': {
+        const dynamicCounterEntries = Object.entries(
+          dynamicAfterCommitStatsCounters,
+        );
+        for (const [slogKey, meta] of dynamicCounterEntries) {
+          const { namePrefix, options, keys } = meta;
+          meta.data = slogObj[slogKey] || {};
+          const newKeys = Object.keys(meta.data).filter(key => !keys.has(key));
+          for (const key of newKeys) {
+            keys.add(key);
+            const name = `${namePrefix}${key}`;
+            const gauge = otelMeter.createObservableUpDownCounter(
+              name,
+              options,
+            );
+            gauge.addCallback(observer => {
+              observer.observe(meta.data[key]);
+            });
+          }
+        }
+        break;
+      }
+      default:
+        break;
+    }
+  };
+  return Object.assign(slogSender, {
+    usesJsonObject: false,
+  });
+};

package/src/prometheus.js

@@ -0,0 +1,18 @@
+import { Fail } from '@endo/errors';
+
+import { getPrometheusMeterProvider } from './index.js';
+import { makeSlogSender as makeOtelMetricsSender } from './otel-metrics.js';
+
+/** @param {import('./index.js').MakeSlogSenderOptions & {otelMeterName?: string}} opts */
+export const makeSlogSender = async (opts = {}) => {
+  const { env, otelMeterName, serviceName } = opts;
+  if (!otelMeterName) throw Fail`OTel meter name is required`;
+  const otelMeterProvider = getPrometheusMeterProvider({
+    console,
+    env,
+    serviceName,
+  });
+  if (!otelMeterProvider) return;
+
+  return makeOtelMetricsSender({ ...opts, otelMeterName, otelMeterProvider });
+};

package/src/slog-sender-pipe-entrypoint.js

@@ -1,32 +1,34 @@
 /* eslint-env node */
+/**
+ * @file Run as a child process of {@link ./slog-sender-pipe.js} to isolate an
+ *   aggregate slog sender (@see {@link ./make-slog-sender.js}). Communicates
+ *   with its parent via Node.js IPC with advanced (structured clone)
+ *   serialization.
+ *   https://nodejs.org/docs/latest/api/child_process.html#advanced-serialization
+ */
+
 import '@endo/init';
 
 import anylogger from 'anylogger';
+import { Fail } from '@endo/errors';
 import { makeShutdown } from '@agoric/internal/src/node/shutdown.js';
 
 import { makeSlogSender } from './make-slog-sender.js';
 
 const logger = anylogger('slog-sender-pipe-entrypoint');
 
-/** @type {(msg: import('./slog-sender-pipe.js').SlogSenderPipeWaitReplies) => void} */
+/** @type {(msg: import('./slog-sender-pipe.js').PipeAPIReply) => void} */
 const send = Function.prototype.bind.call(process.send, process);
 
 /**
- * @typedef {object} InitMessage
- * @property {'init'} type
- * @property {import('./index.js').MakeSlogSenderOptions} options
- */
-/**
- * @typedef {object} SendMessage
- * @property {'send'} type
- * @property {object} obj
+ * @typedef {{type: 'init', options: import('./index.js').MakeSlogSenderOptions }} InitMessage
+ * @typedef {{type: 'flush' }} FlushMessage
+ * @typedef {{type: 'send', obj: Record<string, unknown> }} SendMessage
+ *
+ * @typedef {InitMessage | FlushMessage} PipeAPIResponsefulMessage
+ * @typedef {SendMessage} PipeAPIResponselessMessage
+ * @typedef {PipeAPIResponsefulMessage | PipeAPIResponselessMessage} PipeAPIMessage
  */
-/**
- * @typedef {object} FlushMessage
- * @property {'flush'} type
- */
-/** @typedef {InitMessage | FlushMessage} SlogSenderPipeWaitMessages */
-/** @typedef {SlogSenderPipeWaitMessages | SendMessage } SlogSenderPipeMessages */
 
 const main = async () => {
   /** @type {import('./index.js').SlogSender | undefined} */
@@ -44,9 +46,7 @@ const main = async () => {
 
   /** @param {import('./index.js').MakeSlogSenderOptions} opts */
   const init = async ({ env, ...otherOpts } = {}) => {
-    if (slogSender) {
-      assert.fail('Already initialized');
-    }
+    !slogSender || Fail`Already initialized`;
 
     slogSender = await makeSlogSender({
       ...otherOpts,
@@ -57,9 +57,7 @@ const main = async () => {
   };
 
   const flush = async () => {
-    if (!slogSender) {
-      assert.fail('No sender available');
-    }
+    if (!slogSender) throw Fail`No sender available`;
 
     await slogSender.forceFlush?.();
   };
@@ -77,56 +75,55 @@ const main = async () => {
     return AggregateError(sendErrors.splice(0));
   };
 
-  process.on(
-    'message',
-    /** @param {SlogSenderPipeMessages} msg */ msg => {
-      if (!msg || typeof msg !== 'object') {
-        logger.warn('received invalid message', msg);
-        return;
-      }
+  /** @param {PipeAPIMessage} msg */
+  const onMessage = msg => {
+    if (!msg || typeof msg !== 'object') {
+      logger.warn('Received invalid message', msg);
+      return;
+    }
 
-      switch (msg.type) {
-        case 'init': {
-          void init(msg.options).then(
-            hasSender => {
-              send({ type: 'initReply', hasSender });
-            },
-            error => {
-              send({ type: 'initReply', hasSender: false, error });
-            },
-          );
-          break;
-        }
-        case 'flush': {
-          void flush().then(
-            () => {
-              send({ type: 'flushReply', error: generateFlushError() });
-            },
-            error => {
-              send({ type: 'flushReply', error: generateFlushError(error) });
-            },
-          );
-          break;
-        }
-        case 'send': {
-          if (!slogSender) {
-            logger.warn('received send with no sender available');
-          } else {
-            try {
-              slogSender(msg.obj);
-            } catch (e) {
-              sendErrors.push(e);
-            }
+    switch (msg.type) {
+      case 'init': {
+        void init(msg.options).then(
+          hasSender => {
+            send({ type: 'initReply', hasSender });
+          },
+          error => {
+            send({ type: 'initReply', hasSender: false, error });
+          },
+        );
+        break;
+      }
+      case 'flush': {
+        void flush().then(
+          () => {
+            send({ type: 'flushReply', error: generateFlushError() });
+          },
+          error => {
+            send({ type: 'flushReply', error: generateFlushError(error) });
+          },
+        );
+        break;
+      }
+      case 'send': {
+        if (!slogSender) {
+          logger.warn('Received send with no sender available');
+        } else {
+          try {
+            slogSender(msg.obj);
+          } catch (e) {
+            sendErrors.push(e);
           }
-          break;
-        }
-        default: {
-          // @ts-expect-error exhaustive type check
-          logger.warn('received unknown message type', msg.type);
         }
+        break;
+      }
+      default: {
+        // @ts-expect-error exhaustive type check
+        logger.warn('Received unknown message type', msg.type);
       }
-    },
-  );
+    }
+  };
+  process.on('message', onMessage);
 };
 
 process.exitCode = 1;

package/src/slog-sender-pipe.js

@@ -1,7 +1,17 @@
+/**
+ * @file Export a `makeSlogSender` that spawns a
+ *   {@link ./slog-sender-pipe-entrypoint.js} child process to which it forwards
+ *   all slog entries via Node.js IPC with advanced (structured clone)
+ *   serialization.
+ *   https://nodejs.org/docs/latest/api/child_process.html#advanced-serialization
+ */
+
 import { fork } from 'child_process';
 import path from 'path';
+import { promisify } from 'util';
 import anylogger from 'anylogger';
 
+import { q, Fail } from '@endo/errors';
 import { makeQueue } from '@endo/stream';
 
 import { makeShutdown } from '@agoric/internal/src/node/shutdown.js';
@@ -10,6 +20,8 @@ const dirname = path.dirname(new URL(import.meta.url).pathname);
 
 const logger = anylogger('slog-sender-pipe');
 
+const sink = () => {};
+
 /**
  * @template {any[]} T
  * @template R
@@ -23,168 +35,118 @@ const withMutex = operation => {
   return async (...args) => {
     await mutex.get();
     const result = operation(...args);
-    mutex.put(
-      result.then(
-        () => {},
-        () => {},
-      ),
-    );
+    mutex.put(result.then(sink, sink));
     return result;
   };
 };
 
 /**
- * @typedef {object} SlogSenderInitReply
- * @property {'initReply'} type
- * @property {boolean} hasSender
- * @property {Error} [error]
+ * @template [P=unknown]
+ * @typedef {{ type: string, error?: Error } & P} PipeReply
  */
+
 /**
- * @typedef {object} SlogSenderFlushReply
- * @property {'flushReply'} type
- * @property {Error} [error]
+ * @typedef {{
+ *   init: {
+ *     message: import('./slog-sender-pipe-entrypoint.js').InitMessage;
+ *     reply: PipeReply<{ hasSender: boolean }>;
+ *   };
+ *   flush: {
+ *     message: import('./slog-sender-pipe-entrypoint.js').FlushMessage;
+ *     reply: PipeReply<{}>;
+ *   };
+ * }} SlogSenderPipeAPI
+ *
+ * @typedef {keyof SlogSenderPipeAPI} PipeAPICommand
+ * @typedef {SlogSenderPipeAPI[PipeAPICommand]["reply"]} PipeAPIReply
  */
-/** @typedef {SlogSenderInitReply | SlogSenderFlushReply} SlogSenderPipeWaitReplies */
 
-/** @param {import('.').MakeSlogSenderOptions} opts */
-export const makeSlogSender = async opts => {
+/** @param {import('.').MakeSlogSenderOptions} options */
+export const makeSlogSender = async options => {
   const { registerShutdown } = makeShutdown();
+
   const cp = fork(path.join(dirname, 'slog-sender-pipe-entrypoint.js'), [], {
-    stdio: ['inherit', 'inherit', 'inherit', 'ipc'],
+    stdio: ['ignore', 'inherit', 'inherit', 'ipc'],
     serialization: 'advanced',
   });
   // logger.log('done fork');
+  /** @type {(msg: Record<string, unknown> & {type: string}) => Promise<void>} */
+  const rawSend = promisify(cp.send.bind(cp));
+  const pipeSend = withMutex(rawSend);
 
-  const pipeSend = withMutex(
-    /**
-     * @template {{type: string}} T
-     * @param {T} msg
-     */
-    msg =>
-      /** @type {Promise<void>} */ (
-        new Promise((resolve, reject) => {
-          cp.send(msg, err => {
-            if (err) {
-              reject(err);
-            } else {
-              resolve();
-            }
-          });
-        })
-      ),
-  );
-
-  /**
-   * @typedef {{
-   *   init: {
-   *     message: import('./slog-sender-pipe-entrypoint.js').InitMessage;
-   *     reply: SlogSenderInitReply;
-   *   };
-   *   flush: {
-   *     message: import('./slog-sender-pipe-entrypoint.js').FlushMessage;
-   *     reply: SlogSenderFlushReply;
-   *   };
-   * }} SlogSenderWaitMessagesAndReplies
-   */
-
-  /** @typedef {keyof SlogSenderWaitMessagesAndReplies} SendWaitCommands */
-  /**
-   * @template {SlogSenderPipeWaitReplies} T
-   * @typedef {Omit<T, 'type' | 'error'>} ReplyPayload
-   */
-
-  /** @type {import('@endo/stream').AsyncQueue<SlogSenderPipeWaitReplies>} */
+  /** @type {import('@endo/stream').AsyncQueue<PipeAPIReply>} */
   const sendWaitQueue = makeQueue();
-  /** @type {SendWaitCommands | undefined} */
+  /** @type {PipeAPICommand | undefined} */
   let sendWaitType;
 
   const sendWaitReply = withMutex(
     /**
-     * @template {SendWaitCommands} T
+     * @template {PipeAPICommand} T
      * @param {T} type
-     * @param {Omit<SlogSenderWaitMessagesAndReplies[T]["message"], 'type'>} payload
-     * @returns {Promise<ReplyPayload<SlogSenderWaitMessagesAndReplies[T]["reply"]>>}
+     * @param {Omit<SlogSenderPipeAPI[T]["message"], 'type'>} payload
+     * @returns {Promise<Omit<SlogSenderPipeAPI[T]["reply"], keyof PipeReply>>}
      */
     async (type, payload) => {
-      !sendWaitType || assert.fail('Invalid mutex state');
+      !sendWaitType || Fail`Invalid mutex state`;
 
       const msg = { ...payload, type };
 
       sendWaitType = type;
-      return pipeSend(msg)
-        .then(async () => sendWaitQueue.get())
-        .then(
-          /** @param {SlogSenderWaitMessagesAndReplies[T]["reply"]} reply */ ({
-            type: replyType,
-            error,
-            ...rest
-          }) => {
-            replyType === `${type}Reply` ||
-              assert.fail(`Unexpected reply ${replyType}`);
-            if (error) {
-              throw error;
-            }
-            return rest;
-          },
-        )
-        .finally(() => {
-          sendWaitType = undefined;
-        });
-    },
-  );
-
-  cp.on(
-    'message',
-    /** @param { SlogSenderPipeWaitReplies } msg */
-    msg => {
-      // logger.log('received', msg);
-      if (
-        !msg ||
-        typeof msg !== 'object' ||
-        msg.type !== `${sendWaitType}Reply`
-      ) {
-        logger.warn('Received unexpected message', msg);
-        return;
+      await null;
+      try {
+        await pipeSend(msg);
+        /** @type {SlogSenderPipeAPI[T]["reply"]} */
+        const reply = await sendWaitQueue.get();
+        const { type: replyType, error, ...rest } = reply;
+        replyType === `${type}Reply` ||
+          Fail`Unexpected reply type ${q(replyType)}`;
+        if (error) throw error;
+        return rest;
+      } finally {
+        sendWaitType = undefined;
       }
-
-      sendWaitQueue.put(msg);
     },
   );
 
-  const flush = async () => sendWaitReply('flush', {});
-  /** @param {import('./index.js').MakeSlogSenderOptions} options */
-  const init = async options => sendWaitReply('init', { options });
+  /** @param {PipeReply} msg */
+  const onMessage = msg => {
+    // logger.log('received', msg);
+    if (!msg || msg.type !== `${sendWaitType}Reply`) {
+      logger.warn('Received unexpected message', msg);
+      return;
+    }
+
+    sendWaitQueue.put(msg);
+  };
+  cp.on('message', onMessage);
 
-  const send = obj => {
-    void pipeSend({ type: 'send', obj }).catch(() => {});
+  const flush = async () => {
+    await sendWaitReply('flush', {});
   };
 
   const shutdown = async () => {
     // logger.log('shutdown');
-    if (!cp.connected) {
-      return;
-    }
+    if (!cp.connected) return;
 
     await flush();
     cp.disconnect();
   };
   registerShutdown(shutdown);
 
-  const { hasSender } = await init(opts).catch(err => {
+  const { hasSender } = await sendWaitReply('init', { options }).catch(err => {
     cp.disconnect();
     throw err;
   });
-
   if (!hasSender) {
     cp.disconnect();
     return undefined;
   }
 
-  const slogSender = send;
+  const slogSender = obj => {
+    void pipeSend({ type: 'send', obj }).catch(sink);
+  };
   return Object.assign(slogSender, {
-    forceFlush: async () => {
-      await flush();
-    },
+    forceFlush: flush,
     shutdown,
     usesJsonObject: false,
   });