@agoric/telemetry 0.6.3-other-dev-3eb1a1d.0 → 0.6.3-other-dev-d15096d.0.d15096d

package/src/serialize-slog-obj.js

@@ -1,4 +1,32 @@
-export const serializeSlogObj = slogObj =>
-  JSON.stringify(slogObj, (_, arg) =>
-    typeof arg === 'bigint' ? Number(arg) : arg,
-  );
+const { hasOwn } = Object;
+
+const replacer = (_key, value) => {
+  switch (typeof value) {
+    case 'object': {
+      if (value instanceof Error) {
+        // Represent each error as a serialization-friendly
+        // { errorType, message, cause?, errors?, stack? } object
+        // (itself subject to recursive replacement, particularly in `cause` and
+        // `errors`).
+        const obj = { errorType: value.name, message: value.message };
+        if (hasOwn(value, 'cause')) obj.cause = value.cause;
+        // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+        // @ts-ignore TS2339 property "errors" is only on AggregateError
+        if (hasOwn(value, 'errors')) obj.errors = value.errors;
+        const stack = value.stack;
+        if (stack) obj.stack = stack;
+        return obj;
+      }
+      break;
+    }
+    case 'bigint':
+      // Represent each bigint as a JSON-serializable number, accepting the
+      // possible loss of precision.
+      return Number(value);
+    default:
+      break;
+  }
+  return value;
+};
+
+export const serializeSlogObj = slogObj => JSON.stringify(slogObj, replacer);

package/src/slog-file.js

@@ -1,7 +1,11 @@
 import { makeFsStreamWriter } from '@agoric/internal/src/node/fs-stream.js';
 import { serializeSlogObj } from './serialize-slog-obj.js';
 
-/** @param {import('./index.js').MakeSlogSenderOptions} opts */
+/**
+ * @import {MakeSlogSenderOptions} from './index.js';
+ */
+
+/** @param {MakeSlogSenderOptions} opts */
 export const makeSlogSender = async ({ env: { SLOGFILE } = {} } = {}) => {
   const stream = await makeFsStreamWriter(SLOGFILE);
 

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

@@ -1,35 +1,45 @@
 /* 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';
 
+/**
+ * @import {PipeAPIReply} from './slog-sender-pipe.js';
+ * @import {MakeSlogSenderOptions} from './index.js';
+ * @import {SlogSender} from './index.js';
+ */
+
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-ignore TODO remove when anylogger has types
 const logger = anylogger('slog-sender-pipe-entrypoint');
 
-/** @type {(msg: import('./slog-sender-pipe.js').SlogSenderPipeWaitReplies) => void} */
+/** @type {(msg: PipeAPIReply) => void} */
 const send = Function.prototype.bind.call(process.send, process);
 
 /**
- * @typedef {object} InitMessage
- * @property {'init'} type
- * @property {import('./index.js').MakeSlogSenderOptions} options
+ * @typedef {{type: 'init', options: 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} SendMessage
- * @property {'send'} type
- * @property {object} obj
- */
-/**
- * @typedef {object} FlushMessage
- * @property {'flush'} type
- */
-/** @typedef {InitMessage | FlushMessage} SlogSenderPipeWaitMessages */
-/** @typedef {SlogSenderPipeWaitMessages | SendMessage } SlogSenderPipeMessages */
 
 const main = async () => {
-  /** @type {import('./index.js').SlogSender | undefined} */
+  /** @type {SlogSender | undefined} */
   let slogSender;
 
   const sendErrors = [];
@@ -42,11 +52,9 @@ const main = async () => {
     process.disconnect?.();
   });
 
-  /** @param {import('./index.js').MakeSlogSenderOptions} opts */
+  /** @param {MakeSlogSenderOptions} opts */
   const init = async ({ env, ...otherOpts } = {}) => {
-    if (slogSender) {
-      assert.fail('Already initialized');
-    }
+    !slogSender || Fail`Already initialized`;
 
     slogSender = await makeSlogSender({
       ...otherOpts,
@@ -57,9 +65,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 +83,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(harden(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,190 +1,175 @@
+/**
+ * @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 { makePromiseKit } from '@endo/promise-kit';
 import { makeQueue } from '@endo/stream';
 
 import { makeShutdown } from '@agoric/internal/src/node/shutdown.js';
 
+/**
+ * @import {AsyncQueue} from '@endo/stream';
+ * @import {InitMessage} from './slog-sender-pipe-entrypoint.js';
+ * @import {FlushMessage} from './slog-sender-pipe-entrypoint.js';
+ * @import {MakeSlogSenderOptions} from './index.js';
+ */
+
 const dirname = path.dirname(new URL(import.meta.url).pathname);
 
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-ignore TODO remove when anylogger has types
 const logger = anylogger('slog-sender-pipe');
 
+const sink = () => {};
+
 /**
  * @template {any[]} T
  * @template R
  * @param {(...args: T) => Promise<R>} operation
  */
 const withMutex = operation => {
-  /** @type {import('@endo/stream').AsyncQueue<void>} */
+  /** @type {AsyncQueue<void>} */
   const mutex = makeQueue();
   mutex.put(Promise.resolve());
   /** @param {T} args */
   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: InitMessage;
+ *     reply: PipeReply<{ hasSender: boolean }>;
+ *   };
+ *   flush: {
+ *     message: 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 {MakeSlogSenderOptions} options */
+export const makeSlogSender = async options => {
+  const { env = {} } = 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',
+    env,
   });
   // logger.log('done fork');
 
-  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();
-            }
-          });
-        })
-      ),
-  );
+  const exitKit = makePromiseKit();
+  cp.on('error', error => {
+    // An exit event *might* be coming, so wait a tick.
+    setImmediate(() => exitKit.resolve({ error }));
+  });
+  cp.on('exit', (exitCode, signal) => {
+    exitKit.resolve({ exitCode, signal });
+  });
 
-  /**
-   * @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 {(msg: Record<string, unknown> & {type: string}) => Promise<void>} */
+  const rawSend = promisify(cp.send.bind(cp));
+  const pipeSend = withMutex(rawSend);
+
+  /** @type {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();
+    await exitKit.promise;
   };
   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,
   });

package/src/slog-to-otel.js

@@ -14,7 +14,13 @@ import {
 
 // diag.setLogger(new DiagConsoleLogger(), DiagLogLevel.VERBOSE);
 
-/** @import {Span, Link as SpanLink} from '@opentelemetry/api' */
+/**
+ * @import {Span, Link as SpanLink} from '@opentelemetry/api'
+ * @import {Tracer} from '@opentelemetry/api';
+ * @import {SwingSetCapData} from '@agoric/swingset-vat';
+ * @import {Message} from '@agoric/swingset-vat';
+ * @import {KernelSyscallObject} from '@agoric/swingset-vat';
+ */
 /** @import {SpanContext, SpanOptions} from '@opentelemetry/api' */
 
 const { assign } = Object;
@@ -76,7 +82,7 @@ export const floatSecondsToHiRes = sFloat => {
 };
 
 /**
- * @param {import('@opentelemetry/api').Tracer} tracer
+ * @param {Tracer} tracer
  * @param {Record<string, any>} [overrideAttrs]
  */
 export const makeSlogToOtelKit = (tracer, overrideAttrs = {}) => {
@@ -140,7 +146,7 @@ export const makeSlogToOtelKit = (tracer, overrideAttrs = {}) => {
   });
 
   /**
-   * @param {import('@agoric/swingset-vat').SwingSetCapData} data
+   * @param {SwingSetCapData} data
    * @returns {any}
    */
   const unserialize = data => {
@@ -156,12 +162,12 @@ export const makeSlogToOtelKit = (tracer, overrideAttrs = {}) => {
   /**
    * @typedef {{
    *   method: string;
-   *   args: import('@agoric/swingset-vat').SwingSetCapData;
+   *   args: SwingSetCapData;
    *   result?: string | undefined | null,
    * }} OldMessage
    */
   /** @typedef {ReturnType<typeof parseMsg>} ParsedMessage */
-  /** @param {import('@agoric/swingset-vat').Message | OldMessage} msg */
+  /** @param {Message | OldMessage} msg */
   const parseMsg = msg => {
     /** @type {string | symbol | null} */
     let method = null;
@@ -699,7 +705,7 @@ export const makeSlogToOtelKit = (tracer, overrideAttrs = {}) => {
         if (isReplaying) {
           break;
         }
-        /** @type {{ksc: import('@agoric/swingset-vat').KernelSyscallObject } & Record<string, unknown>} */
+        /** @type {{ksc: KernelSyscallObject } & Record<string, unknown>} */
         const { ksc, vsc: _1, ...attrs } = slogAttrs;
         if (!ksc) {
           break;

package/test/flight-recorder.test.js

@@ -12,27 +12,48 @@ const bufferTests = test.macro(
   /**
    *
    * @param {*} t
-   * @param {{makeBuffer: Function}} input
+   * @param {{makeBuffer: typeof makeSimpleCircularBuffer}} input
    */
   async (t, input) => {
     const BUFFER_SIZE = 512;
 
-    const { name: tmpFile, removeCallback } = tmp.fileSync();
-    const { readCircBuf, writeCircBuf } = await input.makeBuffer({
+    const { name: tmpFile, removeCallback } = tmp.fileSync({
+      discardDescriptor: true,
+    });
+    t.teardown(removeCallback);
+    const { fileHandle, readCircBuf, writeCircBuf } = await input.makeBuffer({
       circularBufferSize: BUFFER_SIZE,
       circularBufferFilename: tmpFile,
     });
-    const slogSender = makeSlogSenderFromBuffer({ writeCircBuf });
+    const realSlogSender = makeSlogSenderFromBuffer({
+      fileHandle,
+      writeCircBuf,
+    });
+    let wasShutdown = false;
+    const shutdown = () => {
+      if (wasShutdown) return;
+      wasShutdown = true;
+
+      return realSlogSender.shutdown();
+    };
+    t.teardown(shutdown);
+    // To verify lack of attempted mutation by the consumer, send only hardened
+    // entries.
+    /** @type {typeof realSlogSender} */
+    const slogSender = Object.assign(
+      (obj, serialized) => realSlogSender(harden(obj), serialized),
+      realSlogSender,
+    );
     slogSender({ type: 'start' });
     await slogSender.forceFlush();
     t.is(fs.readFileSync(tmpFile, { encoding: 'utf8' }).length, BUFFER_SIZE);
 
     const len0 = new Uint8Array(BigUint64Array.BYTES_PER_ELEMENT);
-    const { done: done0 } = readCircBuf(len0);
+    const { done: done0 } = await readCircBuf(len0);
     t.false(done0, 'readCircBuf should not be done');
     const dv0 = new DataView(len0.buffer);
     const buf0 = new Uint8Array(Number(dv0.getBigUint64(0)));
-    const { done: done0b } = readCircBuf(buf0, len0.byteLength);
+    const { done: done0b } = await readCircBuf(buf0, len0.byteLength);
     t.false(done0b, 'readCircBuf should not be done');
     const buf0Str = new TextDecoder().decode(buf0);
     t.is(buf0Str, `\n{"type":"start"}`, `start compare failed`);
@@ -51,12 +72,12 @@ const bufferTests = test.macro(
     let offset = 0;
     const len1 = new Uint8Array(BigUint64Array.BYTES_PER_ELEMENT);
     for (let i = 490; i < last; i += 1) {
-      const { done: done1 } = readCircBuf(len1, offset);
+      const { done: done1 } = await readCircBuf(len1, offset);
       offset += len1.byteLength;
       t.false(done1, `readCircBuf ${i} should not be done`);
       const dv1 = new DataView(len1.buffer);
       const buf1 = new Uint8Array(Number(dv1.getBigUint64(0)));
-      const { done: done1b } = readCircBuf(buf1, offset);
+      const { done: done1b } = await readCircBuf(buf1, offset);
       offset += buf1.byteLength;
       t.false(done1b, `readCircBuf ${i} should not be done`);
       const buf1Str = new TextDecoder().decode(buf1);
@@ -67,14 +88,24 @@ const bufferTests = test.macro(
       );
     }
 
-    const { done: done2 } = readCircBuf(len1, offset);
+    const { done: done2 } = await readCircBuf(len1, offset);
     t.assert(done2, `readCircBuf ${last} should be done`);
 
     slogSender(null, 'PRE-SERIALIZED');
     await slogSender.forceFlush();
     t.truthy(fs.readFileSync(tmpFile).includes('PRE-SERIALIZED'));
-    // console.log({ tmpFile });
-    removeCallback();
+
+    slogSender(null, 'PRE_SHUTDOWN');
+    const shutdownP = shutdown();
+    slogSender(null, 'POST_SHUTDOWN');
+    await shutdownP;
+    slogSender(null, 'SHUTDOWN_COMPLETED');
+
+    const finalContent = fs.readFileSync(tmpFile);
+
+    t.truthy(finalContent.includes('PRE_SHUTDOWN'));
+    t.falsy(finalContent.includes('POST_SHUTDOWN'));
+    t.falsy(finalContent.includes('SHUTDOWN_COMPLETED'));
   },
 );